https://github.com/mkdocstrings/python-legacy

A legacy Python handler for mkdocstrings.
https://github.com/mkdocstrings/python-legacy

autodoc documentation mkdocs mkdocstrings mkdocstrings-handler python python-documentation

Last synced: about 1 month ago
JSON representation

A legacy Python handler for mkdocstrings.

• Host: GitHub
• URL: https://github.com/mkdocstrings/python-legacy
• Owner: mkdocstrings
• License: isc
• Created: 2021-12-17T22:11:34.000Z (almost 3 years ago)
• Default Branch: main
• Last Pushed: 2023-12-06T10:36:17.000Z (12 months ago)
• Last Synced: 2024-04-23T10:45:31.301Z (7 months ago)
• Topics: autodoc, documentation, mkdocs, mkdocstrings, mkdocstrings-handler, python, python-documentation
• Language: Python
• Homepage: https://mkdocstrings.github.io/python-legacy
• Size: 1.05 MB
• Stars: 3
• Watchers: 3
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        
mkdocstrings-python-legacy


The legacy Python handler for mkdocstrings.




  

    

  

  

    

  

  

    

  

  

    

  

  

    

  



---



WARNING: We suggest using the new handler instead:

[mkdocstrings-python](https://mkdocstrings.github.io/python/).

## Installation

You can install this handler as a *mkdocstrings* extra:

```toml title="pyproject.toml"

# PEP 621 dependencies declaration

# adapt to your dependencies manager

[project]

dependencies = [

    "mkdocstrings[python-legacy]>=0.18",

]

```

You can also explicitely depend on the handler:

```toml title="pyproject.toml"

# PEP 621 dependencies declaration

# adapt to your dependencies manager

[project]

dependencies = [

    "mkdocstrings-python-legacy",

]

```

## Preview

![mkdocstrings_python_gif](https://user-images.githubusercontent.com/3999221/77157838-7184db80-6aa2-11ea-9f9a-fe77405202de.gif)

## Features

- **Data collection from source code**: collection of the object-tree and the docstrings is done thanks to

  [pytkdocs](https://github.com/mkdocstrings/pytkdocs).

- **Support for type annotations:** pytkdocs collects your type annotations and *mkdocstrings* uses them

  to display parameters types or return types. 

- **Recursive documentation of Python objects:** just use the module dotted-path as identifier, and you get the full

  module docs. You don't need to inject documentation for each class, function, etc.

- **Support for documented attributes:** attributes (variables) followed by a docstring (triple-quoted string) will

  be recognized by Griffe in modules, classes and even in `__init__` methods.

- **Multiple docstring-styles support:** common support for Google-style, Numpydoc-style,

  and Sphinx-style docstrings.

- **Admonition support in Google docstrings:** blocks like `Note:` or `Warning:` will be transformed

  to their [admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) equivalent.

  *We do not support nested admonitions in docstrings!*

- **Every object has a TOC entry:** we render a heading for each object, meaning *MkDocs* picks them into the Table

  of Contents, which is nicely display by the Material theme. Thanks to *mkdocstrings* cross-reference ability,

  you can reference other objects within your docstrings, with the classic Markdown syntax:

  `[this object][package.module.object]` or directly with `[package.module.object][]`

- **Source code display:** *mkdocstrings* can add a collapsible div containing the highlighted source code

  of the Python object.