Debian Codegraph @

docs/usage/index.md

raw
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 ```