1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
<h1 align="center">mkdocstrings-python-legacy</h1>
<p align="center">The legacy Python handler for <a href="https://github.com/mkdocstrings/mkdocstrings"><i>mkdocstrings</i></a>.</p>
<p align="center">
<a href="https://github.com/mkdocstrings/python-legacy/actions?query=workflow%3Aci">
<img alt="ci" src="https://github.com/mkdocstrings/python-legacy/workflows/ci/badge.svg" />
</a>
<a href="https://mkdocstrings.github.io/python-legacy/">
<img alt="documentation" src="https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat" />
</a>
<a href="https://pypi.org/project/mkdocstrings-python-legacy/">
<img alt="pypi version" src="https://img.shields.io/pypi/v/mkdocstrings-python-legacy.svg" />
</a>
<a href="https://gitpod.io/#https://github.com/mkdocstrings/python-legacy">
<img alt="gitpod" src="https://img.shields.io/badge/gitpod-workspace-blue.svg?style=flat" />
</a>
<a href="https://gitter.im/mkdocstrings/python-legacy">
<img alt="gitter" src="https://badges.gitter.im/join%20chat.svg" />
</a>
</p>
---
<p align="center"><img src="logo.png"></p>
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
<!-- TODO: update the GIF with a more recent screen capture. Maybe use mp4 instead -->
## 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.
|
