{"library":"mkdocstrings-python","title":"mkdocstrings-python","description":"mkdocstrings-python is a handler for the mkdocstrings library, specifically designed to parse and render Python API documentation within MkDocs-generated sites. It leverages the Griffe library for static analysis of Python code to extract docstrings and signatures. The current version is 2.0.3, and it maintains an active release cadence with frequent updates and bug fixes.","language":"python","status":"active","last_verified":"Sat Apr 11","install":{"commands":["pip install mkdocs mkdocstrings mkdocstrings-python"],"cli":null},"imports":[],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import os\nimport subprocess\nimport textwrap\n\ndef setup_mkdocs_project():\n    project_dir = \"my_docs_project\"\n    docs_dir = os.path.join(project_dir, \"docs\")\n    src_dir = os.path.join(project_dir, \"my_package\")\n\n    os.makedirs(docs_dir, exist_ok=True)\n    os.makedirs(src_dir, exist_ok=True)\n\n    # Create a dummy Python module to document\n    with open(os.path.join(src_dir, \"__init__.py\"), \"w\") as f:\n        f.write(textwrap.dedent(\"\"\"\n            \"\"\"A simple example package.\"\"\"\n            def greet(name: str) -> str:\n                \"\"\"Greets a person by name.\n\n                Args:\n                    name: The name of the person.\n\n                Returns:\n                    A greeting string.\n                \"\"\"\n                return f\"Hello, {name}!\"\n\n            class MyClass:\n                \"\"\"A simple example class.\"\"\"\n                def __init__(self, value: int):\n                    self.value = value\n\n                def get_value(self) -> int:\n                    \"\"\"Returns the stored value.\"\"\"\n                    return self.value\n        \"\"\"))\n\n    # Create mkdocs.yml\n    mkdocs_config = textwrap.dedent(f\"\"\"\n        site_name: My Docs\n        nav:\n          - Home: index.md\n        plugins:\n          - search\n          - mkdocstrings:\n              handlers:\n                python:\n                  paths:\n                    - {src_dir}\n        \"\"\")\n    with open(os.path.join(project_dir, \"mkdocs.yml\"), \"w\") as f:\n        f.write(mkdocs_config)\n\n    # Create index.md with mkdocstrings directive\n    index_md_content = textwrap.dedent(\"\"\"\n        # My Awesome Project\n\n        This is the documentation for my project.\n\n        ## API Reference\n\n        ::: my_package\n            options:\n              show_root_heading: false\n              show_root_full_path: false\n              show_object_full_path: false\n        \"\"\")\n    with open(os.path.join(docs_dir, \"index.md\" ), \"w\") as f:\n        f.write(index_md_content)\n\n    print(f\"MkDocs project '{project_dir}' created. Run 'cd {project_dir} && mkdocs build' to generate docs.\")\n    # Optionally, run mkdocs build here for a fully self-contained example\n    # try:\n    #     subprocess.run([\"mkdocs\", \"build\"], cwd=project_dir, check=True)\n    #     print(f\"Docs built successfully in '{os.path.join(project_dir, 'site')}'\")\n    # except subprocess.CalledProcessError as e:\n    #     print(f\"Error building docs: {e}\")\n\nif __name__ == \"__main__\":\n    setup_mkdocs_project()\n","lang":"python","description":"This quickstart creates a minimal MkDocs project structure, including an mkdocs.yml file configured to use mkdocstrings-python, a sample Python package, and a Markdown file with a `:::` directive. It demonstrates how to set up `mkdocstrings` to document Python code. Run the Python script, then navigate to the `my_docs_project` directory and execute `mkdocs build` to generate the documentation. The `paths` configuration under `plugins.mkdocstrings.handlers.python` is crucial for mkdocstrings-python to locate your source code.","tag":null,"tag_description":null,"last_tested":"2026-04-24","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]},"compatibility":null}