mkdocstrings-python-legacy is a Python handler for the mkdocstrings documentation generator. It facilitates the automatic collection of documentation from Python source code, relying on `pytkdocs` for data extraction. The handler supports popular docstring styles like Google, Numpydoc, and reStructuredText. While actively maintained, receiving updates as recently as May 2025, it is considered a legacy component, and users are strongly advised to migrate to the newer `mkdocstrings-python` handler, which offers improved functionality based on Griffe.
pip install mkdocstrings-python-legacyNo compatibility data collected yet for this library.
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.
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.
Upgrade your Python environment to version 3.9 or higher.
Avoid including a 'Methods' section directly within class-level Numpy-style docstrings. Refer to the `pytkdocs` documentation for full details or restructure your docstrings.
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`).
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.
Change cross-references from `[Title](path.to.object)` to `[Title][path.to.object]` or `[path.to.object][]` for automatic linking.
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.