-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
251 lines (216 loc) · 91.7 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="Automatic documentation from sources, for MkDocs."><link href=https://mkdocstrings.github.io/recipes/ rel=canonical><link href=../usage/handlers/ rel=prev><link href=../troubleshooting/ rel=next><link rel=icon href=../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.6.9+insiders-4.53.16"><title>Recipes - mkdocstrings</title><link rel=stylesheet href=../assets/stylesheets/main.ade31302.min.css><link rel=stylesheet href=../assets/stylesheets/palette.ab4e12ef.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback"><style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style><link rel=stylesheet href=../assets/_markdown_exec_pyodide.css><link rel=stylesheet href=../css/timeago.css><link rel=stylesheet href=../assets/_mkdocstrings.css><link rel=stylesheet href=../css/style.css><link rel=stylesheet href=../css/material.css><link rel=stylesheet href=../css/mkdocstrings.css><link rel=stylesheet href=../css/insiders.css><script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#automatic-code-reference-pages class=md-skip> Skip to content </a> </div> <div data-md-component=announce> <aside class=md-banner> <div class="md-banner__inner md-grid md-typeset"> <button class="md-banner__button md-icon" aria-label="Don't show this again"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg> </button> <strong>Fund this project</strong> through <a href=../insiders/#how-to-become-a-sponsor><strong>sponsorship</strong></a> <span class="twemoji heart pulse"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 16 16"><path d="M7.655 14.916zh-.002l-.006-.003-.018-.01a22 22 0 0 1-3.744-2.584C2.045 10.731 0 8.35 0 5.5 0 2.836 2.086 1 4.25 1 5.797 1 7.153 1.802 8 3.02 8.847 1.802 10.203 1 11.75 1 13.914 1 16 2.836 16 5.5c0 2.85-2.044 5.231-3.886 6.818a22 22 0 0 1-3.433 2.414 7 7 0 0 1-.31.17l-.018.01-.008.004a.75.75 0 0 1-.69 0"/></svg> </span> — Follow <strong>@pawamoy</strong> on <a rel=me href=https://fosstodon.org/@pawamoy> <span class="twemoji mastodon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M433 179.11c0-97.2-63.71-125.7-63.71-125.7-62.52-28.7-228.56-28.4-290.48 0 0 0-63.72 28.5-63.72 125.7 0 115.7-6.6 259.4 105.63 289.1 40.51 10.7 75.32 13 103.33 11.4 50.81-2.8 79.32-18.1 79.32-18.1l-1.7-36.9s-36.31 11.4-77.12 10.1c-40.41-1.4-83-4.4-89.63-54a102.5 102.5 0 0 1-.9-13.9c85.63 20.9 158.65 9.1 178.75 6.7 56.12-6.7 105-41.3 111.23-72.9 9.8-49.8 9-121.5 9-121.5m-75.12 125.2h-46.63v-114.2c0-49.7-64-51.6-64 6.9v62.5h-46.33V197c0-58.5-64-56.6-64-6.9v114.2H90.19c0-122.1-5.2-147.9 18.41-175 25.9-28.9 79.82-30.8 103.83 6.1l11.6 19.5 11.6-19.5c24.11-37.1 78.12-34.8 103.83-6.1 23.71 27.3 18.4 53 18.4 175z"/></svg> </span> <strong>Fosstodon</strong> </a> for updates </div> <script>var el=document.querySelector("[data-md-component=announce]");if(el){var content=el.querySelector(".md-typeset");__md_hash(content.innerHTML)===__md_get("__announce")&&(el.hidden=!0)}</script> </aside> </div> <header class="md-header md-header--shadow md-header--lifted" data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=.. title=mkdocstrings class="md-header__button md-logo" aria-label=mkdocstrings data-md-component=logo> <img src=../logo.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> mkdocstrings </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Recipes </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=teal data-md-color-accent=purple aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 7a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5m0 2a3 3 0 0 0-3 3 3 3 0 0 0 3 3 3 3 0 0 0 3-3 3 3 0 0 0-3-3m0-7 2.39 3.42C13.65 5.15 12.84 5 12 5s-1.65.15-2.39.42zM3.34 7l4.16-.35A7.2 7.2 0 0 0 5.94 8.5c-.44.74-.69 1.5-.83 2.29zm.02 10 1.76-3.77a7.131 7.131 0 0 0 2.38 4.14zM20.65 7l-1.77 3.79a7.02 7.02 0 0 0-2.38-4.15zm-.01 10-4.14.36c.59-.51 1.12-1.14 1.54-1.86.42-.73.69-1.5.83-2.29zM12 22l-2.41-3.44c.74.27 1.55.44 2.41.44.82 0 1.63-.17 2.37-.44z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=black data-md-color-accent=lime aria-label="Switch to system preference" type=radio name=__palette id=__palette_2> <label class="md-header__button md-icon" title="Switch to system preference" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m17.75 4.09-2.53 1.94.91 3.06-2.63-1.81-2.63 1.81.91-3.06-2.53-1.94L12.44 4l1.06-3 1.06 3zm3.5 6.91-1.64 1.25.59 1.98-1.7-1.17-1.7 1.17.59-1.98L15.75 11l2.06-.05L18.5 9l.69 1.95zm-2.28 4.95c.83-.08 1.72 1.1 1.19 1.85-.32.45-.66.87-1.08 1.27C15.17 23 8.84 23 4.94 19.07c-3.91-3.9-3.91-10.24 0-14.14.4-.4.82-.76 1.27-1.08.75-.53 1.93.36 1.85 1.19-.27 2.86.69 5.83 2.89 8.02a9.96 9.96 0 0 0 8.02 2.89m-1.64 2.02a12.08 12.08 0 0 1-7.8-3.47c-2.17-2.19-3.33-5-3.49-7.82-2.81 3.14-2.7 7.96.31 10.98 3.02 3.01 7.84 3.12 10.98.31"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-md-component=search role=dialog> <label class=md-search__overlay for=__search></label> <div class=md-search__inner role=search> <form class=md-search__form name=search> <input type=text class=md-search__input name=query aria-label=Search placeholder=Search autocapitalize=off autocorrect=off autocomplete=off spellcheck=false data-md-component=search-query required> <label class="md-search__icon md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </label> <nav class=md-search__options aria-label=Search> <button type=reset class="md-search__icon md-icon" title=Clear aria-label=Clear tabindex=-1> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg> </button> </nav> <div class=md-search__suggest data-md-component=search-suggest></div> </form> <div class=md-search__output> <div class=md-search__scrollwrap tabindex=0 data-md-scrollfix> <div class=md-search-result data-md-component=search-result> <div class=md-search-result__meta> Initializing search </div> <ol class=md-search-result__list role=presentation></ol> </div> </div> </div> </div> </div> <div class=md-header__source> <a href=https://github.com/mkdocstrings/mkdocstrings title="Go to repository" class=md-source data-md-component=source> <div class="md-source__icon md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg> </div> <div class=md-source__repository> mkdocstrings/mkdocstrings </div> </a> </div> </nav> <nav class=md-tabs aria-label=Tabs data-md-component=tabs> <div class=md-grid> <ul class=md-tabs__list> <li class=md-tabs__item> <a href=.. class=md-tabs__link> Home </a> </li> <li class="md-tabs__item md-tabs__item--active"> <a href=../usage/ class=md-tabs__link> Usage </a> </li> <li class=md-tabs__item> <a href=../reference/mkdocstrings/ class=md-tabs__link> API reference </a> </li> <li class=md-tabs__item> <a href=../contributing/ class=md-tabs__link> Development </a> </li> <li class=md-tabs__item> <a href=../insiders/ class=md-tabs__link> Insiders </a> </li> <li class=md-tabs__item> <a href=https://pawamoy.github.io/ class=md-tabs__link> Author's website </a> </li> </ul> </div> </nav> </header> <div class=md-container data-md-component=container> <main class=md-main data-md-component=main> <div class="md-main__inner md-grid"> <div class="md-sidebar md-sidebar--primary" data-md-component=sidebar data-md-type=navigation> <div class=md-sidebar__scrollwrap> <div class=md-sidebar__inner> <nav class="md-nav md-nav--primary md-nav--lifted" aria-label=Navigation data-md-level=0> <label class=md-nav__title for=__drawer> <a href=.. title=mkdocstrings class="md-nav__button md-logo" aria-label=mkdocstrings data-md-component=logo> <img src=../logo.svg alt=logo> </a> mkdocstrings </label> <div class=md-nav__source> <a href=https://github.com/mkdocstrings/mkdocstrings title="Go to repository" class=md-source data-md-component=source> <div class="md-source__icon md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg> </div> <div class=md-source__repository> mkdocstrings/mkdocstrings </div> </a> </div> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_1> <label class=md-nav__link for=__nav_1 id=__nav_1_label tabindex=0> <span class=md-ellipsis> Home </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_1_label aria-expanded=false> <label class=md-nav__title for=__nav_1> <span class="md-nav__icon md-icon"></span> Home </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=.. class=md-nav__link> <span class=md-ellipsis> Overview </span> </a> </li> <li class=md-nav__item> <a href=../changelog/ class=md-nav__link> <span class=md-ellipsis> Changelog </span> </a> </li> <li class=md-nav__item> <a href=../credits/ class=md-nav__link> <span class=md-ellipsis> Credits </span> </a> </li> <li class=md-nav__item> <a href=../license/ class=md-nav__link> <span class=md-ellipsis> License </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2 checked> <div class="md-nav__link md-nav__container"> <a href=../usage/ class="md-nav__link "> <span class=md-ellipsis> Usage </span> </a> <label class="md-nav__link " for=__nav_2 id=__nav_2_label tabindex> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_2_label aria-expanded=true> <label class=md-nav__title for=__nav_2> <span class="md-nav__icon md-icon"></span> Usage </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../usage/theming/ class=md-nav__link> <span class=md-ellipsis> Theming </span> </a> </li> <li class=md-nav__item> <a href=../usage/handlers/ class=md-nav__link> <span class=md-ellipsis> Handlers </span> </a> </li> <li class="md-nav__item md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2_3> <label class=md-nav__link for=__nav_2_3 id=__nav_2_3_label tabindex> <span class=md-ellipsis> All handlers </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_2_3_label aria-expanded=false> <label class=md-nav__title for=__nav_2_3> <span class="md-nav__icon md-icon"></span> All handlers </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=https://mkdocstrings.github.io/c/ class=md-nav__link> <span class=md-ellipsis> C </span> </a> </li> <li class=md-nav__item> <a href=https://mkdocstrings.github.io/crystal/ class=md-nav__link> <span class=md-ellipsis> Crystal </span> </a> </li> <li class=md-nav__item> <a href=https://mkdocstrings.github.io/python/ class=md-nav__link> <span class=md-ellipsis> Python </span> </a> </li> <li class=md-nav__item> <a href=https://mkdocstrings.github.io/python-legacy/ class=md-nav__link> <span class=md-ellipsis> Python (Legacy) </span> </a> </li> <li class=md-nav__item> <a href=https://mkdocstrings.github.io/shell/ class=md-nav__link> <span class=md-ellipsis> Shell </span> </a> </li> <li class=md-nav__item> <a href=https://mkdocstrings.github.io/typescript/ class=md-nav__link> <span class=md-ellipsis> TypeScript </span> </a> </li> <li class=md-nav__item> <a href=https://pypi.org/project/mkdocstrings-vba class=md-nav__link> <span class=md-ellipsis> VBA </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2_4 checked> <label class=md-nav__link for=__nav_2_4 id=__nav_2_4_label tabindex> <span class=md-ellipsis> Guides </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_2_4_label aria-expanded=true> <label class=md-nav__title for=__nav_2_4> <span class="md-nav__icon md-icon"></span> Guides </label> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" type=checkbox id=__toc> <label class="md-nav__link md-nav__link--active" for=__toc> <span class=md-ellipsis> Recipes </span> <span class="md-nav__icon md-icon"></span> </label> <a href=./ class="md-nav__link md-nav__link--active"> <span class=md-ellipsis> Recipes </span> </a> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class=md-nav__title for=__toc> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class=md-nav__list data-md-component=toc data-md-scrollfix> <li class=md-nav__item> <a href=#automatic-code-reference-pages class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Automatic code reference pages </span> </span> </a> <nav class=md-nav aria-label="Automatic code reference pages"> <ul class=md-nav__list> <li class=md-nav__item> <a href=#generate-pages-on-the-fly class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Generate pages on-the-fly </span> </span> </a> </li> <li class=md-nav__item> <a href=#generate-a-literate-navigation-file class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Generate a literate navigation file </span> </span> </a> </li> <li class=md-nav__item> <a href=#bind-pages-to-sections-themselves class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Bind pages to sections themselves </span> </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#prevent-selection-of-prompts-and-output-in-python-code-blocks class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Prevent selection of prompts and output in Python code blocks </span> </span> </a> </li> <li class=md-nav__item> <a href=#hide-documentation-strings-from-source-code-blocks class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Hide documentation strings from source code blocks </span> </span> </a> </li> <li class=md-nav__item> <a href=#automatic-highlighting-for-indented-code-blocks-in-docstrings class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Automatic highlighting for indented code blocks in docstrings </span> </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=../troubleshooting/ class=md-nav__link> <span class=md-ellipsis> Troubleshooting </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=../reference/mkdocstrings/ class=md-nav__link> <span class=md-ellipsis> API reference </span> </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_4> <label class=md-nav__link for=__nav_4 id=__nav_4_label tabindex=0> <span class=md-ellipsis> Development </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_4_label aria-expanded=false> <label class=md-nav__title for=__nav_4> <span class="md-nav__icon md-icon"></span> Development </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../contributing/ class=md-nav__link> <span class=md-ellipsis> Contributing </span> </a> </li> <li class=md-nav__item> <a href=../code_of_conduct/ class=md-nav__link> <span class=md-ellipsis> Code of Conduct </span> </a> </li> <li class=md-nav__item> <a href=../coverage/ class=md-nav__link> <span class=md-ellipsis> Coverage report </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_5> <div class="md-nav__link md-nav__container"> <a href=../insiders/ class="md-nav__link "> <span class=md-ellipsis> Insiders </span> </a> <label class="md-nav__link " for=__nav_5 id=__nav_5_label tabindex=0> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_5_label aria-expanded=false> <label class=md-nav__title for=__nav_5> <span class="md-nav__icon md-icon"></span> Insiders </label> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_5_1> <label class=md-nav__link for=__nav_5_1 id=__nav_5_1_label tabindex=0> <span class=md-ellipsis> Getting started </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_5_1_label aria-expanded=false> <label class=md-nav__title for=__nav_5_1> <span class="md-nav__icon md-icon"></span> Getting started </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../insiders/installation/ class=md-nav__link> <span class=md-ellipsis> Installation </span> </a> </li> <li class=md-nav__item> <a href=../insiders/changelog/ class=md-nav__link> <span class=md-ellipsis> Changelog </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=https://pawamoy.github.io/ class=md-nav__link> <span class=md-ellipsis> Author's website </span> </a> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component=sidebar data-md-type=toc> <div class=md-sidebar__scrollwrap> <div class=md-sidebar__inner> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class=md-nav__title for=__toc> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class=md-nav__list data-md-component=toc data-md-scrollfix> <li class=md-nav__item> <a href=#automatic-code-reference-pages class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Automatic code reference pages </span> </span> </a> <nav class=md-nav aria-label="Automatic code reference pages"> <ul class=md-nav__list> <li class=md-nav__item> <a href=#generate-pages-on-the-fly class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Generate pages on-the-fly </span> </span> </a> </li> <li class=md-nav__item> <a href=#generate-a-literate-navigation-file class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Generate a literate navigation file </span> </span> </a> </li> <li class=md-nav__item> <a href=#bind-pages-to-sections-themselves class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Bind pages to sections themselves </span> </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#prevent-selection-of-prompts-and-output-in-python-code-blocks class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Prevent selection of prompts and output in Python code blocks </span> </span> </a> </li> <li class=md-nav__item> <a href=#hide-documentation-strings-from-source-code-blocks class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Hide documentation strings from source code blocks </span> </span> </a> </li> <li class=md-nav__item> <a href=#automatic-highlighting-for-indented-code-blocks-in-docstrings class=md-nav__link> <span class=md-ellipsis> <span class=md-typeset> Automatic highlighting for indented code blocks in docstrings </span> </span> </a> </li> </ul> </nav> </div> </div> </div> <div class=md-content data-md-component=content> <nav class=md-path aria-label=Navigation> <ol class=md-path__list> <li class=md-path__item> <a href=../usage/ class=md-path__link> <span class=md-ellipsis> Usage </span> </a> </li> <li class=md-path__item> <a href=./ class=md-path__link> <span class=md-ellipsis> Guides </span> </a> </li> </ol> </nav> <article class="md-content__inner md-typeset"> <a href=https://github.com/mkdocstrings/mkdocstrings/edit/main/docs/recipes.md title="Edit this page" class="md-content__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4zm10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1z"/></svg> </a> <a href=https://github.com/mkdocstrings/mkdocstrings/raw/main/docs/recipes.md title="View source of this page" class="md-content__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M17 18c.56 0 1 .44 1 1s-.44 1-1 1-1-.44-1-1 .44-1 1-1m0-3c-2.73 0-5.06 1.66-6 4 .94 2.34 3.27 4 6 4s5.06-1.66 6-4c-.94-2.34-3.27-4-6-4m0 6.5a2.5 2.5 0 0 1-2.5-2.5 2.5 2.5 0 0 1 2.5-2.5 2.5 2.5 0 0 1 2.5 2.5 2.5 2.5 0 0 1-2.5 2.5M9.27 20H6V4h7v5h5v4.07c.7.08 1.36.25 2 .49V8l-6-6H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h4.5a8.2 8.2 0 0 1-1.23-2"/></svg> </a> <h1>Recipes</h1> <p>On this page you will find various recipes, tips and tricks for <em>mkdocstrings</em> and more generally Markdown documentation.</p> <h2 id=automatic-code-reference-pages>Automatic code reference pages<a class=headerlink href=#automatic-code-reference-pages title="Permanent link">¤</a></h2> <div class="admonition tip"> <p class=admonition-title><a href=https://github.com/jcayers20/mkdocs-autoapi>mkdocs-autoapi</a> and <a href=https://github.com/tlambert03/mkdocs-api-autonav>mkdocs-api-autonav</a> are MkDocs plugins that automatically generate API documentation from your project's source code. They were inspired by the recipe below.</p> </div> <p><em>mkdocstrings</em> allows to inject documentation for any object into Markdown pages. But as the project grows, it quickly becomes quite tedious to keep the autodoc instructions, or even the dedicated Markdown files in sync with all your source files and objects.</p> <p>In this recipe, we will iteratively automate the process of generating these pages at each build of the documentation.</p> <hr> <p>Let say you have a project called <code>project</code>. This project has a lot of source files, or modules, which live in the <code>src</code> folder:</p> <div class="language-bash highlight"><pre><span></span><code>📁<span class=w> </span>repo/
└──<span class=w> </span>📁<span class=w> </span>src/
<span class=w> </span>└──<span class=w> </span>📁<span class=w> </span>project/
<span class=w> </span>├──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 9V3.5L18.5 9M6 2c-1.11 0-2 .89-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8l-6-6z"/></svg></span><span class=w> </span>lorem
<span class=w> </span>├──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 9V3.5L18.5 9M6 2c-1.11 0-2 .89-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8l-6-6z"/></svg></span><span class=w> </span>ipsum
<span class=w> </span>├──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 9V3.5L18.5 9M6 2c-1.11 0-2 .89-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8l-6-6z"/></svg></span><span class=w> </span>dolor
<span class=w> </span>├──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 9V3.5L18.5 9M6 2c-1.11 0-2 .89-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8l-6-6z"/></svg></span><span class=w> </span>sit
<span class=w> </span>└──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 9V3.5L18.5 9M6 2c-1.11 0-2 .89-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8l-6-6z"/></svg></span><span class=w> </span>amet
</code></pre></div> <p>Without an automatic process, you will have to manually create a Markdown page for each one of these modules, with the corresponding autodoc instruction, for example <code>::: project.lorem</code>, and also add entry in MkDocs' navigation option (<code>nav</code> in <code>mkdocs.yml</code>). With a lot of modules, this is quickly getting cumbersome.</p> <p>Lets fix that.</p> <h3 id=generate-pages-on-the-fly>Generate pages on-the-fly<a class=headerlink href=#generate-pages-on-the-fly title="Permanent link">¤</a></h3> <p>In this recipe, we suggest to use the <a href=https://github.com/oprypin/mkdocs-gen-files>mkdocs-gen-files plugin</a>. This plugin exposes utilities to generate files at build time. These files won't be written to the docs directory: you don't have to track and version them. They are transparently generated each time you build your docs. This is perfect for our use-case!</p> <p>Add <code>mkdocs-gen-files</code> to your project's docs dependencies, and configure it like so:</p> <div class="language-yaml highlight"><span class=filename>mkdocs.yml</span><pre><span></span><code><span class=nt>plugins</span><span class=p>:</span>
<span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">search</span><span class=w> </span><span class=c1># (1)!</span>
<span class="p p-Indicator">-</span><span class=w> </span><span class=nt>gen-files</span><span class=p>:</span>
<span class=w> </span><span class=nt>scripts</span><span class=p>:</span>
<span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">scripts/gen_ref_pages.py</span><span class=w> </span><span class=c1># (2)!</span>
<span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">mkdocstrings</span>
</code></pre></div> <ol> <li>Don't forget to load the <code>search</code> plugin when redefining the <code>plugins</code> item.</li> <li>The magic happens here, see below how it works.</li> </ol> <p>mkdocs-gen-files is able to run Python scripts at build time. The Python script that we will execute lives in a scripts folder, and is named <code>gen_ref_pages.py</code>, like "generate code reference pages".</p> <div class="language-bash highlight"><pre><span></span><code>📁<span class=w> </span>repo/
├──<span class=w> </span>📁<span class=w> </span>docs/
│<span class=w> </span>└──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M22.27 19.385H1.73A1.73 1.73 0 0 1 0 17.655V6.345a1.73 1.73 0 0 1 1.73-1.73h20.54A1.73 1.73 0 0 1 24 6.345v11.308a1.73 1.73 0 0 1-1.73 1.731zM5.769 15.923v-4.5l2.308 2.885 2.307-2.885v4.5h2.308V8.078h-2.308l-2.307 2.885-2.308-2.885H3.46v7.847zM21.232 12h-2.309V8.077h-2.307V12h-2.308l3.461 4.039z"/></svg></span><span class=w> </span>index.md
├──<span class=w> </span>📁<span class=w> </span>scripts/
│<span class=w> </span>└──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.25.18.9.2.73.26.59.3.45.32.34.34.25.34.16.33.1.3.04.26.02.2-.01.13V8.5l-.05.63-.13.55-.21.46-.26.38-.3.31-.33.25-.35.19-.35.14-.33.1-.3.07-.26.04-.21.02H8.77l-.69.05-.59.14-.5.22-.41.27-.33.32-.27.35-.2.36-.15.37-.1.35-.07.32-.04.27-.02.21v3.06H3.17l-.21-.03-.28-.07-.32-.12-.35-.18-.36-.26-.36-.36-.35-.46-.32-.59-.28-.73-.21-.88-.14-1.05-.05-1.23.06-1.22.16-1.04.24-.87.32-.71.36-.57.4-.44.42-.33.42-.24.4-.16.36-.1.32-.05.24-.01h.16l.06.01h8.16v-.83H6.18l-.01-2.75-.02-.37.05-.34.11-.31.17-.28.25-.26.31-.23.38-.2.44-.18.51-.15.58-.12.64-.1.71-.06.77-.04.84-.02 1.27.05zm-6.3 1.98-.23.33-.08.41.08.41.23.34.33.22.41.09.41-.09.33-.22.23-.34.08-.41-.08-.41-.23-.33-.33-.22-.41-.09-.41.09zm13.09 3.95.28.06.32.12.35.18.36.27.36.35.35.47.32.59.28.73.21.88.14 1.04.05 1.23-.06 1.23-.16 1.04-.24.86-.32.71-.36.57-.4.45-.42.33-.42.24-.4.16-.36.09-.32.05-.24.02-.16-.01h-8.22v.82h5.84l.01 2.76.02.36-.05.34-.11.31-.17.29-.25.25-.31.24-.38.2-.44.17-.51.15-.58.13-.64.09-.71.07-.77.04-.84.01-1.27-.04-1.07-.14-.9-.2-.73-.25-.59-.3-.45-.33-.34-.34-.25-.34-.16-.33-.1-.3-.04-.25-.02-.2.01-.13v-5.34l.05-.64.13-.54.21-.46.26-.38.3-.32.33-.24.35-.2.35-.14.33-.1.3-.06.26-.04.21-.02.13-.01h5.84l.69-.05.59-.14.5-.21.41-.28.33-.32.27-.35.2-.36.15-.36.1-.35.07-.32.04-.28.02-.21V6.07h2.09l.14.01zm-6.47 14.25-.23.33-.08.41.08.41.23.33.33.23.41.08.41-.08.33-.23.23-.33.08-.41-.08-.41-.23-.33-.33-.23-.41-.08-.41.08z"/></svg></span><span class=w> </span>gen_ref_pages.py
├──<span class=w> </span>📁<span class=w> </span>src/
│<span class=w> </span>└──<span class=w> </span>📁<span class=w> </span>project/
└──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m0 .97 4.111 6.453v4.09h2.638v-4.09L11.053.969H8.214L5.58 5.125 2.965.969Zm12.093.024-4.47 10.544h2.114l.97-2.345h4.775l.804 2.345h2.26L14.255.994Zm1.133 2.225 1.463 3.87h-3.096zm3.06 9.475v10.29H24v-2.199h-5.454v-8.091zm-12.175.002v10.335h2.217v-7.129l2.32 4.792h1.746l2.4-4.96v7.295h2.127V12.696h-2.904L9.44 17.37l-2.455-4.674Z"/></svg></span><span class=w> </span>mkdocs.yml
</code></pre></div> <div class="language-python highlight"><span class=filename>scripts/gen_ref_pages.py</span><pre><span></span><code><span class=sd>"""Generate the code reference pages."""</span>
<span class=kn>from</span><span class=w> </span><span class=nn>pathlib</span><span class=w> </span><span class=kn>import</span> <span class=n>Path</span>
<span class=kn>import</span><span class=w> </span><span class=nn>mkdocs_gen_files</span>
<span class=n>root</span> <span class=o>=</span> <span class=n>Path</span><span class=p>(</span><span class=vm>__file__</span><span class=p>)</span><span class=o>.</span><span class=n>parent</span><span class=o>.</span><span class=n>parent</span>
<span class=n>src</span> <span class=o>=</span> <span class=n>root</span> <span class=o>/</span> <span class=s2>"src"</span> <span class=c1># (1)!</span>
<span class=k>for</span> <span class=n>path</span> <span class=ow>in</span> <span class=nb>sorted</span><span class=p>(</span><span class=n>src</span><span class=o>.</span><span class=n>rglob</span><span class=p>(</span><span class=s2>"*.py"</span><span class=p>)):</span> <span class=c1># (2)!</span>
<span class=n>module_path</span> <span class=o>=</span> <span class=n>path</span><span class=o>.</span><span class=n>relative_to</span><span class=p>(</span><span class=n>src</span><span class=p>)</span><span class=o>.</span><span class=n>with_suffix</span><span class=p>(</span><span class=s2>""</span><span class=p>)</span> <span class=c1># (3)!</span>
<span class=n>doc_path</span> <span class=o>=</span> <span class=n>path</span><span class=o>.</span><span class=n>relative_to</span><span class=p>(</span><span class=n>src</span><span class=p>)</span><span class=o>.</span><span class=n>with_suffix</span><span class=p>(</span><span class=s2>".md"</span><span class=p>)</span> <span class=c1># (4)!</span>
<span class=n>full_doc_path</span> <span class=o>=</span> <span class=n>Path</span><span class=p>(</span><span class=s2>"reference"</span><span class=p>,</span> <span class=n>doc_path</span><span class=p>)</span> <span class=c1># (5)!</span>
<span class=n>parts</span> <span class=o>=</span> <span class=nb>tuple</span><span class=p>(</span><span class=n>module_path</span><span class=o>.</span><span class=n>parts</span><span class=p>)</span>
<span class=k>if</span> <span class=n>parts</span><span class=p>[</span><span class=o>-</span><span class=mi>1</span><span class=p>]</span> <span class=o>==</span> <span class=s2>"__init__"</span><span class=p>:</span> <span class=c1># (6)!</span>
<span class=n>parts</span> <span class=o>=</span> <span class=n>parts</span><span class=p>[:</span><span class=o>-</span><span class=mi>1</span><span class=p>]</span>
<span class=k>elif</span> <span class=n>parts</span><span class=p>[</span><span class=o>-</span><span class=mi>1</span><span class=p>]</span> <span class=o>==</span> <span class=s2>"__main__"</span><span class=p>:</span>
<span class=k>continue</span>
<span class=k>with</span> <span class=n>mkdocs_gen_files</span><span class=o>.</span><span class=n>open</span><span class=p>(</span><span class=n>full_doc_path</span><span class=p>,</span> <span class=s2>"w"</span><span class=p>)</span> <span class=k>as</span> <span class=n>fd</span><span class=p>:</span> <span class=c1># (7)!</span>
<span class=n>identifier</span> <span class=o>=</span> <span class=s2>"."</span><span class=o>.</span><span class=n>join</span><span class=p>(</span><span class=n>parts</span><span class=p>)</span> <span class=c1># (8)!</span>
<span class=nb>print</span><span class=p>(</span><span class=s2>"::: "</span> <span class=o>+</span> <span class=n>identifier</span><span class=p>,</span> <span class=n>file</span><span class=o>=</span><span class=n>fd</span><span class=p>)</span> <span class=c1># (9)!</span>
<span class=n>mkdocs_gen_files</span><span class=o>.</span><span class=n>set_edit_path</span><span class=p>(</span><span class=n>full_doc_path</span><span class=p>,</span> <span class=n>path</span><span class=o>.</span><span class=n>relative_to</span><span class=p>(</span><span class=n>root</span><span class=p>))</span> <span class=c1># (10)!</span>
</code></pre></div> <ol> <li>It's important to build a path relative to the script itself, to make it possible to build the docs with MkDocs' <a href=https://www.mkdocs.org/user-guide/cli/#mkdocs-build><code>-f</code> option</a>.</li> <li>Here we recursively list all <code>.py</code> files, but you can adapt the code to list files with other extensions of course, supporting other languages than Python.</li> <li>The module path will look like <code>project/lorem</code>. It will be used to build the <em>mkdocstrings</em> autodoc identifier.</li> <li>This is the partial path of the Markdown page for the module.</li> <li>This is the full path of the Markdown page within the docs. Here we put all reference pages into a <code>reference</code> folder.</li> <li>This part is only relevant for Python modules. We skip <code>__main__</code> modules and remove <code>__init__</code> from the module parts as it's implicit during imports.</li> <li>Magic! Add the file to MkDocs pages, without actually writing it in the docs folder.</li> <li>Build the autodoc identifier. Here we document Python modules, so the identifier is a dot-separated path, like <code>project.lorem</code>.</li> <li>Actually write to the magic file.</li> <li>We can even set the <code>edit_uri</code> on the pages.</li> </ol> <div class="admonition note"> <p class=admonition-title>Note</p> <p> It is important to look out for correct edit page behaviour when using generated pages. For example, if we have <code>edit_uri</code> set to <code>blob/master/docs/</code> and the following file structure:</p> <div class="language-bash highlight"><pre><span></span><code>📁<span class=w> </span>repo/
├──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m0 .97 4.111 6.453v4.09h2.638v-4.09L11.053.969H8.214L5.58 5.125 2.965.969Zm12.093.024-4.47 10.544h2.114l.97-2.345h4.775l.804 2.345h2.26L14.255.994Zm1.133 2.225 1.463 3.87h-3.096zm3.06 9.475v10.29H24v-2.199h-5.454v-8.091zm-12.175.002v10.335h2.217v-7.129l2.32 4.792h1.746l2.4-4.96v7.295h2.127V12.696h-2.904L9.44 17.37l-2.455-4.674Z"/></svg></span><span class=w> </span>mkdocs.yml
├──<span class=w> </span>📁<span class=w> </span>docs/
│<span class=w> </span>└──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M22.27 19.385H1.73A1.73 1.73 0 0 1 0 17.655V6.345a1.73 1.73 0 0 1 1.73-1.73h20.54A1.73 1.73 0 0 1 24 6.345v11.308a1.73 1.73 0 0 1-1.73 1.731zM5.769 15.923v-4.5l2.308 2.885 2.307-2.885v4.5h2.308V8.078h-2.308l-2.307 2.885-2.308-2.885H3.46v7.847zM21.232 12h-2.309V8.077h-2.307V12h-2.308l3.461 4.039z"/></svg></span><span class=w> </span>index.md
├──<span class=w> </span>📁<span class=w> </span>scripts/
│<span class=w> </span>└──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.25.18.9.2.73.26.59.3.45.32.34.34.25.34.16.33.1.3.04.26.02.2-.01.13V8.5l-.05.63-.13.55-.21.46-.26.38-.3.31-.33.25-.35.19-.35.14-.33.1-.3.07-.26.04-.21.02H8.77l-.69.05-.59.14-.5.22-.41.27-.33.32-.27.35-.2.36-.15.37-.1.35-.07.32-.04.27-.02.21v3.06H3.17l-.21-.03-.28-.07-.32-.12-.35-.18-.36-.26-.36-.36-.35-.46-.32-.59-.28-.73-.21-.88-.14-1.05-.05-1.23.06-1.22.16-1.04.24-.87.32-.71.36-.57.4-.44.42-.33.42-.24.4-.16.36-.1.32-.05.24-.01h.16l.06.01h8.16v-.83H6.18l-.01-2.75-.02-.37.05-.34.11-.31.17-.28.25-.26.31-.23.38-.2.44-.18.51-.15.58-.12.64-.1.71-.06.77-.04.84-.02 1.27.05zm-6.3 1.98-.23.33-.08.41.08.41.23.34.33.22.41.09.41-.09.33-.22.23-.34.08-.41-.08-.41-.23-.33-.33-.22-.41-.09-.41.09zm13.09 3.95.28.06.32.12.35.18.36.27.36.35.35.47.32.59.28.73.21.88.14 1.04.05 1.23-.06 1.23-.16 1.04-.24.86-.32.71-.36.57-.4.45-.42.33-.42.24-.4.16-.36.09-.32.05-.24.02-.16-.01h-8.22v.82h5.84l.01 2.76.02.36-.05.34-.11.31-.17.29-.25.25-.31.24-.38.2-.44.17-.51.15-.58.13-.64.09-.71.07-.77.04-.84.01-1.27-.04-1.07-.14-.9-.2-.73-.25-.59-.3-.45-.33-.34-.34-.25-.34-.16-.33-.1-.3-.04-.25-.02-.2.01-.13v-5.34l.05-.64.13-.54.21-.46.26-.38.3-.32.33-.24.35-.2.35-.14.33-.1.3-.06.26-.04.21-.02.13-.01h5.84l.69-.05.59-.14.5-.21.41-.28.33-.32.27-.35.2-.36.15-.36.1-.35.07-.32.04-.28.02-.21V6.07h2.09l.14.01zm-6.47 14.25-.23.33-.08.41.08.41.23.33.33.23.41.08.41-.08.33-.23.23-.33.08-.41-.08-.41-.23-.33-.33-.23-.41-.08-.41.08z"/></svg></span><span class=w> </span>gen_ref_pages.py
└──<span class=w> </span>📁<span class=w> </span>src/
<span class=w> </span>└──<span class=w> </span>📁<span class=w> </span>project/
<span class=w> </span>├──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.25.18.9.2.73.26.59.3.45.32.34.34.25.34.16.33.1.3.04.26.02.2-.01.13V8.5l-.05.63-.13.55-.21.46-.26.38-.3.31-.33.25-.35.19-.35.14-.33.1-.3.07-.26.04-.21.02H8.77l-.69.05-.59.14-.5.22-.41.27-.33.32-.27.35-.2.36-.15.37-.1.35-.07.32-.04.27-.02.21v3.06H3.17l-.21-.03-.28-.07-.32-.12-.35-.18-.36-.26-.36-.36-.35-.46-.32-.59-.28-.73-.21-.88-.14-1.05-.05-1.23.06-1.22.16-1.04.24-.87.32-.71.36-.57.4-.44.42-.33.42-.24.4-.16.36-.1.32-.05.24-.01h.16l.06.01h8.16v-.83H6.18l-.01-2.75-.02-.37.05-.34.11-.31.17-.28.25-.26.31-.23.38-.2.44-.18.51-.15.58-.12.64-.1.71-.06.77-.04.84-.02 1.27.05zm-6.3 1.98-.23.33-.08.41.08.41.23.34.33.22.41.09.41-.09.33-.22.23-.34.08-.41-.08-.41-.23-.33-.33-.22-.41-.09-.41.09zm13.09 3.95.28.06.32.12.35.18.36.27.36.35.35.47.32.59.28.73.21.88.14 1.04.05 1.23-.06 1.23-.16 1.04-.24.86-.32.71-.36.57-.4.45-.42.33-.42.24-.4.16-.36.09-.32.05-.24.02-.16-.01h-8.22v.82h5.84l.01 2.76.02.36-.05.34-.11.31-.17.29-.25.25-.31.24-.38.2-.44.17-.51.15-.58.13-.64.09-.71.07-.77.04-.84.01-1.27-.04-1.07-.14-.9-.2-.73-.25-.59-.3-.45-.33-.34-.34-.25-.34-.16-.33-.1-.3-.04-.25-.02-.2.01-.13v-5.34l.05-.64.13-.54.21-.46.26-.38.3-.32.33-.24.35-.2.35-.14.33-.1.3-.06.26-.04.21-.02.13-.01h5.84l.69-.05.59-.14.5-.21.41-.28.33-.32.27-.35.2-.36.15-.36.1-.35.07-.32.04-.28.02-.21V6.07h2.09l.14.01zm-6.47 14.25-.23.33-.08.41.08.41.23.33.33.23.41.08.41-.08.33-.23.23-.33.08-.41-.08-.41-.23-.33-.33-.23-.41-.08-.41.08z"/></svg></span><span class=w> </span>lorem.py
<span class=w> </span>├──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.25.18.9.2.73.26.59.3.45.32.34.34.25.34.16.33.1.3.04.26.02.2-.01.13V8.5l-.05.63-.13.55-.21.46-.26.38-.3.31-.33.25-.35.19-.35.14-.33.1-.3.07-.26.04-.21.02H8.77l-.69.05-.59.14-.5.22-.41.27-.33.32-.27.35-.2.36-.15.37-.1.35-.07.32-.04.27-.02.21v3.06H3.17l-.21-.03-.28-.07-.32-.12-.35-.18-.36-.26-.36-.36-.35-.46-.32-.59-.28-.73-.21-.88-.14-1.05-.05-1.23.06-1.22.16-1.04.24-.87.32-.71.36-.57.4-.44.42-.33.42-.24.4-.16.36-.1.32-.05.24-.01h.16l.06.01h8.16v-.83H6.18l-.01-2.75-.02-.37.05-.34.11-.31.17-.28.25-.26.31-.23.38-.2.44-.18.51-.15.58-.12.64-.1.71-.06.77-.04.84-.02 1.27.05zm-6.3 1.98-.23.33-.08.41.08.41.23.34.33.22.41.09.41-.09.33-.22.23-.34.08-.41-.08-.41-.23-.33-.33-.22-.41-.09-.41.09zm13.09 3.95.28.06.32.12.35.18.36.27.36.35.35.47.32.59.28.73.21.88.14 1.04.05 1.23-.06 1.23-.16 1.04-.24.86-.32.71-.36.57-.4.45-.42.33-.42.24-.4.16-.36.09-.32.05-.24.02-.16-.01h-8.22v.82h5.84l.01 2.76.02.36-.05.34-.11.31-.17.29-.25.25-.31.24-.38.2-.44.17-.51.15-.58.13-.64.09-.71.07-.77.04-.84.01-1.27-.04-1.07-.14-.9-.2-.73-.25-.59-.3-.45-.33-.34-.34-.25-.34-.16-.33-.1-.3-.04-.25-.02-.2.01-.13v-5.34l.05-.64.13-.54.21-.46.26-.38.3-.32.33-.24.35-.2.35-.14.33-.1.3-.06.26-.04.21-.02.13-.01h5.84l.69-.05.59-.14.5-.21.41-.28.33-.32.27-.35.2-.36.15-.36.1-.35.07-.32.04-.28.02-.21V6.07h2.09l.14.01zm-6.47 14.25-.23.33-.08.41.08.41.23.33.33.23.41.08.41-.08.33-.23.23-.33.08-.41-.08-.41-.23-.33-.33-.23-.41-.08-.41.08z"/></svg></span><span class=w> </span>ipsum.py
<span class=w> </span>├──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.25.18.9.2.73.26.59.3.45.32.34.34.25.34.16.33.1.3.04.26.02.2-.01.13V8.5l-.05.63-.13.55-.21.46-.26.38-.3.31-.33.25-.35.19-.35.14-.33.1-.3.07-.26.04-.21.02H8.77l-.69.05-.59.14-.5.22-.41.27-.33.32-.27.35-.2.36-.15.37-.1.35-.07.32-.04.27-.02.21v3.06H3.17l-.21-.03-.28-.07-.32-.12-.35-.18-.36-.26-.36-.36-.35-.46-.32-.59-.28-.73-.21-.88-.14-1.05-.05-1.23.06-1.22.16-1.04.24-.87.32-.71.36-.57.4-.44.42-.33.42-.24.4-.16.36-.1.32-.05.24-.01h.16l.06.01h8.16v-.83H6.18l-.01-2.75-.02-.37.05-.34.11-.31.17-.28.25-.26.31-.23.38-.2.44-.18.51-.15.58-.12.64-.1.71-.06.77-.04.84-.02 1.27.05zm-6.3 1.98-.23.33-.08.41.08.41.23.34.33.22.41.09.41-.09.33-.22.23-.34.08-.41-.08-.41-.23-.33-.33-.22-.41-.09-.41.09zm13.09 3.95.28.06.32.12.35.18.36.27.36.35.35.47.32.59.28.73.21.88.14 1.04.05 1.23-.06 1.23-.16 1.04-.24.86-.32.71-.36.57-.4.45-.42.33-.42.24-.4.16-.36.09-.32.05-.24.02-.16-.01h-8.22v.82h5.84l.01 2.76.02.36-.05.34-.11.31-.17.29-.25.25-.31.24-.38.2-.44.17-.51.15-.58.13-.64.09-.71.07-.77.04-.84.01-1.27-.04-1.07-.14-.9-.2-.73-.25-.59-.3-.45-.33-.34-.34-.25-.34-.16-.33-.1-.3-.04-.25-.02-.2.01-.13v-5.34l.05-.64.13-.54.21-.46.26-.38.3-.32.33-.24.35-.2.35-.14.33-.1.3-.06.26-.04.21-.02.13-.01h5.84l.69-.05.59-.14.5-.21.41-.28.33-.32.27-.35.2-.36.15-.36.1-.35.07-.32.04-.28.02-.21V6.07h2.09l.14.01zm-6.47 14.25-.23.33-.08.41.08.41.23.33.33.23.41.08.41-.08.33-.23.23-.33.08-.41-.08-.41-.23-.33-.33-.23-.41-.08-.41.08z"/></svg></span><span class=w> </span>dolor.py
<span class=w> </span>├──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.25.18.9.2.73.26.59.3.45.32.34.34.25.34.16.33.1.3.04.26.02.2-.01.13V8.5l-.05.63-.13.55-.21.46-.26.38-.3.31-.33.25-.35.19-.35.14-.33.1-.3.07-.26.04-.21.02H8.77l-.69.05-.59.14-.5.22-.41.27-.33.32-.27.35-.2.36-.15.37-.1.35-.07.32-.04.27-.02.21v3.06H3.17l-.21-.03-.28-.07-.32-.12-.35-.18-.36-.26-.36-.36-.35-.46-.32-.59-.28-.73-.21-.88-.14-1.05-.05-1.23.06-1.22.16-1.04.24-.87.32-.71.36-.57.4-.44.42-.33.42-.24.4-.16.36-.1.32-.05.24-.01h.16l.06.01h8.16v-.83H6.18l-.01-2.75-.02-.37.05-.34.11-.31.17-.28.25-.26.31-.23.38-.2.44-.18.51-.15.58-.12.64-.1.71-.06.77-.04.84-.02 1.27.05zm-6.3 1.98-.23.33-.08.41.08.41.23.34.33.22.41.09.41-.09.33-.22.23-.34.08-.41-.08-.41-.23-.33-.33-.22-.41-.09-.41.09zm13.09 3.95.28.06.32.12.35.18.36.27.36.35.35.47.32.59.28.73.21.88.14 1.04.05 1.23-.06 1.23-.16 1.04-.24.86-.32.71-.36.57-.4.45-.42.33-.42.24-.4.16-.36.09-.32.05-.24.02-.16-.01h-8.22v.82h5.84l.01 2.76.02.36-.05.34-.11.31-.17.29-.25.25-.31.24-.38.2-.44.17-.51.15-.58.13-.64.09-.71.07-.77.04-.84.01-1.27-.04-1.07-.14-.9-.2-.73-.25-.59-.3-.45-.33-.34-.34-.25-.34-.16-.33-.1-.3-.04-.25-.02-.2.01-.13v-5.34l.05-.64.13-.54.21-.46.26-.38.3-.32.33-.24.35-.2.35-.14.33-.1.3-.06.26-.04.21-.02.13-.01h5.84l.69-.05.59-.14.5-.21.41-.28.33-.32.27-.35.2-.36.15-.36.1-.35.07-.32.04-.28.02-.21V6.07h2.09l.14.01zm-6.47 14.25-.23.33-.08.41.08.41.23.33.33.23.41.08.41-.08.33-.23.23-.33.08-.41-.08-.41-.23-.33-.33-.23-.41-.08-.41.08z"/></svg></span><span class=w> </span>sit.py
<span class=w> </span>└──<span class=w> </span><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.25.18.9.2.73.26.59.3.45.32.34.34.25.34.16.33.1.3.04.26.02.2-.01.13V8.5l-.05.63-.13.55-.21.46-.26.38-.3.31-.33.25-.35.19-.35.14-.33.1-.3.07-.26.04-.21.02H8.77l-.69.05-.59.14-.5.22-.41.27-.33.32-.27.35-.2.36-.15.37-.1.35-.07.32-.04.27-.02.21v3.06H3.17l-.21-.03-.28-.07-.32-.12-.35-.18-.36-.26-.36-.36-.35-.46-.32-.59-.28-.73-.21-.88-.14-1.05-.05-1.23.06-1.22.16-1.04.24-.87.32-.71.36-.57.4-.44.42-.33.42-.24.4-.16.36-.1.32-.05.24-.01h.16l.06.01h8.16v-.83H6.18l-.01-2.75-.02-.37.05-.34.11-.31.17-.28.25-.26.31-.23.38-.2.44-.18.51-.15.58-.12.64-.1.71-.06.77-.04.84-.02 1.27.05zm-6.3 1.98-.23.33-.08.41.08.41.23.34.33.22.41.09.41-.09.33-.22.23-.34.08-.41-.08-.41-.23-.33-.33-.22-.41-.09-.41.09zm13.09 3.95.28.06.32.12.35.18.36.27.36.35.35.47.32.59.28.73.21.88.14 1.04.05 1.23-.06 1.23-.16 1.04-.24.86-.32.71-.36.57-.4.45-.42.33-.42.24-.4.16-.36.09-.32.05-.24.02-.16-.01h-8.22v.82h5.84l.01 2.76.02.36-.05.34-.11.31-.17.29-.25.25-.31.24-.38.2-.44.17-.51.15-.58.13-.64.09-.71.07-.77.04-.84.01-1.27-.04-1.07-.14-.9-.2-.73-.25-.59-.3-.45-.33-.34-.34-.25-.34-.16-.33-.1-.3-.04-.25-.02-.2.01-.13v-5.34l.05-.64.13-.54.21-.46.26-.38.3-.32.33-.24.35-.2.35-.14.33-.1.3-.06.26-.04.21-.02.13-.01h5.84l.69-.05.59-.14.5-.21.41-.28.33-.32.27-.35.2-.36.15-.36.1-.35.07-.32.04-.28.02-.21V6.07h2.09l.14.01zm-6.47 14.25-.23.33-.08.41.08.41.23.33.33.23.41.08.41-.08.33-.23.23-.33.08-.41-.08-.41-.23-.33-.33-.23-.41-.08-.41.08z"/></svg></span><span class=w> </span>amet.py
</code></pre></div> <p>Then we will have to change our <code>set_edit_path</code> call to:</p> <div class="language-python highlight"><pre><span></span><code><span class=n>mkdocs_gen_files</span><span class=o>.</span><span class=n>set_edit_path</span><span class=p>(</span><span class=n>full_doc_path</span><span class=p>,</span> <span class=n>Path</span><span class=p>(</span><span class=s2>"../"</span><span class=p>)</span> <span class=o>/</span> <span class=n>path</span><span class=p>)</span> <span class=c1># (1)!</span>
</code></pre></div> <ol> <li>Path can be used to traverse the structure in any way you may need, but remember to use relative paths!</li> </ol> <p>...so that it correctly sets the edit path of (for example) <code>lorem.py</code> to <code><repo_url>/blob/master/src/project/lorem.py</code> instead of <code><repo_url>/blob/master/docs/src/project/lorem.py</code>.</p> </div> <p>With this script, a <code>reference</code> folder is automatically created each time we build our docs. This folder contains a Markdown page for each of our source modules, and each of these pages contains a single line of the form <code>::: project.module</code> (module being <code>lorem</code>, <code>ipsum</code>, etc.). Great! But, we still have to actually add those pages into our MkDocs navigation:</p> <div class="language-yaml highlight"><span class=filename>mkdocs.yml</span><pre><span></span><code><span class=nt>nav</span><span class=p>:</span>
<span class=c1># rest of the navigation...</span>
<span class="p p-Indicator">-</span><span class=w> </span><span class=nt>Code Reference</span><span class=p>:</span>
<span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=nt>project</span><span class=p>:</span>
<span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=nt>lorem</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">reference/project/lorem.md</span>
<span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=nt>ipsum</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">reference/project/ipsum.md</span>
<span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=nt>dolor</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">reference/project/dolor.md</span>
<span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=nt>sit</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">reference/project/sit.md</span>
<span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=nt>amet</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">reference/project/amet.md</span>
<span class=c1># rest of the navigation...</span>
</code></pre></div> <p>Err... so this process is only semi-automatic? Yes, but don't worry, we can fully automate it.</p> <h3 id=generate-a-literate-navigation-file>Generate a literate navigation file<a class=headerlink href=#generate-a-literate-navigation-file title="Permanent link">¤</a></h3> <p>mkdocs-gen-files is able to generate a literate navigation file. But to make use of it, we will need an additional plugin: <a href=https://github.com/oprypin/mkdocs-literate-nav>mkdocs-literate-nav</a>. This plugin allows to specify the whole navigation, or parts of it, into Markdown pages, as plain Markdown lists. We use it here to specify the navigation for the code reference pages.</p> <p>First, add <code>mkdocs-literate-nav</code> to your project's docs dependencies, and configure the plugin in your MkDocs configuration:</p> <div class="language-yaml highlight"><span class=filename>mkdocs.yml</span><pre><span></span><code><span class=nt>plugins</span><span class=p>:</span>
<span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">search</span>
<span class="p p-Indicator">-</span><span class=w> </span><span class=nt>gen-files</span><span class=p>:</span>
<span class=w> </span><span class=nt>scripts</span><span class=p>:</span>
<span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">scripts/gen_ref_pages.py</span>
<span class=hll><span class="p p-Indicator">-</span><span class=w> </span><span class=nt>literate-nav</span><span class=p>:</span>
</span><span class=hll><span class=w> </span><span class=nt>nav_file</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">SUMMARY.md</span>
</span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">mkdocstrings</span>
</code></pre></div> <p>Then, the previous script is updated like so:</p> <div class="language-python highlight"><span class=filename>scripts/gen_ref_pages.py</span><pre><span></span><code><span class=sd>"""Generate the code reference pages and navigation."""</span>
<span class=kn>from</span><span class=w> </span><span class=nn>pathlib</span><span class=w> </span><span class=kn>import</span> <span class=n>Path</span>
<span class=kn>import</span><span class=w> </span><span class=nn>mkdocs_gen_files</span>
<span class=hll><span class=n>nav</span> <span class=o>=</span> <span class=n>mkdocs_gen_files</span><span class=o>.</span><span class=n>Nav</span><span class=p>()</span>
</span>
<span class=n>root</span> <span class=o>=</span> <span class=n>Path</span><span class=p>(</span><span class=vm>__file__</span><span class=p>)</span><span class=o>.</span><span class=n>parent</span><span class=o>.</span><span class=n>parent</span>
<span class=n>src</span> <span class=o>=</span> <span class=n>root</span> <span class=o>/</span> <span class=s2>"src"</span>
<span class=k>for</span> <span class=n>path</span> <span class=ow>in</span> <span class=nb>sorted</span><span class=p>(</span><span class=n>src</span><span class=o>.</span><span class=n>rglob</span><span class=p>(</span><span class=s2>"*.py"</span><span class=p>)):</span>
<span class=n>module_path</span> <span class=o>=</span> <span class=n>path</span><span class=o>.</span><span class=n>relative_to</span><span class=p>(</span><span class=n>src</span><span class=p>)</span><span class=o>.</span><span class=n>with_suffix</span><span class=p>(</span><span class=s2>""</span><span class=p>)</span>
<span class=n>doc_path</span> <span class=o>=</span> <span class=n>path</span><span class=o>.</span><span class=n>relative_to</span><span class=p>(</span><span class=n>src</span><span class=p>)</span><span class=o>.</span><span class=n>with_suffix</span><span class=p>(</span><span class=s2>".md"</span><span class=p>)</span>
<span class=n>full_doc_path</span> <span class=o>=</span> <span class=n>Path</span><span class=p>(</span><span class=s2>"reference"</span><span class=p>,</span> <span class=n>doc_path</span><span class=p>)</span>
<span class=n>parts</span> <span class=o>=</span> <span class=nb>tuple</span><span class=p>(</span><span class=n>module_path</span><span class=o>.</span><span class=n>parts</span><span class=p>)</span>
<span class=k>if</span> <span class=n>parts</span><span class=p>[</span><span class=o>-</span><span class=mi>1</span><span class=p>]</span> <span class=o>==</span> <span class=s2>"__init__"</span><span class=p>:</span>
<span class=n>parts</span> <span class=o>=</span> <span class=n>parts</span><span class=p>[:</span><span class=o>-</span><span class=mi>1</span><span class=p>]</span>
<span class=k>elif</span> <span class=n>parts</span><span class=p>[</span><span class=o>-</span><span class=mi>1</span><span class=p>]</span> <span class=o>==</span> <span class=s2>"__main__"</span><span class=p>:</span>
<span class=k>continue</span>
<span class=hll> <span class=n>nav</span><span class=p>[</span><span class=n>parts</span><span class=p>]</span> <span class=o>=</span> <span class=n>doc_path</span><span class=o>.</span><span class=n>as_posix</span><span class=p>()</span> <span class=c1># (1)!</span>
</span>
<span class=k>with</span> <span class=n>mkdocs_gen_files</span><span class=o>.</span><span class=n>open</span><span class=p>(</span><span class=n>full_doc_path</span><span class=p>,</span> <span class=s2>"w"</span><span class=p>)</span> <span class=k>as</span> <span class=n>fd</span><span class=p>:</span>
<span class=n>ident</span> <span class=o>=</span> <span class=s2>"."</span><span class=o>.</span><span class=n>join</span><span class=p>(</span><span class=n>parts</span><span class=p>)</span>
<span class=n>fd</span><span class=o>.</span><span class=n>write</span><span class=p>(</span><span class=sa>f</span><span class=s2>"::: </span><span class=si>{</span><span class=n>ident</span><span class=si>}</span><span class=s2>"</span><span class=p>)</span>
<span class=n>mkdocs_gen_files</span><span class=o>.</span><span class=n>set_edit_path</span><span class=p>(</span><span class=n>full_doc_path</span><span class=p>,</span> <span class=n>path</span><span class=o>.</span><span class=n>relative_to</span><span class=p>(</span><span class=n>root</span><span class=p>))</span>
<span class=hll><span class=k>with</span> <span class=n>mkdocs_gen_files</span><span class=o>.</span><span class=n>open</span><span class=p>(</span><span class=s2>"reference/SUMMARY.md"</span><span class=p>,</span> <span class=s2>"w"</span><span class=p>)</span> <span class=k>as</span> <span class=n>nav_file</span><span class=p>:</span> <span class=c1># (2)!</span>
</span><span class=hll> <span class=n>nav_file</span><span class=o>.</span><span class=n>writelines</span><span class=p>(</span><span class=n>nav</span><span class=o>.</span><span class=n>build_literate_nav</span><span class=p>())</span> <span class=c1># (3)!</span>
</span></code></pre></div> <ol> <li>Progressively build the navigation object.</li> <li>At the end, create a magic, literate navigation file called <code>SUMMARY.md</code> in the <code>reference</code> folder.</li> <li>Write the navigation as a Markdown list in the literate navigation file.</li> </ol> <p>Now we are able to remove our hard-coded navigation in <code>mkdocs.yml</code>, and replace it with a single line!</p> <div class="language-yaml highlight"><span class=filename>mkdocs.yml</span><pre><span></span><code><span class=nt>nav</span><span class=p>:</span>
<span class=c1># rest of the navigation...</span>
<span class=c1># defer to gen-files + literate-nav</span>
<span class="p p-Indicator">-</span><span class=w> </span><span class=nt>Code Reference</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">reference/</span><span class=w> </span><span class=c1># (1)!</span>
<span class=c1># rest of the navigation...</span>
</code></pre></div> <ol> <li>Note the trailing slash! It is needed so that <code>mkdocs-literate-nav</code> knows it has to look for a <code>SUMMARY.md</code> file in that folder.</li> </ol> <p>At this point, we should be able to see the tree of our modules in the navigation.</p> <h3 id=bind-pages-to-sections-themselves>Bind pages to sections themselves<a class=headerlink href=#bind-pages-to-sections-themselves title="Permanent link">¤</a></h3> <p>There's a last improvement we can do. With the current script, sections, corresponding to folders, will expand or collapse when you click on them, revealing <code>__init__</code> modules under them (or equivalent modules in other languages, if relevant). Since we are documenting a public API, and given users never explicitly import <code>__init__</code> modules, it would be nice if we could get rid of them and instead render their documentation inside the section itself.</p> <p>Well, this is possible thanks to a third plugin: <a href=https://github.com/oprypin/mkdocs-section-index>mkdocs-section-index</a>.</p> <p>Update the script like this:</p> <div class="language-python highlight"><span class=filename>scripts/gen_ref_pages.py</span><pre><span></span><code><span class=sd>"""Generate the code reference pages and navigation."""</span>
<span class=kn>from</span><span class=w> </span><span class=nn>pathlib</span><span class=w> </span><span class=kn>import</span> <span class=n>Path</span>
<span class=kn>import</span><span class=w> </span><span class=nn>mkdocs_gen_files</span>
<span class=n>nav</span> <span class=o>=</span> <span class=n>mkdocs_gen_files</span><span class=o>.</span><span class=n>Nav</span><span class=p>()</span>
<span class=n>root</span> <span class=o>=</span> <span class=n>Path</span><span class=p>(</span><span class=vm>__file__</span><span class=p>)</span><span class=o>.</span><span class=n>parent</span><span class=o>.</span><span class=n>parent</span>
<span class=n>src</span> <span class=o>=</span> <span class=n>root</span> <span class=o>/</span> <span class=s2>"src"</span>
<span class=k>for</span> <span class=n>path</span> <span class=ow>in</span> <span class=nb>sorted</span><span class=p>(</span><span class=n>src</span><span class=o>.</span><span class=n>rglob</span><span class=p>(</span><span class=s2>"*.py"</span><span class=p>)):</span>
<span class=n>module_path</span> <span class=o>=</span> <span class=n>path</span><span class=o>.</span><span class=n>relative_to</span><span class=p>(</span><span class=n>src</span><span class=p>)</span><span class=o>.</span><span class=n>with_suffix</span><span class=p>(</span><span class=s2>""</span><span class=p>)</span>
<span class=n>doc_path</span> <span class=o>=</span> <span class=n>path</span><span class=o>.</span><span class=n>relative_to</span><span class=p>(</span><span class=n>src</span><span class=p>)</span><span class=o>.</span><span class=n>with_suffix</span><span class=p>(</span><span class=s2>".md"</span><span class=p>)</span>
<span class=n>full_doc_path</span> <span class=o>=</span> <span class=n>Path</span><span class=p>(</span><span class=s2>"reference"</span><span class=p>,</span> <span class=n>doc_path</span><span class=p>)</span>
<span class=n>parts</span> <span class=o>=</span> <span class=nb>tuple</span><span class=p>(</span><span class=n>module_path</span><span class=o>.</span><span class=n>parts</span><span class=p>)</span>
<span class=k>if</span> <span class=n>parts</span><span class=p>[</span><span class=o>-</span><span class=mi>1</span><span class=p>]</span> <span class=o>==</span> <span class=s2>"__init__"</span><span class=p>:</span>
<span class=n>parts</span> <span class=o>=</span> <span class=n>parts</span><span class=p>[:</span><span class=o>-</span><span class=mi>1</span><span class=p>]</span>
<span class=hll> <span class=n>doc_path</span> <span class=o>=</span> <span class=n>doc_path</span><span class=o>.</span><span class=n>with_name</span><span class=p>(</span><span class=s2>"index.md"</span><span class=p>)</span>
</span><span class=hll> <span class=n>full_doc_path</span> <span class=o>=</span> <span class=n>full_doc_path</span><span class=o>.</span><span class=n>with_name</span><span class=p>(</span><span class=s2>"index.md"</span><span class=p>)</span>
</span> <span class=k>elif</span> <span class=n>parts</span><span class=p>[</span><span class=o>-</span><span class=mi>1</span><span class=p>]</span> <span class=o>==</span> <span class=s2>"__main__"</span><span class=p>:</span>
<span class=k>continue</span>
<span class=n>nav</span><span class=p>[</span><span class=n>parts</span><span class=p>]</span> <span class=o>=</span> <span class=n>doc_path</span><span class=o>.</span><span class=n>as_posix</span><span class=p>()</span>
<span class=k>with</span> <span class=n>mkdocs_gen_files</span><span class=o>.</span><span class=n>open</span><span class=p>(</span><span class=n>full_doc_path</span><span class=p>,</span> <span class=s2>"w"</span><span class=p>)</span> <span class=k>as</span> <span class=n>fd</span><span class=p>:</span>
<span class=n>ident</span> <span class=o>=</span> <span class=s2>"."</span><span class=o>.</span><span class=n>join</span><span class=p>(</span><span class=n>parts</span><span class=p>)</span>
<span class=n>fd</span><span class=o>.</span><span class=n>write</span><span class=p>(</span><span class=sa>f</span><span class=s2>"::: </span><span class=si>{</span><span class=n>ident</span><span class=si>}</span><span class=s2>"</span><span class=p>)</span>
<span class=n>mkdocs_gen_files</span><span class=o>.</span><span class=n>set_edit_path</span><span class=p>(</span><span class=n>full_doc_path</span><span class=p>,</span> <span class=n>path</span><span class=o>.</span><span class=n>relative_to</span><span class=p>(</span><span class=n>root</span><span class=p>))</span>
<span class=k>with</span> <span class=n>mkdocs_gen_files</span><span class=o>.</span><span class=n>open</span><span class=p>(</span><span class=s2>"reference/SUMMARY.md"</span><span class=p>,</span> <span class=s2>"w"</span><span class=p>)</span> <span class=k>as</span> <span class=n>nav_file</span><span class=p>:</span>
<span class=n>nav_file</span><span class=o>.</span><span class=n>writelines</span><span class=p>(</span><span class=n>nav</span><span class=o>.</span><span class=n>build_literate_nav</span><span class=p>())</span>
</code></pre></div> <p>And update your MkDocs configuration to list the plugin:</p> <div class="language-yaml highlight"><span class=filename>mkdocs.yml</span><pre><span></span><code><span class=nt>plugins</span><span class=p>:</span>
<span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">search</span>
<span class="p p-Indicator">-</span><span class=w> </span><span class=nt>gen-files</span><span class=p>:</span>
<span class=w> </span><span class=nt>scripts</span><span class=p>:</span>
<span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">scripts/gen_ref_pages.py</span>
<span class="p p-Indicator">-</span><span class=w> </span><span class=nt>literate-nav</span><span class=p>:</span>
<span class=w> </span><span class=nt>nav_file</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">SUMMARY.md</span>
<span class=hll><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">section-index</span>
</span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">mkdocstrings</span>
</code></pre></div> <p>With this, <code>__init__</code> modules will be documented and bound to the sections themselves, better reflecting our public API.</p> <h2 id=prevent-selection-of-prompts-and-output-in-python-code-blocks>Prevent selection of prompts and output in Python code blocks<a class=headerlink href=#prevent-selection-of-prompts-and-output-in-python-code-blocks title="Permanent link">¤</a></h2> <p>To prevent the selection of <code>>>></code>, <code>...</code> and output in Python "Console" code blocks, you can use the <code>pycon</code> syntax highlighting on your code blocks, and add global CSS rules to your site using MkDocs <code>extra_css</code> option:</p> <div class="language-md highlight"><pre><span></span><code><span class=sb>```pycon</span>
<span class=gp>>>> </span><span class=k>for</span> <span class=n>word</span> <span class=ow>in</span> <span class=p>(</span><span class=s2>"Hello"</span><span class=p>,</span> <span class=s2>"mkdocstrings!"</span><span class=p>):</span>
<span class=gp>... </span> <span class=nb>print</span><span class=p>(</span><span class=n>word</span><span class=p>,</span> <span class=n>end</span><span class=o>=</span><span class=s2>" "</span><span class=p>)</span>
<span class=gp>...</span>
<span class=go>Hello mkdocstrings!</span>
<span class=sb>```</span>
</code></pre></div> <div class="language-css highlight"><span class=filename>docs/css/code_select.css</span><pre><span></span><code><span class=p>.</span><span class=nc>highlight</span><span class=w> </span><span class=p>.</span><span class=nc>gp</span><span class=o>,</span><span class=w> </span><span class=p>.</span><span class=nc>highlight</span><span class=w> </span><span class=p>.</span><span class=nc>go</span><span class=w> </span><span class=p>{</span><span class=w> </span><span class=c>/* Generic.Prompt, Generic.Output */</span>
<span class=w> </span><span class=k>user-select</span><span class=p>:</span><span class=w> </span><span class=kc>none</span><span class=p>;</span>
<span class=p>}</span>
</code></pre></div> <div class="language-yaml highlight"><span class=filename>mkdocs.yml</span><pre><span></span><code><span class=nt>extra_css</span><span class=p>:</span>
<span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">css/code_select.css</span>
</code></pre></div> <div class="admonition warning"> <p class=admonition-title>Warning</p> <p> The <code>.highlight .gp, .highlight .go</code> CSS selector can have unintended side-effects. To target <code>pycon</code> code blocks more specifically, you can configure the <code>pymdownx.highlight</code> extension to use Pygments and set language classes on code blocks:</p> <div class="language-yaml highlight"><span class=filename>mkdocs.yml</span><pre><span></span><code><span class=nt>markdown_extensions</span><span class=p>:</span>
<span class="p p-Indicator">-</span><span class=w> </span><span class=nt>pymdownx.highlight</span><span class=p>:</span>
<span class=w> </span><span class=nt>use_pygments</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class=w> </span><span class=nt>pygments_lang_class</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
</code></pre></div> <p>Then you can update the CSS selector like this:</p> <div class="language-css highlight"><span class=filename>docs/css/code_select.css</span><pre><span></span><code><span class=p>.</span><span class=nc>language-pycon</span><span class=w> </span><span class=p>.</span><span class=nc>gp</span><span class=o>,</span><span class=w> </span><span class=p>.</span><span class=nc>language-pycon</span><span class=w> </span><span class=p>.</span><span class=nc>go</span><span class=w> </span><span class=p>{</span><span class=w> </span><span class=c>/* Generic.Prompt, Generic.Output */</span>
<span class=w> </span><span class=k>user-select</span><span class=p>:</span><span class=w> </span><span class=kc>none</span><span class=p>;</span>
<span class=p>}</span>
</code></pre></div> </div> <p>If you don't want to enable this globally, you can still use <code>style</code> tags in the relevant pages, with more accurate CSS selectors:</p> <div class="language-html highlight"><pre><span></span><code><span class=p><</span><span class=nt>style</span><span class=p>></span>
<span class=p>#</span><span class=nn>my-div</span><span class=w> </span><span class=p>.</span><span class=nc>highlight</span><span class=w> </span><span class=p>.</span><span class=nc>gp</span><span class=o>,</span><span class=w> </span><span class=p>#</span><span class=nn>my-div</span><span class=w> </span><span class=p>.</span><span class=nc>highlight</span><span class=w> </span><span class=p>.</span><span class=nc>go</span><span class=w> </span><span class=p>{</span><span class=w> </span><span class=c>/* Generic.Prompt, Generic.Output */</span>
<span class=w> </span><span class=k>user-select</span><span class=p>:</span><span class=w> </span><span class=kc>none</span><span class=p>;</span>
<span class=p>}</span>
<span class=p></</span><span class=nt>style</span><span class=p>></span>
</code></pre></div> <p>Try to select the following code block's text:</p> <style>
.highlight .gp, .highlight .go { /* Generic.Prompt, Generic.Output */
user-select: none;
}
</style> <div class="language-pycon highlight"><pre><span></span><code><span class=gp>>>> </span><span class=k>for</span> <span class=n>word</span> <span class=ow>in</span> <span class=p>(</span><span class=s2>"Hello"</span><span class=p>,</span> <span class=s2>"mkdocstrings!"</span><span class=p>):</span>
<span class=gp>... </span> <span class=nb>print</span><span class=p>(</span><span class=n>word</span><span class=p>,</span> <span class=n>end</span><span class=o>=</span><span class=s2>" "</span><span class=p>)</span>
<span class=go>Hello mkdocstrings!</span>
</code></pre></div> <h2 id=hide-documentation-strings-from-source-code-blocks>Hide documentation strings from source code blocks<a class=headerlink href=#hide-documentation-strings-from-source-code-blocks title="Permanent link">¤</a></h2> <p>Since documentation strings are rendered by handlers, it can sometimes feel redundant to show these same documentation strings in source code blocks (when handlers render those).</p> <p>There is a general workaround to hide these docstrings from source blocks using CSS:</p> <div class="language-css highlight"><pre><span></span><code><span class=c>/* These CSS classes depend on the handler. */</span>
<span class=p>.</span><span class=nc>doc-contents</span><span class=w> </span><span class=nt>details</span><span class=w> </span><span class=p>.</span><span class=nc>highlight</span><span class=w> </span><span class=nt>code</span><span class=w> </span><span class=p>{</span>
<span class=w> </span><span class=k>line-height</span><span class=p>:</span><span class=w> </span><span class=mi>0</span><span class=p>;</span>
<span class=p>}</span>
<span class=p>.</span><span class=nc>doc-contents</span><span class=w> </span><span class=nt>details</span><span class=w> </span><span class=p>.</span><span class=nc>highlight</span><span class=w> </span><span class=nt>code</span><span class=w> </span><span class=o>></span><span class=w> </span><span class=o>*</span><span class=w> </span><span class=p>{</span>
<span class=w> </span><span class=k>line-height</span><span class=p>:</span><span class=w> </span><span class=kc>initial</span><span class=p>;</span>
<span class=p>}</span>
<span class=p>.</span><span class=nc>doc-contents</span><span class=w> </span><span class=nt>details</span><span class=w> </span><span class=p>.</span><span class=nc>highlight</span><span class=w> </span><span class=nt>code</span><span class=w> </span><span class=o>></span><span class=w> </span><span class=p>.</span><span class=nc>sd</span><span class=w> </span><span class=p>{</span><span class=w> </span><span class=c>/* Literal.String.Doc */</span>
<span class=w> </span><span class=k>display</span><span class=p>:</span><span class=w> </span><span class=kc>none</span><span class=p>;</span>
<span class=p>}</span>
</code></pre></div> <p>Note that this is considered a workaround and not a proper solution, because it has side-effects like also removing blank lines.</p> <h2 id=automatic-highlighting-for-indented-code-blocks-in-docstrings>Automatic highlighting for indented code blocks in docstrings<a class=headerlink href=#automatic-highlighting-for-indented-code-blocks-in-docstrings title="Permanent link">¤</a></h2> <p>Depending on the language used in your code base and the mkdocstrings handler used to document it, you might want to set a default syntax for code blocks added to your docstrings. For example, to default to the Python syntax:</p> <div class="language-yaml highlight"><span class=filename>mkdocs.yml</span><pre><span></span><code><span class=nt>markdown_extensions</span><span class=p>:</span>
<span class="p p-Indicator">-</span><span class=w> </span><span class=nt>pymdownx.highlight</span><span class=p>:</span>
<span class=w> </span><span class=nt>default_lang</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">python</span>
</code></pre></div> <p>Then in your docstrings, indented code blocks will be highlighted as Python code:</p> <div class="language-python highlight"><pre><span></span><code><span class=k>def</span><span class=w> </span><span class=nf>my_function</span><span class=p>():</span>
<span class=w> </span><span class=sd>"""This is my function.</span>
<span class=sd> The following code will be highlighted as Python:</span>
<span class=sd> result = my_function()</span>
<span class=sd> print(result)</span>
<span class=sd> End of the docstring.</span>
<span class=sd> """</span>
<span class=k>pass</span>
</code></pre></div> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago" title="January 31, 2025 12:11:37"><span class=timeago datetime=2025-01-31T12:11:37+00:00 locale=en></span></span><span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date" title="January 31, 2025 12:11:37">2025-01-31</span> </span> <span class=md-source-file__fact> <span class=md-icon title=Created> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M14.47 15.08 11 13V7h1.5v5.25l3.08 1.83c-.41.28-.79.62-1.11 1m-1.39 4.84c-.36.05-.71.08-1.08.08-4.42 0-8-3.58-8-8s3.58-8 8-8 8 3.58 8 8c0 .37-.03.72-.08 1.08.69.1 1.33.32 1.92.64.1-.56.16-1.13.16-1.72 0-5.5-4.5-10-10-10S2 6.5 2 12s4.47 10 10 10c.59 0 1.16-.06 1.72-.16-.32-.59-.54-1.23-.64-1.92M18 15v3h-3v2h3v3h2v-3h3v-2h-3v-3z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago" title="February 7, 2022 18:09:08"><span class=timeago datetime=2022-02-07T18:09:08+00:00 locale=en></span></span><span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date" title="February 7, 2022 18:09:08">2022-02-07</span> </span> </aside> <form class=md-feedback name=feedback hidden> <fieldset> <legend class=md-feedback__title> Was this page helpful? </legend> <div class=md-feedback__inner> <div class=md-feedback__list> <button class="md-feedback__icon md-icon" type=submit title="This page was helpful" data-md-value=1> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 12a8 8 0 0 0-8-8 8 8 0 0 0-8 8 8 8 0 0 0 8 8 8 8 0 0 0 8-8m2 0a10 10 0 0 1-10 10A10 10 0 0 1 2 12 10 10 0 0 1 12 2a10 10 0 0 1 10 10M10 9.5c0 .8-.7 1.5-1.5 1.5S7 10.3 7 9.5 7.7 8 8.5 8s1.5.7 1.5 1.5m7 0c0 .8-.7 1.5-1.5 1.5S14 10.3 14 9.5 14.7 8 15.5 8s1.5.7 1.5 1.5m-5 7.73c-1.75 0-3.29-.73-4.19-1.81L9.23 14c.45.72 1.52 1.23 2.77 1.23s2.32-.51 2.77-1.23l1.42 1.42c-.9 1.08-2.44 1.81-4.19 1.81"/></svg> </button> <button class="md-feedback__icon md-icon" type=submit title="This page could be improved" data-md-value=0> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 12a8 8 0 0 0-8-8 8 8 0 0 0-8 8 8 8 0 0 0 8 8 8 8 0 0 0 8-8m2 0a10 10 0 0 1-10 10A10 10 0 0 1 2 12 10 10 0 0 1 12 2a10 10 0 0 1 10 10m-6.5-4c.8 0 1.5.7 1.5 1.5s-.7 1.5-1.5 1.5-1.5-.7-1.5-1.5.7-1.5 1.5-1.5M10 9.5c0 .8-.7 1.5-1.5 1.5S7 10.3 7 9.5 7.7 8 8.5 8s1.5.7 1.5 1.5m2 4.5c1.75 0 3.29.72 4.19 1.81l-1.42 1.42C14.32 16.5 13.25 16 12 16s-2.32.5-2.77 1.23l-1.42-1.42C8.71 14.72 10.25 14 12 14"/></svg> </button> </div> <div class=md-feedback__note> <div data-md-value=1 hidden> Thanks for your feedback! </div> <div data-md-value=0 hidden> Let us know how we can improve this page. </div> </div> </div> </fieldset> </form> <!-- Giscus --> <!-- https://squidfunk.github.io/mkdocs-material/setup/adding-a-comment-system/#giscus-integration --> <div id=feedback style="display: none;"> <h2 id=__comments>Feedback</h2> <script src=https://giscus.app/client.js data-repo=mkdocstrings/mkdocstrings data-repo-id="MDEwOlJlcG9zaXRvcnkyMjY5MzY0MTY=" data-category=Documentation data-category-id=DIC_kwDODYbGYM4ChKXy data-mapping=pathname data-strict=1 data-reactions-enabled=0 data-emit-metadata=0 data-input-position=top data-theme=preferred_color_scheme data-lang=en data-loading=lazy crossorigin=anonymous async>
</script> <!-- Synchronize Giscus theme with palette --> <script>
var giscus = document.querySelector("script[src*=giscus]")
// Set palette on initial load
var palette = __md_get("__palette")
if (palette && typeof palette.color === "object") {
var theme = palette.color.scheme === "slate"
? "transparent_dark"
: "light"
// Instruct Giscus to set theme
giscus.setAttribute("data-theme", theme)
}
// Register event handlers after documented loaded
document.addEventListener("DOMContentLoaded", function() {
var ref = document.querySelector("[data-md-component=palette]")
ref.addEventListener("change", function() {
var palette = __md_get("__palette")
if (palette && typeof palette.color === "object") {
var theme = palette.color.scheme === "slate"
? "transparent_dark"
: "light"
// Instruct Giscus to change theme
var frame = document.querySelector(".giscus-frame")
frame.contentWindow.postMessage(
{ giscus: { setConfig: { theme } } },
"https://giscus.app"
)
}
})
})
</script> </div> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../usage/handlers/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Handlers"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> Handlers </div> </div> </a> <a href=../troubleshooting/ class="md-footer__link md-footer__link--next" aria-label="Next: Troubleshooting"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Troubleshooting </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2019 Timothée Mazzucotelli </div> Made with <a href=https://squidfunk.github.io/mkdocs-material/ target=_blank rel=noopener> Material for MkDocs Insiders </a> </div> <div class=md-social> <a href=https://github.com/pawamoy target=_blank rel=noopener title=github.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 496 512"><!-- Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8M97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href=https://fosstodon.org/@pawamoy target=_blank rel="noopener me" title=fosstodon.org class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M433 179.11c0-97.2-63.71-125.7-63.71-125.7-62.52-28.7-228.56-28.4-290.48 0 0 0-63.72 28.5-63.72 125.7 0 115.7-6.6 259.4 105.63 289.1 40.51 10.7 75.32 13 103.33 11.4 50.81-2.8 79.32-18.1 79.32-18.1l-1.7-36.9s-36.31 11.4-77.12 10.1c-40.41-1.4-83-4.4-89.63-54a102.5 102.5 0 0 1-.9-13.9c85.63 20.9 158.65 9.1 178.75 6.7 56.12-6.7 105-41.3 111.23-72.9 9.8-49.8 9-121.5 9-121.5m-75.12 125.2h-46.63v-114.2c0-49.7-64-51.6-64 6.9v62.5h-46.33V197c0-58.5-64-56.6-64-6.9v114.2H90.19c0-122.1-5.2-147.9 18.41-175 25.9-28.9 79.82-30.8 103.83 6.1l11.6 19.5 11.6-19.5c24.11-37.1 78.12-34.8 103.83-6.1 23.71 27.3 18.4 53 18.4 175z"/></svg> </a> <a href=https://twitter.com/pawamoy target=_blank rel=noopener title=twitter.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253"/></svg> </a> <a href=https://gitter.im/mkdocstrings/community target=_blank rel=noopener title=gitter.im class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M66.4 322.5H16V0h50.4zM166.9 76.1h-50.4V512h50.4zm100.6 0h-50.4V512h50.4zM368 76h-50.4v247H368z"/></svg> </a> <a href=https://pypi.org/project/mkdocstrings/ target=_blank rel=noopener title=pypi.org class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M439.8 200.5c-7.7-30.9-22.3-54.2-53.4-54.2h-40.1v47.4c0 36.8-31.2 67.8-66.8 67.8H172.7c-29.2 0-53.4 25-53.4 54.3v101.8c0 29 25.2 46 53.4 54.3 33.8 9.9 66.3 11.7 106.8 0 26.9-7.8 53.4-23.5 53.4-54.3v-40.7H226.2v-13.6h160.2c31.1 0 42.6-21.7 53.4-54.2 11.2-33.5 10.7-65.7 0-108.6M286.2 404c11.1 0 20.1 9.1 20.1 20.3 0 11.3-9 20.4-20.1 20.4-11 0-20.1-9.2-20.1-20.4.1-11.3 9.1-20.3 20.1-20.3M167.8 248.1h106.8c29.7 0 53.4-24.5 53.4-54.3V91.9c0-29-24.4-50.7-53.4-55.6-35.8-5.9-74.7-5.6-106.8.1-45.2 8-53.4 24.7-53.4 55.6v40.7h106.9v13.6h-147c-31.1 0-58.3 18.7-66.8 54.2-9.8 40.7-10.2 66.1 0 108.6 7.6 31.6 25.7 54.2 56.8 54.2H101v-48.8c0-35.3 30.5-66.4 66.8-66.4m-6.7-142.6c-11.1 0-20.1-9.1-20.1-20.3.1-11.3 9-20.4 20.1-20.4 11 0 20.1 9.2 20.1 20.4s-9 20.3-20.1 20.3"/></svg> </a> </div> </div> </div> </footer> </div> <div class=md-dialog data-md-component=dialog> <div class="md-dialog__inner md-typeset"></div> </div> <script id=__config type=application/json>{"base": "..", "features": ["announce.dismiss", "content.action.edit", "content.action.view", "content.code.annotate", "content.code.copy", "content.tooltips", "navigation.footer", "navigation.instant.preview", "navigation.path", "navigation.sections", "navigation.tabs", "navigation.tabs.sticky", "navigation.top", "search.highlight", "search.suggest", "toc.follow"], "search": "../assets/javascripts/workers/search.c7c1ca2c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src=../assets/javascripts/bundle.f807c082.min.js></script> <script src=../assets/_markdown_exec_pyodide.js></script> <script src=../js/timeago.min.js></script> <script src=../js/timeago_mkdocs_material.js></script> <script src=../js/feedback.js></script> </body> </html>