Skip to content

Commit 73292f5

Browse files
pawamoypawamoy
committed
docs: Sort options, document extra and extensions, add warnings on no-effect local options
1 parent 5ebeda6 commit 73292f5

File tree

3 files changed

+241
-145
lines changed

3 files changed

+241
-145
lines changed

‎docs/usage/configuration/docstrings.md

+3
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@ plugins:
2929
docstring_style: numpy
3030
```
3131
32+
WARNING: **The style is applied to the specified object only, not its members.** Local `docstring_style` options (in `:::` instructions) will only be applied to the specified object, and not its members. Instead of changing the style when rendering, we strongly recommend to *set the right style as early as possible*, for example by using the [auto-style](https://mkdocstrings.github.io/griffe/reference/docstrings/#auto-style) (sponsors only), or with a custom Griffe extension
33+
34+
3235
/// admonition | Preview
3336
type: preview
3437

‎docs/usage/configuration/general.md

+202-112
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,10 @@ and sometimes the collected data is inaccurate
1818
(depending on the tool that was used to compile the module)
1919
or too low-level/technical for API documentation.
2020

21+
See also [`force_inspection`](#force_inspection).
22+
23+
WARNING: **Packages are loaded only once.** When mkdocstrings-python collects data from a Python package (thanks to [Griffe](https://mkdocstrings.github.io/griffe/)), it collects *the entire package* and *caches it*. Next time an object from the same package is rendered, the package is retrieved from the cache and not collected again. The `allow_inspection` option will therefore only have an effect the first time a package is collected, and will do nothing for objects rendered afterwards.
24+
2125
```yaml title="in mkdocs.yml (global configuration)"
2226
plugins:
2327
- mkdocstrings:
@@ -55,6 +59,145 @@ plugins:
5559
////
5660
///
5761
62+
[](){#option-extensions}
63+
## `extensions`
64+
65+
- **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref> | <autoref identifier="dict" optional>dict</autoref>[<autoref identifier="str" optional>str</autoref>, <autoref identifier="dict" optional>dict</autoref>[<autoref identifier="str" optional>str</autoref>, <autoref identifier="typing.Any" optional>Any</autoref>]]]</code> :material-equal: `[]`{ title="default value" }**
66+
<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
67+
68+
The `extensions` option lets you enable [Griffe extensions](https://mkdocstrings.github.io/griffe/extensions/), which enhance or modify the data collected from Python sources (or compiled modules).
69+
70+
Elements in the list can be strings or dictionaries.
71+
72+
Strings denote the path to an extension module, like `griffe_typingdoc`, or to an extension class directly, like `griffe_typingdoc.TypingDocExtension`. When using a module path, all extensions within that module will be loaded and enabled. Strings can also be the path to a Python module, and a class name separated with `:`, like `scripts/griffe_extensions.py` or `scripts/griffe_extensions.py:MyExtension`.
73+
74+
Dictionaries have a single key, which is the module/class path (as a dot-separated qualifier or file path and colon-separated class name, like above), and its value is another dictionary specifying options that will be passed when to class constructors when instantiating extensions.
75+
76+
WARNING: **Packages are loaded only once.** When mkdocstrings-python collects data from a Python package (thanks to [Griffe](https://mkdocstrings.github.io/griffe/)), it collects *the entire package* and *caches it*. Next time an object from the same package is rendered, the package is retrieved from the cache and not collected again. Only the extensions specified the first time the package is loaded will be used. You cannot use a different set of extensions for specific objects rendered afterwards, and you cannot deactivate extensions for objects rendered afterwards either.
77+
78+
```yaml title="in mkdocs.yml (global configuration)"
79+
plugins:
80+
- mkdocstrings:
81+
handlers:
82+
python:
83+
options:
84+
extensions:
85+
- griffe_sphinx
86+
- griffe_pydantic: {schema: true}
87+
- scripts/exts.py:DynamicDocstrings:
88+
paths: [mypkg.mymod.myobj]
89+
```
90+
91+
```md title="or in docs/some_page.md (local configuration)"
92+
::: your_package.your_module.your_func
93+
options:
94+
extensions:
95+
- griffe_typingdoc
96+
```
97+
98+
[](){#option-extra}
99+
## `extra`
100+
101+
- **:octicons-package-24: Type [`dict`][] :material-equal: `{}`{ title="default value" }**
102+
<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
103+
104+
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][templates].
105+
106+
Local `extra` options will be merged into the global `extra` option:
107+
108+
```yaml title="in mkdocs.yml (global configuration)"
109+
plugins:
110+
- mkdocstrings:
111+
handlers:
112+
python:
113+
options:
114+
extra:
115+
hello: world
116+
```
117+
118+
```md title="in docs/some_page.md (local configuration)"
119+
::: your_package.your_module.your_func
120+
options:
121+
extra:
122+
foo: bar
123+
```
124+
125+
...will inject both `hello` and `foo` into the Jinja context when rendering `your_package.your_module.your_func`.
126+
127+
> WARNING: Previously, extra options were supported directly under the `options` key.
128+
>
129+
> ```yaml
130+
> plugins:
131+
> - mkdocstrings:
132+
> handlers:
133+
> python:
134+
> options:
135+
> hello: world
136+
> ```
137+
>
138+
> Now that we introduced optional validation of options and automatic JSON schema generation thanks to Pydantic, we require extra options to be put under `options.extra`. Extra options directly under `options` are still supported, but deprecated, and will emit deprecation warnings. Support will be removed in a future version of mkdocstrings-python.
139+
140+
[](){#option-find_stubs_package}
141+
## `find_stubs_package`
142+
143+
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
144+
<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
145+
146+
When looking for documentation specified in [autodoc instructions][autodoc syntax] (`::: identifier`), also look for
147+
the stubs package as defined in [PEP 561](https://peps.python.org/pep-0561/) if it exists. This is useful when
148+
most of your documentation is separately provided by such a package and not inline in your main package.
149+
150+
WARNING: **Packages are loaded only once.** When mkdocstrings-python collects data from a Python package (thanks to [Griffe](https://mkdocstrings.github.io/griffe/)), it collects *the entire package* and *caches it*. Next time an object from the same package is rendered, the package is retrieved from the cache and not collected again. The `find_stubs_package` option will therefore only have an effect the first time a package is collected, and will do nothing for objects rendered afterwards.
151+
152+
```yaml title="in mkdocs.yml (global configuration)"
153+
plugins:
154+
- mkdocstrings:
155+
handlers:
156+
python:
157+
options:
158+
find_stubs_package: true
159+
```
160+
161+
```md title="or in docs/some_page.md (local configuration)"
162+
::: your_package.your_module.your_func
163+
options:
164+
find_stubs_package: true
165+
```
166+
167+
```python title="your_package/your_module.py"
168+
169+
def your_func(a, b):
170+
# Function code
171+
...
172+
173+
# rest of your code
174+
```
175+
176+
```python title="your_package-stubs/your_module.pyi"
177+
178+
def your_func(a: int, b: str):
179+
"""
180+
<Function docstring>
181+
"""
182+
...
183+
184+
# rest of your code
185+
```
186+
187+
/// admonition | Preview
188+
type: preview
189+
190+
//// tab | With find_stubs_package
191+
<h2><code>your_func</code></h2>
192+
<p>Function docstring</p>
193+
////
194+
195+
//// tab | Without find_stubs_package
196+
<h2><code>your_func</code></h2>
197+
////
198+
///
199+
200+
[](){#option-force_inspection}
58201
## `force_inspection`
59202

60203
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -64,6 +207,8 @@ Whether to force inspecting modules (importing them) even if their source code i
64207

65208
This option is useful when you know that dynamic analysis (inspection) yields better results than static analysis. Do not use this blindly: the recommended approach is to write a Griffe extension that will improve extracted API data. See [How to selectively inspect objects](https://mkdocstrings.github.io/griffe/guide/users/how-to/selectively-inspect/).
66209

210+
See also [`allow_inspection`](#allow_inspection).
211+
67212
```yaml title="in mkdocs.yml (global configuration)"
68213
plugins:
69214
- mkdocstrings:
@@ -79,6 +224,63 @@ plugins:
79224
force_inspection: true
80225
```
81226

227+
WARNING: **Packages are loaded only once.** When mkdocstrings-python collects data from a Python package (thanks to [Griffe](https://mkdocstrings.github.io/griffe/)), it collects *the entire package* and *caches it*. Next time an object from the same package is rendered, the package is retrieved from the cache and not collected again. The `force_inspection` option will therefore only have an effect the first time a package is collected, and will do nothing for objects rendered afterwards.
228+
229+
[](){#option-preload_modules}
230+
## `preload_modules`
231+
232+
- **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] | None</code> :material-equal: `None`{ title="default value" }**
233+
<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
234+
235+
Pre-load modules that are not specified directly in [autodoc instructions][autodoc syntax] (`::: identifier`).
236+
It is useful when you want to render documentation for a particular member of an object,
237+
and this member is imported from another package than its parent.
238+
239+
For an imported member to be rendered,
240+
you need to add it to the [`__all__`][__all__] attribute of the importing module.
241+
The package from which the imported object originates must be accessible to the handler
242+
(see [Finding modules](../index.md#finding-modules)).
243+
244+
```yaml title="in mkdocs.yml (global configuration)"
245+
plugins:
246+
- mkdocstrings:
247+
handlers:
248+
python:
249+
options:
250+
preload_modules:
251+
- their_package
252+
```
253+
254+
```md title="or in docs/some_page.md (local configuration)"
255+
::: your_package.your_module
256+
options:
257+
preload_modules:
258+
- their_package
259+
```
260+
261+
```python title="your_package/your_module.py"
262+
from their_package.their_module import their_object
263+
264+
__all__ = ["their_object"]
265+
266+
# rest of your code
267+
```
268+
269+
/// admonition | Preview
270+
type: preview
271+
272+
//// tab | With preloaded modules
273+
<h2><code>your_module</code></h2>
274+
<p>Docstring of your module.</p>
275+
<h3><code>their_object</code></h3>
276+
<p>Docstring of their object.</p>
277+
////
278+
279+
//// tab | Without preloaded modules
280+
<h2><code>your_module</code></h2>
281+
<p>Docstring of your module.</p>
282+
////
283+
///
82284
## `show_bases`
83285

84286
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -245,115 +447,3 @@ def some_function():
245447
<p>Docstring of the function.</p>
246448
////
247449
///
248-
249-
## `preload_modules`
250-
251-
- **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] | None</code> :material-equal: `None`{ title="default value" }**
252-
<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
253-
254-
Pre-load modules that are not specified directly in [autodoc instructions][autodoc syntax] (`::: identifier`).
255-
It is useful when you want to render documentation for a particular member of an object,
256-
and this member is imported from another package than its parent.
257-
258-
For an imported member to be rendered,
259-
you need to add it to the [`__all__`][__all__] attribute of the importing module.
260-
The package from which the imported object originates must be accessible to the handler
261-
(see [Finding modules](../index.md#finding-modules)).
262-
263-
```yaml title="in mkdocs.yml (global configuration)"
264-
plugins:
265-
- mkdocstrings:
266-
handlers:
267-
python:
268-
options:
269-
preload_modules:
270-
- their_package
271-
```
272-
273-
```md title="or in docs/some_page.md (local configuration)"
274-
::: your_package.your_module
275-
options:
276-
preload_modules:
277-
- their_package
278-
```
279-
280-
```python title="your_package/your_module.py"
281-
from their_package.their_module import their_object
282-
283-
__all__ = ["their_object"]
284-
285-
# rest of your code
286-
```
287-
288-
/// admonition | Preview
289-
type: preview
290-
291-
//// tab | With preloaded modules
292-
<h2><code>your_module</code></h2>
293-
<p>Docstring of your module.</p>
294-
<h3><code>their_object</code></h3>
295-
<p>Docstring of their object.</p>
296-
////
297-
298-
//// tab | Without preloaded modules
299-
<h2><code>your_module</code></h2>
300-
<p>Docstring of your module.</p>
301-
////
302-
///
303-
304-
## `find_stubs_package`
305-
306-
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
307-
<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
308-
309-
When looking for documentation specified in [autodoc instructions][autodoc syntax] (`::: identifier`), also look for
310-
the stubs package as defined in [PEP 561](https://peps.python.org/pep-0561/) if it exists. This is useful when
311-
most of your documentation is separately provided by such a package and not inline in your main package.
312-
313-
```yaml title="in mkdocs.yml (global configuration)"
314-
plugins:
315-
- mkdocstrings:
316-
handlers:
317-
python:
318-
options:
319-
find_stubs_package: true
320-
```
321-
322-
```md title="or in docs/some_page.md (local configuration)"
323-
::: your_package.your_module.your_func
324-
options:
325-
find_stubs_package: true
326-
```
327-
328-
```python title="your_package/your_module.py"
329-
330-
def your_func(a, b):
331-
# Function code
332-
...
333-
334-
# rest of your code
335-
```
336-
337-
```python title="your_package-stubs/your_module.pyi"
338-
339-
def your_func(a: int, b: str):
340-
"""
341-
<Function docstring>
342-
"""
343-
...
344-
345-
# rest of your code
346-
```
347-
348-
/// admonition | Preview
349-
type: preview
350-
351-
//// tab | With find_stubs_package
352-
<h2><code>your_func</code></h2>
353-
<p>Function docstring</p>
354-
////
355-
356-
//// tab | Without find_stubs_package
357-
<h2><code>your_func</code></h2>
358-
////
359-
///

0 commit comments

Comments
 (0)