{"id":1560,"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.","status":"active","version":"2.0.3","language":"en","source_language":"en","source_url":"https://github.com/mkdocstrings/python","tags":["documentation","mkdocs","docstrings","python","api-docs"],"install":[{"cmd":"pip install mkdocs mkdocstrings mkdocstrings-python","lang":"bash","label":"Full installation"}],"dependencies":[{"reason":"The base static site generator for which mkdocstrings-python is an extension.","package":"mkdocs"},{"reason":"The core library that provides the plugin system and renders documentation based on handlers.","package":"mkdocstrings"},{"reason":"The underlying Python code parsing library, replacing 'griffe' from version 2.0.3 onwards.","package":"griffelib"}],"imports":[],"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."},"warnings":[{"fix":"Consult the migration guide or changelog for specific breaking changes and adapt your configuration/code accordingly.","message":"Version 2.0.0 removed previously deprecated code. Users upgrading from 1.x versions should review release notes for any functionality that might have been removed or changed.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure 'griffelib' is installed. If you have custom integrations, verify compatibility with 'griffelib' API.","message":"As of version 2.0.3, mkdocstrings-python depends on 'griffelib' instead of 'griffe'. While 'griffelib' is essentially 'griffe v2', this change indicates a significant internal refactor of the underlying parsing library. Custom plugins or integrations relying directly on 'griffe' internals might be affected.","severity":"breaking","affected_versions":">=2.0.3"},{"fix":"Install all three packages: `pip install mkdocs mkdocstrings mkdocstrings-python`.","message":"mkdocstrings-python is an extension. You must install `mkdocs` and `mkdocstrings` separately for it to function, in addition to `mkdocstrings-python` itself.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `plugins: [mkdocstrings]` to `mkdocs.yml` and ensure the `python` handler is configured, e.g., `plugins.mkdocstrings.handlers.python.paths`.","message":"mkdocstrings-python needs to be explicitly enabled and configured as a handler in your `mkdocs.yml` file under the `plugins` section for it to process Python documentation directives.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `plugins.mkdocstrings.handlers.python.paths` in `mkdocs.yml` correctly points to the directory containing your Python modules, or set your `PYTHONPATH` environment variable correctly before running `mkdocs build`.","message":"The documentation engine needs to locate your Python source code. Misconfiguration of the Python `paths` option (or `PYTHONPATH`) is a common cause of 'module not found' errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}