mkdocstrings-python-legacy

Common errors

• Some objects are not rendered (they do not appear in the generated docs)

  cause Incorrect configuration of handler options, incorrectly formatted docstrings, or Python modules not being discoverable (e.g., missing `__init__.py` files or incorrect `paths` setting).
  fix Verify `mkdocs.yml` handler options. Ensure docstrings follow a supported style. Add `__init__.py` to directories containing modules. Configure the `paths` option in `mkdocs.yml` to point to your source code directory (e.g., `paths: [src]`). Run `mkdocs build -v` for verbose output.

• WARNING - Documentation file 'reference/parsers/docstrings.md' contains a link to 'reference/parsers/pytkdocs.parsers.docstrings.Section' which is not found in the documentation files.

  cause A cross-reference link in your Markdown uses parentheses `()` instead of brackets `[]`.
  fix Change cross-references from `[Title](path.to.object)` to `[Title][path.to.object]` or `[path.to.object][]` for automatic linking.

• mkdocstrings not finding module

  cause The Python handler cannot locate your Python packages or modules. This is often due to an incorrect `paths` configuration in `mkdocs.yml` or an improperly set `PYTHONPATH` environment variable.
  fix Explicitly configure the `paths` option under the `python` handler in your `mkdocs.yml` (e.g., `paths: [src]`). Ensure this path is relative to your `mkdocs.yml` file. Alternatively, ensure your `PYTHONPATH` environment variable correctly points to your project's source root or install your package in the environment.

Warnings

• deprecated This handler is considered legacy. Users are strongly recommended to migrate to the newer `mkdocstrings-python` handler for improved features and future compatibility, which is based on Griffe.
  Fix: Install `mkdocstrings-python` (e.g., `pip install mkdocstrings-python` or `pip install 'mkdocstrings[python]'`) and update your `mkdocs.yml` configuration to use the new handler.
• breaking Support for Python 3.8 has been dropped. Ensure you are running Python 3.9 or newer.
  Fix: Upgrade your Python environment to version 3.9 or higher.
• gotcha When using Numpy-style docstrings, having a 'Methods' section within a class docstring can lead to parsing issues.
  Fix: Avoid including a 'Methods' section directly within class-level Numpy-style docstrings. Refer to the `pytkdocs` documentation for full details or restructure your docstrings.
• gotcha For code blocks within docstrings or admonitions to render correctly, the `pymdownx.superfences` Markdown extension must be enabled. Newlines within docstring code blocks may also require escaping.
  Fix: Add `pymdownx.superfences` to your `markdown_extensions` in `mkdocs.yml`. For code blocks in docstrings, use raw strings (prefix with `r`) or escape newlines (e.g., `\n` instead of `\n`).

Install

• pip install mkdocstrings-python-legacy Direct Installation
• pip install 'mkdocstrings[python-legacy]' As mkdocstrings extra

Quickstart

To use mkdocstrings-python-legacy, first ensure it's installed. Then, configure your `mkdocs.yml` file to include `mkdocstrings` in the plugins section and specify the `python` handler within `mkdocstrings.handlers`. You'll need to define `paths` to indicate where your Python source code is located. Once configured, you can inject documentation into your Markdown files using the `:::` syntax, followed by the Python object's dotted path.

# mkdocs.yml
plugins:
  - mkdocstrings:
      handlers:
        python:
          paths: [src] # Adjust to your source code directory
          options:
            docstring_style: google # or numpy, restructured-text
            members: !docstrings_replace # Example: show only documented members

# docs/index.md
# ::: my_package.my_module