Skip to content

Commit b4959f4

Browse files
pawamoypawamoy
committed
feat: Update for latest mkdocstrings
1 parent 451735d commit b4959f4

18 files changed

Lines changed: 933 additions & 96 deletions

File tree

‎copier.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ _jinja_extensions:
1212
- extensions.py:GitExtension
1313
- extensions.py:SlugifyExtension
1414
- extensions.py:GitHubIDsforGiscusExtension
15+
- extensions.py:ContextUpdater
1516
_skip_if_exists:
1617
- CHANGELOG.md
1718
- docs/insiders/changelog.md

‎extensions.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,3 +98,10 @@ def hook(self, context):
9898
else:
9999
self.category_id = process.stdout.strip() or self.category_placeholder
100100
context["giscus_discussion_category_id"] = self.category_id
101+
102+
103+
class ContextUpdater(ContextHook):
104+
def hook(self, context):
105+
if context["_copier_phase"] == "prompt":
106+
return
107+
context["handler_class_name"] = context["language"].title().replace(" ", "")

‎project/docs/reference/api.md.jinja‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,4 @@ hide:
44
- navigation
55
---
66

7-
# ::: {{ python_package_import_name }}
7+
# ::: mkdocstrings_handlers.{{ python_package_import_name }}

‎project/docs/usage/configuration/general.md.jinja‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# General options
2+
3+
[](){ #option-extra }
4+
## `extra`
5+
6+
- **:octicons-package-24: Type [`dict`][] :material-equal: `{}`{ title="default value" }**
7+
8+
The `extra` option lets you inject additional variables into the Jinja context used when rendering templates. You can then use this extra context in your overridden templates.
9+
10+
Local `extra` options will be merged into the global `extra` option:
11+
12+
```yaml title="in mkdocs.yml (global configuration)"
13+
plugins:
14+
- mkdocstrings:
15+
handlers:
16+
{{ language | slugify }}:
17+
options:
18+
extra:
19+
hello: world
20+
```
21+
22+
```md title="in docs/some_page.md (local configuration)"
23+
::: your_package.your_module.your_func
24+
options:
25+
extra:
26+
foo: bar
27+
```
28+
29+
...will inject both `hello` and `foo` into the Jinja context when rendering `your_package.your_module.your_func`.

‎project/docs/usage/configuration/headings.md.jinja‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# Headings options
2+
3+
[](){ #option-heading }
4+
## `heading`
5+
6+
- **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }**
7+
8+
A custom string to use as the heading of the root object (i.e. the object specified directly after the identifier `:::`). This will override the default heading generated by the plugin. See also the [`toc_label` option][option-toc_label].
9+
10+
WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default heading for all objects. It is recommended to use it only in specific cases where you want to override the heading for a specific object.
11+
12+
```md title="in docs/some_page.md (local configuration)"
13+
::: path.to.module
14+
options:
15+
heading: "My fancy module"
16+
```
17+
18+
[](){ #option-heading_level }
19+
## `heading_level`
20+
21+
- **:octicons-package-24: Type [`int`][] :material-equal: `2`{ title="default value" }**
22+
23+
The initial heading level to use.
24+
25+
When injecting documentation for an object,
26+
the object itself and its members are rendered.
27+
For each layer of objects, we increase the heading level by 1.
28+
29+
The initial heading level will be used for the first layer.
30+
If you set it to 3, then headings will start with `<h3>`.
31+
32+
```yaml title="in mkdocs.yml (global configuration)"
33+
plugins:
34+
- mkdocstrings:
35+
handlers:
36+
{{ language | slugify }}:
37+
options:
38+
heading_level: 2
39+
```
40+
41+
```md title="or in docs/some_page.md (local configuration)"
42+
::: path.to.module
43+
options:
44+
heading_level: 3
45+
```
46+
47+
/// admonition | Preview
48+
type: preview
49+
50+
//// tab | With level 3 and root heading
51+
<h3><code>module</code> (3)</h3>
52+
<p>Docstring of the module.</p>
53+
<h4><code>ClassA</code> (4)</h4>
54+
<p>Docstring of class A.</p>
55+
<h4><code>ClassB</code> (4)</h4>
56+
<p>Docstring of class B.</p>
57+
<h5><code>method_1</code> (5)</h5>
58+
<p>Docstring of the method.</p>
59+
////
60+
61+
//// tab | With level 3, without root heading
62+
<p>Docstring of the module.</p>
63+
<h3><code>ClassA</code> (3)</h3>
64+
<p>Docstring of class A.</p>
65+
<h3><code>ClassB</code> (3)</h3>
66+
<p>Docstring of class B.</p>
67+
<h4><code>method_1</code> (4)</h4>
68+
<p>Docstring of the method.</p>
69+
////
70+
///
71+
72+
73+
[](){ #option-show_symbol_type_heading }
74+
## `show_symbol_type_heading`
75+
76+
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
77+
78+
Show the symbol type in headings.
79+
80+
This option will prefix headings with
81+
<code class="doc-symbol doc-symbol-attribute"></code>,
82+
<code class="doc-symbol doc-symbol-function"></code>,
83+
<code class="doc-symbol doc-symbol-method"></code>,
84+
<code class="doc-symbol doc-symbol-class"></code> or
85+
<code class="doc-symbol doc-symbol-module"></code> types.
86+
See also [`show_symbol_type_toc`][show_symbol_type_toc].
87+
88+
To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
89+
90+
```yaml title="in mkdocs.yml (global configuration)"
91+
plugins:
92+
- mkdocstrings:
93+
handlers:
94+
{{ language | slugify }}:
95+
options:
96+
show_symbol_type_heading: true
97+
```
98+
99+
```md title="or in docs/some_page.md (local configuration)"
100+
::: package.module
101+
options:
102+
show_symbol_type_heading: false
103+
```
104+
105+
/// admonition | Preview
106+
type: preview
107+
108+
//// tab | With symbol type in headings
109+
<h1><code class="doc-symbol doc-symbol-module"></code> <code>module</code></h1>
110+
<p>Docstring of the module.</p>
111+
<h2><code class="doc-symbol doc-symbol-attribute"></code> <code>attribute</code></h2>
112+
<p>Docstring of the module attribute.</p>
113+
<h2><code class="doc-symbol doc-symbol-function"></code> <code>function</code></h2>
114+
<p>Docstring of the function.</p>
115+
<h2><code class="doc-symbol doc-symbol-class"></code> <code>Class</code></h2>
116+
<p>Docstring of the class.</p>
117+
<h3><code class="doc-symbol doc-symbol-method"></code> <code>method</code></h3>
118+
<p>Docstring of the method.</p>
119+
////
120+
121+
//// tab | Without symbol type in headings
122+
<h1><code>module</code></h1>
123+
<p>Docstring of the module.</p>
124+
<h2><code>attribute</code></h2>
125+
<p>Docstring of the module attribute.</p>
126+
<h2><code>function</code></h2>
127+
<p>Docstring of the function.</p>
128+
<h2><code>Class</code></h2>
129+
<p>Docstring of the class.</p>
130+
<h3><code>method</code></h3>
131+
<p>Docstring of the method.</p>
132+
////
133+
///
134+
135+
[](){ #option-show_symbol_type_toc }
136+
## `show_symbol_type_toc`
137+
138+
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
139+
140+
Show the symbol type in the Table of Contents.
141+
142+
This option will prefix items in the ToC with
143+
<code class="doc-symbol doc-symbol-attribute"></code>,
144+
<code class="doc-symbol doc-symbol-function"></code>,
145+
<code class="doc-symbol doc-symbol-method"></code>,
146+
<code class="doc-symbol doc-symbol-class"></code> or
147+
<code class="doc-symbol doc-symbol-module"></code> types.
148+
See also [`show_symbol_type_heading`][show_symbol_type_heading].
149+
150+
To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
151+
152+
```yaml title="in mkdocs.yml (global configuration)"
153+
plugins:
154+
- mkdocstrings:
155+
handlers:
156+
{{ language | slugify }}:
157+
options:
158+
show_symbol_type_toc: true
159+
```
160+
161+
```md title="or in docs/some_page.md (local configuration)"
162+
::: package.module
163+
options:
164+
show_symbol_type_toc: false
165+
```
166+
167+
/// admonition | Preview
168+
type: preview
169+
170+
//// tab | With symbol type in ToC
171+
<ul style="list-style: none;">
172+
<li><code class="doc-symbol doc-symbol-module"></code> module</li>
173+
<li><code class="doc-symbol doc-symbol-attribute"></code> attribute</li>
174+
<li><code class="doc-symbol doc-symbol-function"></code> function</li>
175+
<li><code class="doc-symbol doc-symbol-class"></code> Class
176+
<ul style="list-style: none;">
177+
<li><code class="doc-symbol doc-symbol-method"></code> method</li>
178+
</ul>
179+
</li>
180+
</ul>
181+
////
182+
183+
//// tab | Without symbol type in ToC
184+
<ul style="list-style: none;">
185+
<li>module</li>
186+
<li>attribute</li>
187+
<li>function</li>
188+
<li>Class
189+
<ul style="list-style: none;">
190+
<li>method</li>
191+
</ul>
192+
</li>
193+
</ul>
194+
////
195+
///
196+
197+
[](){ #option-toc_label }
198+
## `toc_label`
199+
200+
- **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }**
201+
202+
A custom string to use as the label in the Table of Contents for the root object (i.e. the one specified directly after the identifier `:::`). This will override the default label generated by the plugin. See also the [`heading` option][option-heading].
203+
204+
WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default label for all objects. It is recommended to use it only in specific cases where you want to override the label for a specific object.
205+
206+
NOTE: **Use with/without `heading`.** If you use this option without specifying a custom `heading`, the default heading will be used in the page, but the label in the Table of Contents will be the one you specified. By providing both an option for `heading` and `toc_label`, we leave the customization entirely up to you.
207+
208+
```md title="in docs/some_page.md (local configuration)"
209+
::: path.to.module
210+
options:
211+
heading: "My fancy module"
212+
toc_label: "My fancy module"
213+
```

‎project/docs/usage/configuration/index.md.jinja‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Configuration
2+
3+
[](){ #setting-options }
4+
### Global/local options
5+
6+
The other options can be used both globally *and* locally, under the `options` key.
7+
For example, globally:
8+
9+
```yaml title="mkdocs.yml"
10+
plugins:
11+
- mkdocstrings:
12+
handlers:
13+
python:
14+
options:
15+
do_something: true
16+
```
17+
18+
...and locally, overriding the global configuration:
19+
20+
```md title="docs/some_page.md"
21+
::: package.module.class
22+
options:
23+
do_something: false
24+
```
25+
26+
These options affect how the documentation is collected from sources and rendered.
27+
See the following tables summarizing the options, and get more details for each option
28+
in the following pages:
29+
30+
- [General options](general.md): various options that do not fit in the other categories
31+
- [Headings options](headings.md): options related to headings and the table of contents
32+
(or sidebar, depending on the theme used)

0 commit comments

Comments
 (0)