Skip to content

Commit 7b11ba8

Browse files
pawamoypawamoy
committed
docs: Update docs from insiders
1 parent 446d725 commit 7b11ba8

File tree

9 files changed

+391
-6
lines changed

9 files changed

+391
-6
lines changed

‎docs/insiders/changelog.md

+26
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,32 @@
22

33
## mkdocstrings-python Insiders
44

5+
### 1.8.3 <small>June 19, 2024</small> { id="1.8.3" }
6+
7+
- Update code for Griffe 0.46+ to avoid deprecation warnings
8+
9+
### 1.8.2 <small>May 09, 2024</small> { id="1.8.2" }
10+
11+
- Don't render cross-refs for default values when signatures aren't separated
12+
13+
### 1.8.1 <small>April 19, 2024</small> { id="1.8.1" }
14+
15+
- Render enumeration instance name instead of just "value", allowing proper cross-reference
16+
17+
### 1.8.0 <small>March 24, 2024</small> { id="1.8.0" }
18+
19+
- [Annotations modernization][modernize_annotations]
20+
21+
### 1.7.0 <small>March 24, 2024</small> { id="1.7.0" }
22+
23+
- [Class inheritance diagrams with Mermaid][show_inheritance_diagram]
24+
25+
### 1.6.0 <small>January 30, 2024</small> { id="1.6.0" }
26+
27+
- Render cross-references to parameters documentation in signatures and attribute values.
28+
- Add [`parameter_headings`][parameter_headings] option to render headings for parameters (enabling permalinks and ToC/inventory entries).
29+
- Render cross-references for default parameter values in signatures.
30+
531
### 1.5.1 <small>September 12, 2023</small> { id="1.5.1" }
632

733
- Prevent empty auto-summarized Methods section.

‎docs/insiders/goals.yml

+17-2
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,24 @@ goals:
1616
since: 2023/08/20
1717
- name: Automatic rendering of function signature overloads
1818
since: 2023/09/05
19+
- name: Parameter headings
20+
ref: /usage/configuration/headings/#parameter_headings
21+
since: 2024/01/30
22+
- name: Automatic cross-references to parameters
23+
ref: /usage/configuration/headings/#parameter_headings
24+
since: 2024/01/30
25+
- name: Automatic cross-references for default parameter values in signatures
26+
since: 2024/01/30
1927
1500:
2028
name: HyperLamp Navigation Tips
21-
features: []
29+
features:
30+
- name: Class inheritance diagrams with Mermaid
31+
ref: /usage/configuration/general/#show_inheritance_diagram
32+
since: 2024/03/24
33+
- name: Annotations modernization
34+
ref: /usage/configuration/signatures/#modernize_annotations
35+
since: 2024/03/24
2236
2000:
2337
name: FusionDrive Ejection Configuration
24-
features: []
38+
features:
39+
- name: Relative cross-references

‎docs/snippets/package/__init__.py

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
from importlib import metadata
2+
3+
def get_version(dist: str = "mkdocstrings-python") -> str:
4+
"""Get version of the given distribution.
5+
6+
Parameters:
7+
dist: A distribution name.
8+
9+
Returns:
10+
A version number.
11+
"""
12+
try:
13+
return metadata.version(dist)
14+
except metadata.PackageNotFoundError:
15+
return "0.0.0"
16+
17+
18+
current_version: str = get_version(dist="mkdocstrings-python")
19+
"""Current package version."""

‎docs/snippets/package/modern.py

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
from typing import Optional, Union, List
2+
3+
example: Optional[Union[int, List[int]]] = None

‎docs/usage/configuration/general.md

+85
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,91 @@ plugins:
9292
////
9393
///
9494

