| 1 |
# Usage |
| 2 |
|
| 3 |
## Autodoc syntax |
| 4 |
|
| 5 |
*mkdocstrings* works by processing special expressions in your Markdown files. |
| 6 |
|
| 7 |
The syntax is as follows: |
| 8 |
|
| 9 |
```md |
| 10 |
::: identifier |
| 11 |
YAML block |
| 12 |
``` |
| 13 |
|
| 14 |
> NOTE: **Resources on YAML.** |
| 15 |
> YAML can sometimes be a bit tricky, particularly on indentation. |
| 16 |
> Here are some resources that other users found useful to better |
| 17 |
> understand YAML's peculiarities. |
| 18 |
> |
| 19 |
> - [YAML idiosyncrasies](https://salt-zh.readthedocs.io/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html) |
| 20 |
> - [YAML multiline](https://yaml-multiline.info/) |
| 21 |
|
| 22 |
The `identifier` is a string identifying the object you want to document. |
| 23 |
The format of an identifier can vary from one handler to another. |
| 24 |
For example, the Python handler expects the full dotted-path to a Python object: |
| 25 |
`my_package.my_module.MyClass.my_method`. |
| 26 |
|
| 27 |
The YAML block is optional, and contains some configuration options: |
| 28 |
|
| 29 |
- `handler`: the name of the handler to use to collect and render this object. |
| 30 |
By default, it will use the value defined in the [Global options](#global-options)'s |
| 31 |
`default_handler` key, or `"python"`. |
| 32 |
- `options`: a dictionary of options passed to the handler's methods responsible both |
| 33 |
for collecting and rendering the documentation. These options can be defined |
| 34 |
globally (in `mkdocs.yml`, see [Global options](#global-options)), |
| 35 |
locally (as described here), or both. |
| 36 |
|
| 37 |
!!! example "Example with the Python handler" |
| 38 |
=== "docs/my_page.md" |
| 39 |
```md |
| 40 |
# Documentation for `MyClass` |
| 41 |
|
| 42 |
::: my_package.my_module.MyClass |
| 43 |
handler: python |
| 44 |
options: |
| 45 |
members: |
| 46 |
- method_a |
| 47 |
- method_b |
| 48 |
show_root_heading: false |
| 49 |
show_source: false |
| 50 |
``` |
| 51 |
|
| 52 |
=== "mkdocs.yml" |
| 53 |
```yaml |
| 54 |
nav: |
| 55 |
- "My page": my_page.md |
| 56 |
``` |
| 57 |
|
| 58 |
=== "src/my_package/my_module.py" |
| 59 |
```python |
| 60 |
class MyClass: |
| 61 |
"""Print print print!""" |
| 62 |
|
| 63 |
def method_a(self): |
| 64 |
"""Print A!""" |
| 65 |
print("A!") |
| 66 |
|
| 67 |
def method_b(self): |
| 68 |
"""Print B!""" |
| 69 |
print("B!") |
| 70 |
|
| 71 |
def method_c(self): |
| 72 |
"""Print C!""" |
| 73 |
print("C!") |
| 74 |
``` |
| 75 |
|
| 76 |
=== "Result" |
| 77 |
<h3 id="documentation-for-myclass" style="margin: 0;">Documentation for <code>MyClass</code></h3> |
| 78 |
<div><div><p>Print print print!</p><div><div> |
| 79 |
<h4 id="mkdocstrings.my_module.MyClass.method_a"> |
| 80 |
<code class="highlight language-python"> |
| 81 |
method_a<span class="p">(</span><span class="bp">self</span><span class="p">)</span> </code> |
| 82 |
</h4><div> |
| 83 |
<p>Print A!</p></div></div><div><h4 id="mkdocstrings.my_module.MyClass.method_b"> |
| 84 |
<code class="highlight language-python"> |
| 85 |
method_b<span class="p">(</span><span class="bp">self</span><span class="p">)</span> </code> |
| 86 |
</h4><div><p>Print B!</p></div></div></div></div></div> |
| 87 |
|
| 88 |
It is also possible to integrate a mkdocstrings identifier into a Markdown header: |
| 89 |
|
| 90 |
```md |
| 91 |
## ::: my_package.my_module.MyClass |
| 92 |
options: |
| 93 |
show_source: false |
| 94 |
``` |
| 95 |
|
| 96 |
The above is equivalent to: |
| 97 |
|
| 98 |
```md |
| 99 |
::: my_package.my_module.MyClass |
| 100 |
options: |
| 101 |
show_source: false |
| 102 |
heading_level: 2 |
| 103 |
``` |
| 104 |
|
| 105 |
## Global options |
| 106 |
|
| 107 |
*mkdocstrings* accepts a few top-level configuration options in `mkdocs.yml`: |
| 108 |
|
| 109 |
- `default_handler`: The handler that is used by default when no handler is specified. |
| 110 |
- `custom_templates`: The path to a directory containing custom templates. |
| 111 |
The path is relative to the MkDocs configuration file. |
| 112 |
See [Theming](theming.md). |
| 113 |
- `handlers`: The handlers' global configuration. |
| 114 |
- `enable_inventory`: Whether to enable inventory file generation. |
| 115 |
See [Cross-references to other projects / inventories](#cross-references-to-other-projects-inventories) |
| 116 |
- `locale`: The locale used for translations. See [Internationalization](#internationalization-i18n). |
| 117 |
- `enabled` **(New in version 0.20)**: Whether to enable the plugin. Defaults to `true`. |
| 118 |
Can be used to reduce build times when doing local development. |
| 119 |
Especially useful when used with environment variables (see example below). |
| 120 |
|
| 121 |
!!! example |
| 122 |
```yaml title="mkdocs.yml" |
| 123 |
plugins: |
| 124 |
- mkdocstrings: |
| 125 |
enabled: !ENV [ENABLE_MKDOCSTRINGS, true] |
| 126 |
custom_templates: templates |
| 127 |
default_handler: python |
| 128 |
locale: en |
| 129 |
handlers: |
| 130 |
python: |
| 131 |
options: |
| 132 |
show_source: false |
| 133 |
``` |
| 134 |
|
| 135 |
The handlers global configuration can then be overridden by local configurations: |
| 136 |
|
| 137 |
```yaml title="docs/some_page.md" |
| 138 |
::: my_package.my_module.MyClass |
| 139 |
options: |
| 140 |
show_source: true |
| 141 |
``` |
| 142 |
|
| 143 |
Some handlers accept additional global configuration. |
| 144 |
Check the documentation for your handler of interest in [Handlers](handlers.md). |
| 145 |
|
| 146 |
## Internationalization (I18N) |
| 147 |
|
| 148 |
Some handlers support multiple languages. |
| 149 |
|
| 150 |
If the handler supports localization, the locale it uses is determined by the following order of precedence: |
| 151 |
|
| 152 |
- `locale` in [global options](#global-options) |
| 153 |
- `theme.language`: used by the [MkDocs Material theme](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/) |
| 154 |
- `theme.locale` in [MkDocs configuration](https://www.mkdocs.org/user-guide/configuration/#theme) |
| 155 |
|
| 156 |
## Cross-references |
| 157 |
|
| 158 |
Cross-references are written as Markdown *reference-style* links: |
| 159 |
|
| 160 |
=== "Markdown" |
| 161 |
```md |
| 162 |
With a custom title: |
| 163 |
[`Object 1`][full.path.object1] |
| 164 |
|
| 165 |
With the identifier as title: |
| 166 |
[full.path.object2][] |
| 167 |
``` |
| 168 |
|
| 169 |
=== "HTML Result" |
| 170 |
```html |
| 171 |
<p>With a custom title: |
| 172 |
<a href="https://example.com/page1#full.path.object1"><code>Object 1</code></a><p> |
| 173 |
<p>With the identifier as title: |
| 174 |
<a href="https://example.com/page2#full.path.object2">full.path.object2</a></p> |
| 175 |
``` |
| 176 |
|
| 177 |
Any item that was inserted using the [autodoc syntax](#autodoc-syntax) |
| 178 |
(e.g. `::: full.path.object1`) is possible to link to by using the same identifier with the |
| 179 |
cross-reference syntax (`[example][full.path.object1]`). |
| 180 |
But the cross-references are also applicable to the items' children that get pulled in. |
| 181 |
|
| 182 |
### Finding out the anchor |
| 183 |
|
| 184 |
If you're not sure which exact identifier a doc item uses, you can look at its "anchor", which your |
| 185 |
Web browser will show in the URL bar when clicking an item's entry in the table of contents. |
| 186 |
If the URL is `https://example.com/some/page.html#full.path.object1` then you know that this item |
| 187 |
is possible to link to with `[example][full.path.object1]`, regardless of the current page. |
| 188 |
|
| 189 |
### Cross-references to any Markdown heading |
| 190 |
|
| 191 |
TIP: **Changed in version 0.15.** |
| 192 |
Linking to any Markdown heading used to be the default, but now opt-in is required. |
| 193 |
|
| 194 |
If you want to link to *any* Markdown heading, not just *mkdocstrings*-inserted items, please |
| 195 |
enable the [*autorefs* plugin for *MkDocs*](https://github.com/mkdocstrings/autorefs) by adding |
| 196 |
`autorefs` to `plugins`: |
| 197 |
|
| 198 |
```yaml title="mkdocs.yml" hl_lines="3" |
| 199 |
plugins: |
| 200 |
- search |
| 201 |
- autorefs |
| 202 |
- mkdocstrings: |
| 203 |
[...] |
| 204 |
``` |
| 205 |
|
| 206 |
Note that you don't need to (`pip`) install anything more; this plugin is guaranteed to be pulled in with *mkdocstrings*. |
| 207 |
|
| 208 |
!!! example |
| 209 |
=== "doc1.md" |
| 210 |
```md |
| 211 |
## Hello, world! |
| 212 |
|
| 213 |
Testing |
| 214 |
``` |
| 215 |
|
| 216 |
=== "doc2.md" |
| 217 |
```md |
| 218 |
## Something else |
| 219 |
|
| 220 |
Please see the [Hello, World!][hello-world] section. |
| 221 |
``` |
| 222 |
|
| 223 |
=== "Result HTML for doc2" |
| 224 |
```html |
| 225 |
<p>Please see the <a href="doc1.html#hello-world">Hello, World!</a> section.</p> |
| 226 |
``` |
| 227 |
|
| 228 |
### Cross-references to a sub-heading in a docstring |
| 229 |
|
| 230 |
TIP: **New in version 0.14.** |
| 231 |
|
| 232 |
If you have a Markdown heading *inside* your docstring, you can also link directly to it. |
| 233 |
In the example below you see the identifier to be linked is `foo.bar--tips`, because it's the "Tips" heading that's part of the `foo.bar` object, joined with "`--`". |
| 234 |
|
| 235 |
!!! example |
| 236 |
=== "foo.py" |
| 237 |
```python |
| 238 |
def bar(): |
| 239 |
"""Hello, world! |
| 240 |
|
| 241 |
# Tips |
| 242 |
|
| 243 |
- Stay hydrated. |
| 244 |
""" |
| 245 |
``` |
| 246 |
|
| 247 |
=== "doc1.md" |
| 248 |
```md |
| 249 |
::: foo.bar |
| 250 |
``` |
| 251 |
|
| 252 |
=== "doc2.md" |
| 253 |
```md |
| 254 |
Check out the [tips][foo.bar--tips] |
| 255 |
``` |
| 256 |
|
| 257 |
=== "HTML result for doc2" |
| 258 |
```html |
| 259 |
<p>Check out the <a href="doc1.html#foo.bar--tips">tips</a></p> |
| 260 |
``` |
| 261 |
|
| 262 |
The above tip about [Finding out the anchor](#finding-out-the-anchor) also applies the same way here. |
| 263 |
|
| 264 |
You may also notice that such a heading does not get rendered as a `<h1>` element directly, but rather the level gets shifted to fit the encompassing document structure. If you're curious about the implementation, check out [mkdocstrings.HeadingShiftingTreeprocessor][] and others. |
| 265 |
|
| 266 |
### Cross-references to other projects / inventories |
| 267 |
|
| 268 |
TIP: **New in version 0.16.** |
| 269 |
|
| 270 |
Python developers coming from Sphinx might know about its `intersphinx` extension, |
| 271 |
that allows to cross-reference items between several projects. |
| 272 |
*mkdocstrings* has a similar feature. |
| 273 |
|
| 274 |
To reference an item from another project, you must first tell *mkdocstrings* |
| 275 |
to load the inventory it provides. Each handler will be responsible of loading |
| 276 |
inventories specific to its language. For example, the Python handler |
| 277 |
can load Sphinx-generated inventories (`objects.inv`). |
| 278 |
|
| 279 |
In the following snippet, we load the inventory provided by `installer`: |
| 280 |
|
| 281 |
```yaml title="mkdocs.yml" |
| 282 |
plugins: |
| 283 |
- mkdocstrings: |
| 284 |
handlers: |
| 285 |
python: |
| 286 |
inventories: |
| 287 |
- https://installer.readthedocs.io/en/stable/objects.inv |
| 288 |
``` |
| 289 |
|
| 290 |
Now it is possible to cross-reference `installer`'s items. For example: |
| 291 |
|
| 292 |
=== "Markdown" |
| 293 |
```md |
| 294 |
See [installer.records][] to learn about records. |
| 295 |
``` |
| 296 |
|
| 297 |
=== "Result (HTML)" |
| 298 |
```html |
| 299 |
<p>See <a href="https://installer.readthedocs.io/en/stable/api/records/#module-installer.records">installer.records</a> |
| 300 |
to learn about records.</p> |
| 301 |
``` |
| 302 |
|
| 303 |
=== "Result (displayed)" |
| 304 |
See [installer.records][] to learn about records. |
| 305 |
|
| 306 |
You can of course select another version of the inventory, for example: |
| 307 |
|
| 308 |
```yaml |
| 309 |
plugins: |
| 310 |
- mkdocstrings: |
| 311 |
handlers: |
| 312 |
python: |
| 313 |
inventories: |
| 314 |
# latest instead of stable |
| 315 |
- https://installer.readthedocs.io/en/latest/objects.inv |
| 316 |
``` |
| 317 |
|
| 318 |
In case the inventory file is not served under the base documentation URL, |
| 319 |
you can explicitly specify both URLs: |
| 320 |
|
| 321 |
```yaml |
| 322 |
plugins: |
| 323 |
- mkdocstrings: |
| 324 |
handlers: |
| 325 |
python: |
| 326 |
inventories: |
| 327 |
- url: https://cdn.example.com/version/objects.inv |
| 328 |
base_url: https://docs.example.com/version |
| 329 |
``` |
| 330 |
|
| 331 |
Absolute URLs to cross-referenced items will then be based |
| 332 |
on `https://docs.example.com/version/` instead of `https://cdn.example.com/version/`. |
| 333 |
|
| 334 |
If you need authentication to access the inventory file, you can provide the credentials in the URL, either as `username:password`: |
| 335 |
|
| 336 |
```yaml |
| 337 |
- url: https://username:[email protected]/version/objects.inv |
| 338 |
``` |
| 339 |
|
| 340 |
...or with token authentication: |
| 341 |
|
| 342 |
```yaml |
| 343 |
- url: https://[email protected]/version/objects.inv |
| 344 |
``` |
| 345 |
|
| 346 |
The credentials can also be specified using environment variables in the form `${ENV_VAR}`: |
| 347 |
|
| 348 |
```yaml |
| 349 |
- url: https://${USERNAME}:${PASSWORD}@private.example.com/version/objects.inv |
| 350 |
``` |
| 351 |
|
| 352 |
Reciprocally, *mkdocstrings* also allows to *generate* an inventory file in the Sphinx format. |
| 353 |
It will be enabled by default if the Python handler is used, and generated as `objects.inv` in the final site directory. |
| 354 |
Other projects will be able to cross-reference items from your project. |
| 355 |
|
| 356 |
To explicitly enable or disable the generation of the inventory file, use the global |
| 357 |
`enable_inventory` option: |
| 358 |
|
| 359 |
```yaml |
| 360 |
plugins: |
| 361 |
- mkdocstrings: |
| 362 |
enable_inventory: false |
| 363 |
``` |