{"id":7415,"library":"mkdocstrings-python-legacy","title":"mkdocstrings-python-legacy","description":"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.","status":"active","version":"0.2.7","language":"python","source_language":"en","source_url":"https://github.com/mkdocstrings/python-legacy","tags":["documentation","mkdocs","mkdocstrings","python","legacy","autodoc"],"install":[{"cmd":"pip install mkdocstrings-python-legacy","lang":"bash","label":"Direct Installation"},{"cmd":"pip install 'mkdocstrings[python-legacy]'","lang":"bash","label":"As mkdocstrings extra"}],"dependencies":[{"reason":"Core dependency for integrating documentation generation.","package":"mkdocstrings","optional":false},{"reason":"Used by the legacy handler for collecting Python object documentation.","package":"pytkdocs","optional":false},{"reason":"Requires Python 3.9 or newer.","package":"Python","optional":false},{"reason":"Required for parsing Numpy-style docstrings.","package":"pytkdocs[numpy-style]","optional":true}],"imports":[],"quickstart":{"code":"# mkdocs.yml\nplugins:\n  - mkdocstrings:\n      handlers:\n        python:\n          paths: [src] # Adjust to your source code directory\n          options:\n            docstring_style: google # or numpy, restructured-text\n            members: !docstrings_replace # Example: show only documented members\n\n# docs/index.md\n# ::: my_package.my_module","lang":"yaml","description":"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."},"warnings":[{"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.","message":"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.","severity":"deprecated","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to version 3.9 or higher.","message":"Support for Python 3.8 has been dropped. Ensure you are running Python 3.9 or newer.","severity":"breaking","affected_versions":">=0.2.5"},{"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.","message":"When using Numpy-style docstrings, having a 'Methods' section within a class docstring can lead to parsing issues.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'2025':55 'activ':47 'advis':66 'autodoc':88 'automat':21 'base':80 'code':28 'collect':22 'compon':61 'consid':58 'data':33 'docstr':39 'document':16,24,83 'extract':34 'facilit':19 'function':79 'generat':17 'googl':42 'griff':82 'handler':12,36,75 'improv':78 'legaci':4,8,60,87 'like':41 'maintain':48 'may':54 'migrat':68 'mkdoc':84 'mkdocstr':2,6,15,73,85 'mkdocstrings-python':72 'mkdocstrings-python-legaci':1,5 'newer':71 'numpydoc':43 'offer':77 'popular':38 'python':3,7,11,26,74,86 'pytkdoc':31 'receiv':49 'recent':52 'reli':29 'restructuredtext':45 'sourc':27 'strong':65 'style':40 'support':37 'updat':50 'user':63","created_at":"2026-04-16T13:57:18.985849+00:00","updated_at":"2026-04-16T13:57:18.985849+00:00","problems":[{"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.","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).","error":"Some objects are not rendered (they do not appear in the generated docs)"},{"fix":"Change cross-references from `[Title](path.to.object)` to `[Title][path.to.object]` or `[path.to.object][]` for automatic linking.","cause":"A cross-reference link in your Markdown uses parentheses `()` instead of brackets `[]`.","error":"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."},{"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.","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.","error":"mkdocstrings not finding module"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://mkdocstrings.github.io/python-legacy","github":"https://github.com/mkdocstrings/python-legacy","docs":"https://mkdocstrings.github.io/python-legacy","changelog":"https://mkdocstrings.github.io/python-legacy/changelog","pypi":"https://pypi.org/project/mkdocstrings-python-legacy/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-16","next_check":"2026-07-15","install_tag":null}}