95+
## `show_inheritance_diagram`
96+
97+
[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } &mdash;
98+
[:octicons-tag-24: Insiders 1.7.0](../../insiders/changelog.md#1.7.0)
99+
100+
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
101+
<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
102+
103+
Show the inheritance diagram of a class using [Mermaid](https://mermaid.js.org/).
104+
105+
With this option enabled, an inheritance diagram (as a flowchart)
106+
will be displayed after a class signature.
107+
Each node will act as a cross-reference
108+
and will bring you to the relevant class' documentation
109+
when clicking on it.
110+
111+
It should work out of the box with [Material for MkDocs][].
112+
For other themes, you must include Mermaid's Javascript code manually:
113+
114+
```yaml title="mkdocs.yml"
115+
extra_javascript:
116+
- https://unpkg.com/[email protected]/dist/mermaid.min.js
117+
```
118+
119+
```yaml title="in mkdocs.yml (global configuration)"
120+
plugins:
121+
- mkdocstrings:
122+
handlers:
123+
python:
124+
options:
125+
show_inheritance_diagram: true
126+
```
127+
128+
```md title="or in docs/some_page.md (local configuration)"
129+
::: path.to.object
130+
options:
131+
show_inheritance_diagram: false
132+
```
133+
134+
/// admonition | Preview
135+
type: preview
136+
137+
With the following classes:
138+
139+
```python
140+
class SuperAbstract:
141+
"""Super abstract class."""
142+
class Mixin1:
143+
"""Mixin 1."""
144+
class Abstract(SuperAbstract, Mixin1):
145+
"""Abstract class."""
146+
class Mixin2A:
147+
"""Mixin 2A."""
148+
class Mixin2B(Mixin2A):
149+
"""Mixin 2B."""
150+
class Concrete(Abstract, Mixin2B):
151+
"""Concrete class."""
152+
class SuperConcrete(Concrete):
153+
"""Super concrete class."""
154+
```
155+
156+
The diagram for `SuperConcrete` will look like this:
157+
158+
```mermaid
159+
flowchart TD
160+
SuperConcrete[SuperConcrete]
161+
Concrete[Concrete]
162+
Abstract[Abstract]
163+
SuperAbstract[SuperAbstract]
164+
Mixin1[Mixin1]
165+
Mixin2B[Mixin2B]
166+
Mixin2A[Mixin2A]
167+
168+
Concrete --> SuperConcrete
169+
Abstract --> Concrete
170+
SuperAbstract --> Abstract
171+
Mixin1 --> Abstract
172+
Mixin2B --> Concrete
173+
Mixin2A --> Mixin2B
174+
```
175+
176+
*Nodes are not clickable in this example
177+
because these classes do not exist in our documentation.*
178+
///
179+
95180
## `show_source`
96181

97182
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**

‎docs/usage/configuration/headings.md

+123
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,129 @@ plugins:
5757
////
5858
///
5959
60+
## `parameter_headings`
61+
62+
[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } &mdash;
63+
[:octicons-tag-24: Insiders 1.6.0](../../insiders/changelog.md#1.6.0)
64+
65+
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
66+
<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
67+
68+
Whether to render headings for function/method parameters.
69+
70+
With this option enabled, each function/method parameter
71+
(including parameters of `__init__` methods merged in their parent class
72+
with the [`merge_init_into_class`][] option)
73+
gets a permalink, an entry in the Table of Contents,
74+
and an entry in the generated objects inventory.
75+
The permalink and inventory entry allow cross-references
76+
from internal and external pages.
77+
78+
The identifier used in the permalink and inventory is of the following form:
79+
`path.to.function(param_name)`. To manually cross-reference a parameter,
80+
you can therefore use this Markdown syntax:
81+
82+
```md
83+
- Class parameter: [`param`][package.module.Class(param)]
84+
- Method parameter: [`param`][package.module.Class.method(param)]
85+
- Function parameter: [`param`][package.module.function(param)]
86+
- Variadic positional parameters: [`*args`][package.module.function(*args)]
87+
- Variadic keyword parameters: [`**kwargs`][package.module.function(**kwargs)]
88+
```
89+
90+
Enabling this option along with [`signature_crossrefs`][] will automatically
91+
render cross-references to parameters in class/function/method signatures
92+
and attributes values.
93+
94+
```yaml title="in mkdocs.yml (global configuration)"
95+
plugins:
96+
- mkdocstrings:
97+
handlers:
98+
python:
99+
options:
100+
parameter_headings: false
101+
```
102+
103+
```md title="or in docs/some_page.md (local configuration)"
104+
::: path.to.module
105+
options:
106+
parameter_headings: true
107+
```
108+
109+
/// admonition | Preview: Cross-references
110+
type: preview
111+
112+
```md exec="on"
113+
::: package.get_version
114+
options:
115+
heading_level: 3
116+
parameter_headings: true
117+
docstring_section_style: list
118+
119+
::: package.current_version
120+
options:
121+
heading_level: 3
122+
line_length: 100
123+
```
124+
125+
///
126+
127+
/// admonition | Preview: Parameter sections
128+
type: preview
129+
130+
//// tab | Table style
131+
```md exec="on"
132+
::: package.get_version
133+
options:
134+
heading_level: 3
135+
show_root_heading: false
136+
show_root_toc_entry: false
137+
parameter_headings: true
138+
docstring_section_style: table
139+
show_docstring_returns: false
140+
show_docstring_description: false
141+
```
142+
////
143+
144+
//// tab | List style
145+
```md exec="on"
146+
::: package.get_version
147+
options:
148+
heading_level: 3
149+
show_root_heading: false
150+
show_root_toc_entry: false
151+
parameter_headings: true
152+
docstring_section_style: list
153+
show_docstring_returns: false
154+
show_docstring_description: false
155+
```
156+
////
157+
158+
//// tab | Spacy style
159+
```md exec="on"
160+
::: package.get_version
161+
options:
162+
heading_level: 3
163+
show_root_heading: false
164+
show_root_toc_entry: false
165+
parameter_headings: true
166+
docstring_section_style: spacy
167+
show_docstring_returns: false
168+
show_docstring_description: false
169+
```
170+
////
171+
///
172+
173+
/// admonition | Preview: Table of contents (with symbol types)
174+
type: preview
175+
176+
<code class="doc-symbol doc-symbol-toc doc-symbol-function"></code> get_version<br>
177+
<code class="doc-symbol doc-symbol-toc doc-symbol-parameter" style="margin-left: 16px;"></code> dist
178+
179+
To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
180+
181+
///
182+
60183
## `show_root_heading`
61184

62185
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**

‎docs/usage/configuration/signatures.md

+87
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,93 @@ plugins:
193193
////
194194
///
195195

196+
## `modernize_annotations`
197+
198+
[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } &mdash;
199+
[:octicons-tag-24: Insiders 1.8.0](../../insiders/changelog.md#1.8.0) &mdash;
200+
**This feature also requires
201+
[Griffe Insiders](https://mkdocstrings.github.io/griffe/insiders/)
202+
to be installed.**
203+
204+
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
205+
<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
206+
207+
Modernize annotations with latest features and PEPs of the Python language.
208+
209+
The Python language keeps evolving, and often library developers
210+
must continue to support a few minor versions of Python.
211+
Therefore they cannot use some features that were introduced
212+
in the latest versions.
213+
214+
Yet this doesn't mean they can't enjoy latest features in their docs:
215+
Griffe allows to "modernize" expressions, for example
216+
by replacing `typing.Union` with [PEP 604][pep-604] type unions `|`.
217+
Thanks to this, mkdocstrings' Python handler
218+
can automatically transform type annotations into their modern equivalent.
219+
This improves consistency in your docs, and shows users
220+
how to use your code with the latest features of the language.
221+
222+
[pep-604]: https://peps.python.org/pep-0604/
223+
224+
Modernizations applied:
225+
226+
- `typing.Dict[A, B]` becomes `dict[A, B]`
227+
- `typing.List[A]` becomes `list[A]`
228+
- `typing.Set[A]` becomes `set[A]`
229+
- `typing.Tuple[A]` becomes `tuple[A]`
230+
- `typing.Union[A, B]` becomes `A | B`
231+
- `typing.Optional[A]` becomes `A | None`
232+
233+
```yaml title="in mkdocs.yml (global configuration)"
234+
plugins:
235+
- mkdocstrings:
236+
handlers:
237+
python:
238+
options:
239+
modernize_annotations: true
240+
```
241+
242+
```md title="or in docs/some_page.md (local configuration)"
243+
::: path.to.object
244+
options:
245+
modernize_annotations: false
246+
```
247+
248+
/// admonition | Preview
249+
type: preview
250+
251+
```python
252+
--8<-- "docs/snippets/package/modern.py"
253+
```
254+
255+
//// tab | Unchanged annotations
256+
257+
```md exec="on"
258+
::: package.modern.example
259+
options:
260+
modernize_annotations: false
261+
show_symbol_type_heading: false
262+
show_labels: false
263+
```
264+
265+
////
266+
267+
//// tab | Modernized annotations
268+
269+
```md exec="on"
270+
::: package.modern.example
271+
options:
272+
modernize_annotations: true
273+
show_symbol_type_heading: false
274+
show_labels: false
275+
```
276+
277+
////
278+
279+
///
280+
281+
282+
196283
## `show_signature`
197284

198285
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**

0 commit comments

Comments
 (0)