mkdocstrings-python

Common errors

• ModuleNotFoundError: No module named 'mkdocstrings_handlers'

  cause The `mkdocstrings-python` package, which provides the Python handler, is not installed or not accessible in the current Python environment where MkDocs is run.
  fix Ensure `mkdocstrings-python` is installed in the correct environment: `pip install mkdocstrings-python`.

• ERROR - Object 'your_package.your_module' was not found

  cause Mkdocstrings or its underlying Griffe parser could not locate the specified Python object, module, class, or function. This often happens due to incorrect paths, the Python package not being on the Python path, or missing `__init__.py` files in subdirectories.
  fix Verify that 'your_package.your_module' is the correct dotted path to an existing and importable Python object. Ensure your project's root directory or the directory containing the package is added to the `paths` option in `mkdocs.yml` under the `python` handler, for example: `plugins: mkdocstrings: handlers: python: paths: [src]`. Also, confirm all relevant directories have `__init__.py` files, especially if it's a non-namespace package.

• Warning: could not find cross-reference target

  cause This warning occurs when Mkdocstrings attempts to create a cross-reference (link) to an identifier that it cannot resolve within the generated documentation or its loaded inventories. This could be due to a typo in the cross-reference, the target object not being documented, or a missing inventory import.
  fix Check the spelling of the cross-reference identifier. Ensure the referenced object is actually being documented by `mkdocstrings-python`. If referencing an external project, confirm its inventory is correctly imported in `mkdocs.yml`. For false positives, wrap the text in backticks (` `) to prevent mkdocstrings from trying to process it as a cross-reference.

• AttributeError: module 'mkdocstrings_handlers.python' has no attribute 'get_handler'

  cause This error typically indicates an incompatibility or corruption in the installed `mkdocstrings` and `mkdocstrings-python` packages, often due to mismatched versions or an unclean environment, particularly when dealing with legacy versions or migration.
  fix Try reinstalling `mkdocstrings` and `mkdocstrings-python` in a clean virtual environment: `pip uninstall mkdocstrings mkdocstrings-python && pip install mkdocstrings mkdocstrings-python`. If using a dependency manager like Poetry or PDM, ensure dependencies are properly synchronized (e.g., `poetry install` or `pdm sync`).

Warnings

• breaking 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.
  Fix: Consult the migration guide or changelog for specific breaking changes and adapt your configuration/code accordingly.
• breaking 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.
  Fix: Ensure 'griffelib' is installed. If you have custom integrations, verify compatibility with 'griffelib' API.
• gotcha mkdocstrings-python is an extension. You must install `mkdocs` and `mkdocstrings` separately for it to function, in addition to `mkdocstrings-python` itself.
  Fix: Install all three packages: `pip install mkdocs mkdocstrings mkdocstrings-python`.
• gotcha 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.
  Fix: Add `plugins: [mkdocstrings]` to `mkdocs.yml` and ensure the `python` handler is configured, e.g., `plugins.mkdocstrings.handlers.python.paths`.
• gotcha 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.
  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`.
• gotcha The Python interpreter encountered a syntax error in your source code. `mkdocstrings-python` relies on valid Python syntax to parse and extract documentation. This error typically indicates an issue within your Python modules rather than `mkdocstrings-python` itself.
  Fix: Carefully review the specified file and line number for syntax errors. Use a Python linter or run the file directly with `python your_module.py` to diagnose basic syntax issues. Ensure the file is correctly encoded (e.g., UTF-8) and does not contain invisible problematic characters.
• breaking The test script failed with a `SyntaxError` in `/script.py`, line 15, preventing the evaluation of library behavior. This indicates an issue with the test script itself, not necessarily the library.
  Fix: Inspect and correct the Python syntax error in `/script.py` at the specified line. Ensure the test script is compatible with the Python 3.13 environment.

Install

• pip install mkdocs mkdocstrings mkdocstrings-python Full installation

Quickstart

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.

import os
import subprocess
import textwrap

def setup_mkdocs_project():
    project_dir = "my_docs_project"
    docs_dir = os.path.join(project_dir, "docs")
    src_dir = os.path.join(project_dir, "my_package")

    os.makedirs(docs_dir, exist_ok=True)
    os.makedirs(src_dir, exist_ok=True)

    # Create a dummy Python module to document
    with open(os.path.join(src_dir, "__init__.py"), "w") as f:
        f.write(textwrap.dedent("""
            """A simple example package."""
            def greet(name: str) -> str:
                """Greets a person by name.

                Args:
                    name: The name of the person.

                Returns:
                    A greeting string.
                """
                return f"Hello, {name}!"

            class MyClass:
                """A simple example class."""
                def __init__(self, value: int):
                    self.value = value

                def get_value(self) -> int:
                    """Returns the stored value."""
                    return self.value
        """))

    # Create mkdocs.yml
    mkdocs_config = textwrap.dedent(f"""
        site_name: My Docs
        nav:
          - Home: index.md
        plugins:
          - search
          - mkdocstrings:
              handlers:
                python:
                  paths:
                    - {src_dir}
        """)
    with open(os.path.join(project_dir, "mkdocs.yml"), "w") as f:
        f.write(mkdocs_config)

    # Create index.md with mkdocstrings directive
    index_md_content = textwrap.dedent("""
        # My Awesome Project

        This is the documentation for my project.

        ## API Reference

        ::: my_package
            options:
              show_root_heading: false
              show_root_full_path: false
              show_object_full_path: false
        """)
    with open(os.path.join(docs_dir, "index.md" ), "w") as f:
        f.write(index_md_content)

    print(f"MkDocs project '{project_dir}' created. Run 'cd {project_dir} && mkdocs build' to generate docs.")
    # Optionally, run mkdocs build here for a fully self-contained example
    # try:
    #     subprocess.run(["mkdocs", "build"], cwd=project_dir, check=True)
    #     print(f"Docs built successfully in '{os.path.join(project_dir, 'site')}'")
    # except subprocess.CalledProcessError as e:
    #     print(f"Error building docs: {e}")

if __name__ == "__main__":
    setup_mkdocs_project()