Skip to content

Commit ee59c8c

Browse files
pawamoypawamoy
committed
docs: Improve global options documentation
1 parent aead1fd commit ee59c8c

1 file changed

Lines changed: 76 additions & 53 deletions

File tree

‎docs/usage/index.md‎

Lines changed: 76 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -75,69 +75,92 @@ plugins:
7575

7676
Some options are **global only**, and go directly under the handler's name.
7777

78-
- `import`: this option is used to import Sphinx-compatible objects inventories from other
79-
documentation sites. For example, you can import the standard library
80-
objects inventory like this:
78+
#### `import`
8179

82-
```yaml title="mkdocs.yml"
83-
plugins:
84-
- mkdocstrings:
85-
handlers:
86-
python:
87-
import:
88-
- https://docs.python-requests.org/en/master/objects.inv
89-
```
80+
This option is used to import Sphinx-compatible objects inventories from other
81+
documentation sites. For example, you can import the standard library
82+
objects inventory like this:
9083

91-
When importing an inventory, you enable automatic cross-references
92-
to other documentation sites like the standard library docs
93-
or any third-party package docs. Typically, you want to import
94-
the inventories of your project's dependencies, at least those
95-
that are used in the public API.
84+
```yaml title="mkdocs.yml"
85+
plugins:
86+
- mkdocstrings:
87+
handlers:
88+
python:
89+
import:
90+
- https://docs.python-requests.org/en/master/objects.inv
91+
```
9692

97-
See [*mkdocstrings*' documentation on inventories][inventories]
98-
for more details.
93+
When importing an inventory, you enable automatic cross-references
94+
to other documentation sites like the standard library docs
95+
or any third-party package docs. Typically, you want to import
96+
the inventories of your project's dependencies, at least those
97+
that are used in the public API.
9998

100-
[inventories]: https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories
99+
See [*mkdocstrings*' documentation on inventories][inventories]
100+
for more details.
101101

102-
NOTE: This global option is common to *all* handlers, however
103-
they might implement it differently (or not even implement it).
102+
[inventories]: https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories
104103

105-
- `paths`: this option is used to provide filesystem paths in which to search for Python modules.
106-
Non-absolute paths are computed as relative to MkDocs configuration file. Example:
104+
Additionally, the Python handler accepts a `domains` option in the import items,
105+
which allows to select the inventory domains to select.
106+
By default the Python handler only selects the `py` domain (for Python objects).
107+
You might find useful to also enable the [`std` domain][std domain]:
107108

108-
```yaml title="mkdocs.yml"
109-
plugins:
110-
- mkdocstrings:
111-
handlers:
112-
python:
113-
paths: [src] # search packages in the src folder
114-
```
109+
[std domain]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-standard-domain
115110

116-
More details at [Finding modules](#finding-modules).
117-
118-
- `load_external_modules`: this option allows resolving aliases (imports) to any external module.
119-
Modules are considered external when they are not part
120-
of the package your are injecting documentation for.
121-
Enabling this option will tell the handler to resolve aliases recursively
122-
when they are made public through the [`__all__`][__all__] variable.
123-
124-
WARNING: **Use with caution**
125-
This can load a *lot* of modules through [Griffe],
126-
slowing down your build or triggering errors that Griffe does not yet handle.
127-
**We recommend using the [`preload_modules`][] option instead**,
128-
which acts as an include-list rather than as include-all.
129-
130-
Example:
111+
```yaml title="mkdocs.yml"
112+
plugins:
113+
- mkdocstrings:
114+
handlers:
115+
python:
116+
import:
117+
- url: https://docs.python-requests.org/en/master/objects.inv
118+
domains: [std, py]
119+
```
131120

132-
```yaml title="mkdocs.yml"
133-
plugins:
134-
- mkdocstrings:
135-
handlers:
136-
python:
137-
load_external_modules: true
138-
```
121+
NOTE: The `import` option is common to *all* handlers, however
122+
they might implement it differently, or not even implement it.
123+
124+
#### `paths`
125+
126+
This option is used to provide filesystem paths in which to search for Python modules.
127+
Non-absolute paths are computed as relative to MkDocs configuration file. Example:
128+
129+
```yaml title="mkdocs.yml"
130+
plugins:
131+
- mkdocstrings:
132+
handlers:
133+
python:
134+
paths: [src] # search packages in the src folder
135+
```
136+
137+
More details at [Finding modules](#finding-modules).
138+
139+
#### `load_external_modules`
140+
141+
This option allows resolving aliases (imports) to any external module.
142+
Modules are considered external when they are not part
143+
of the package your are injecting documentation for.
144+
Enabling this option will tell the handler to resolve aliases recursively
145+
when they are made public through the [`__all__`][__all__] variable.
146+
147+
WARNING: **Use with caution**
148+
This can load a *lot* of modules through [Griffe],
149+
slowing down your build or triggering errors that Griffe does not yet handle.
150+
**We recommend using the [`preload_modules`][] option instead**,
151+
which acts as an include-list rather than as include-all.
152+
153+
Example:
154+
155+
```yaml title="mkdocs.yml"
156+
plugins:
157+
- mkdocstrings:
158+
handlers:
159+
python:
160+
load_external_modules: true
161+
```
139162

140-
[__all__]: https://docs.python.org/3/tutorial/modules.html#importing-from-a-package
163+
[__all__]: https://docs.python.org/3/tutorial/modules.html#importing-from-a-package
141164

142165
### Global/local options
143166

0 commit comments

Comments
 (0)