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
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
|
{% extends "frame.html.jinja2" %}
{% block title %}{{ module.modulename }} API documentation{% endblock %}
{% block nav %}
{% block module_list_link %}
{% set parentmodule = ".".join(module.modulename.split(".")[:-1]) %}
{% if parentmodule and parentmodule in all_modules %}
<a class="pdoc-button module-list-button" href="../{{ parentmodule.split(".")[-1] }}.html">
{% include "resources/box-arrow-in-left.svg" %}
{{- parentmodule -}}
</a>
{% elif not root_module_name %}
<a class="pdoc-button module-list-button" href="{{ "../" * module.modulename.count(".") }}index.html">
{% include "resources/box-arrow-in-left.svg" %}
Module Index
</a>
{% endif %}
{% endblock %}
{% block nav_title %}
{% if logo %}
{% if logo_link %}<a href="{{ logo_link }}">{% endif %}
<img src="{{ logo }}" class="logo" alt="project logo"/>
{% if logo_link %}</a>{% endif %}
{% endif %}
{% endblock %}
{% block search_box %}
{% if search and all_modules|length > 1 %}
{# we set a pattern here so that we can use the :valid CSS selector #}
<input type="search" placeholder="Search..." role="searchbox" aria-label="search"
pattern=".+" required>
{% endif %}
{% endblock %}
{% block nav_index %}
{% set index = module.docstring | to_markdown | to_html | attr("toc_html") %}
{% if index %}
<h2>Contents</h2>
{{ index | safe }}
{% endif %}
{% endblock %}
{% block nav_submodules %}
{% if module.submodules %}
<h2>Submodules</h2>
<ul>
{% for submodule in module.submodules if is_public(submodule) | trim %}
<li>{{ submodule.taken_from | link(text=submodule.name) }}</li>
{% endfor %}
</ul>
{% endif %}
{% endblock %}
{% block nav_members %}
{% if module.members %}
<h2>API Documentation</h2>
{{ nav_members(module.members.values()) }}
{% endif %}
{% endblock %}
{% block nav_footer %}
{% if footer_text %}
<footer>{{ footer_text }}</footer>
{% endif %}
{% endblock %}
{% block attribution %}
<a class="attribution" title="pdoc: Python API documentation generator" href="https://pdoc.dev" target="_blank">
built with <span class="visually-hidden">pdoc</span><img
alt="pdoc logo"
src="data:image/svg+xml,
{%- filter urlencode %}{% include "resources/pdoc-logo.svg" %}{% endfilter %}"/>
</a>
{% endblock %}
{% endblock nav %}
{% block content %}
<main class="pdoc">
{% block module_info %}
<section class="module-info">
{% block edit_button %}
{% if edit_url %}
{% if "github.com" in edit_url %}
{% set edit_text = "Edit on GitHub" %}
{% elif "gitlab" in edit_url %}
{% set edit_text = "Edit on GitLab" %}
{% else %}
{% set edit_text = "Edit Source" %}
{% endif %}
<a class="pdoc-button git-button" href="{{ edit_url }}">{{ edit_text }}</a>
{% endif %}
{% endblock %}
{{ module_name() }}
{{ docstring(module) }}
{{ view_source_state(module) }}
{{ view_source_button(module) }}
{{ view_source_code(module) }}
</section>
{% endblock %}
{% block module_contents %}
{% for m in module.flattened_own_members if is_public(m) | trim %}
<section id="{{ m.qualname or m.name }}">
{{ member(m) }}
{% if m.kind == "class" %}
{% for m in m.own_members if m.kind != "class" and is_public(m) | trim %}
<div id="{{ m.qualname }}" class="classattr">
{{ member(m) }}
</div>
{% endfor %}
{% set inherited_members = inherited(m) | trim %}
{% if inherited_members %}
<div class="inherited">
<h5>Inherited Members</h5>
<dl>
{{ inherited_members }}
</dl>
</div>
{% endif %}
{% endif %}
</section>
{% endfor %}
{% endblock %}
</main>
{% if mtime %}
{% include "livereload.html.jinja2" %}
{% endif %}
{% block search_js %}
{% if search and all_modules|length > 1 %}
{% include "search.html.jinja2" %}
{% endif %}
{% endblock %}
{% endblock content %}
{#
End of content, beginning of helper macros.
See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an explanation of defaultmacro.
#}
{% defaultmacro bases(cls) %}
{%- if cls.bases -%}
<wbr>(
{%- for base in cls.bases -%}
<span class="base">{{ base[:2] | link(text=base[2]) }}</span>
{%- if loop.nextitem %}, {% endif %}
{%- endfor -%}
)
{%- endif -%}
{% enddefaultmacro %}
{% defaultmacro default_value(var) -%}
{%- if var.default_value_str %}
=
{% if var.default_value_str | length > 100 -%}
<input id="{{ var.qualname }}-view-value" class="view-value-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
<label class="view-value-button pdoc-button" for="{{ var.qualname }}-view-value"></label>
{%- endif -%}
<span class="default_value">{{ var.default_value_str | escape | linkify }}</span>
{%- endif -%}
{% enddefaultmacro %}
{% defaultmacro annotation(var) %}
{%- if var.annotation_str -%}
<span class="annotation">{{ var.annotation_str | escape | linkify }}</span>
{%- endif -%}
{% enddefaultmacro %}
{% defaultmacro decorators(doc) %}
{% for d in doc.decorators if not d.startswith("@_") %}
<div class="decorator decorator-{{ d[1:].partition("(")[0] }}">{{ d }}</div>
{% endfor %}
{% enddefaultmacro %}
{% defaultmacro function(fn) -%}
{{ decorators(fn) }}
{% if fn.name == "__init__" %}
<span class="name">{{ ".".join(fn.qualname.split(".")[:-1]) }}</span>
{{- fn.signature_without_self | format_signature(colon=False) | linkify }}
{% else %}
<span class="def">{{ fn.funcdef }}</span>
<span class="name">{{ fn.name }}</span>
{{- fn.signature | format_signature(colon=True) | linkify }}
{% endif %}
{% enddefaultmacro %}
{% defaultmacro variable(var) -%}
{%- if var.is_type_alias_type %}<span class="def">type</span> {% endif -%}
<span class="name">{{ var.name }}</span>{{ annotation(var) }}{{ default_value(var) }}
{% enddefaultmacro %}
{% defaultmacro submodule(mod) -%}
<span class="name">{{ mod.taken_from | link }}</span>
{% enddefaultmacro %}
{% defaultmacro class(cls) -%}
{{ decorators(cls) }}
<span class="def">class</span>
<span class="name">{{ cls.qualname }}</span>
{{- bases(cls) -}}:
{% enddefaultmacro %}
{% defaultmacro member(doc) %}
{{- view_source_state(doc) -}}
<div class="attr {{ doc.kind }}">
{% if doc.kind == "class" %}
{{ class(doc) }}
{% elif doc.kind == "function" %}
{{ function(doc) }}
{% elif doc.kind == "module" %}
{{ submodule(doc) }}
{% else %}
{{ variable(doc) }}
{% endif %}
{{ view_source_button(doc) }}
</div>
<a class="headerlink" href="#{{ doc.qualname or doc.name }}"></a>
{{ view_source_code(doc) }}
{{ docstring(doc) }}
{% enddefaultmacro %}
{% defaultmacro docstring(var) %}
{% if var.docstring %}
<div class="docstring">{{ var.docstring | replace("@public", "") | to_markdown | to_html | linkify(namespace=var.qualname, shorten=False) }}</div>
{% endif %}
{% enddefaultmacro %}
{% defaultmacro nav_members(members) %}
<ul class="memberlist">
{% for m in members if is_public(m) | trim %}
<li>
{% if m.kind == "class" %}
<a class="class" href="#{{ m.qualname }}">{{ m.qualname }}</a>
{% if m.own_members %}
{{ nav_members(m.own_members) | indent(12) }}
{% endif %}
{% elif m.kind == "module" %}
<a class="module" href="#{{ m.name }}">{{ m.name }}</a>
{% elif m.name == "__init__" %}
<a class="function" href="#{{ m.qualname }}">{{ m.qualname.split(".")[-2] }}</a>
{% else %}
<a class="{{ m.kind }}" href="#{{ m.qualname }}">{{ m.name }}</a>
{% endif %}
</li>
{% endfor %}
</ul>
{% enddefaultmacro %}
{% defaultmacro is_public(doc) %}
{#
This macro is a bit unconventional in that its output is not rendered, but treated as a boolean:
Returning no text is interpreted as false, returning any other text is iterpreted as true.
Implementing this as a macro makes it very easy to override with a custom template, see
https://github.com/mitmproxy/pdoc/tree/main/examples/custom-template.
#}
{% if "@private" in doc.docstring %}
{# hide members explicitly marked as @private #}
{% elif "@public" in doc.docstring %}
{# show members explicitly marked as @public #}
true
{% elif not include_undocumented and not doc.docstring and doc.kind != "module" %}
{# hide members that are undocumented if include_undocumented has been toggled off. #}
{% elif doc.name == "__init__" and (doc.docstring or (doc.kind == "function" and doc.signature_without_self.parameters)) %}
{# show constructors that have a docstring or at least one extra argument #}
true
{% elif doc.name == "__doc__" %}
{# We don't want to document __doc__ itself, https://github.com/mitmproxy/pdoc/issues/235 #}
{% elif doc.kind == "variable" and doc.is_typevar and not doc.docstring %}
{# do not document TypeVars, that only clutters the docs. #}
{% elif doc.kind == "module" and doc.fullname not in all_modules %}
{# Skip modules that were manually excluded, https://github.com/mitmproxy/pdoc/issues/334 #}
{% elif (doc.qualname or doc.name) is in(module.obj.__all__ or []) %}
{# members starting with an underscore are still public if mentioned in __all__ #}
true
{% elif not doc.name.startswith("_") %}
{# members not starting with an underscore are considered public by default #}
true
{% endif %}
{% enddefaultmacro %}
{# fmt: off #}
{% defaultmacro inherited(cls) %}
{% for base, members in cls.inherited_members.items() %}
{% if base[0] not in all_modules %}
{# hide inherited members from modules that are not in the documentation, https://github.com/mitmproxy/pdoc/issues/715 #}
{% continue %}
{% endif %}
{% set m = None %}{# workaround for https://github.com/pallets/jinja/issues/1427 #}
{% set member_html %}
{% for m in members if is_public(m) | trim %}
<dd id="{{ m.qualname }}" class="{{ m.kind }}">
{{- m.taken_from | link(text=m.name.replace("__init__",base[1])) -}}
</dd>
{% endfor %}
{% endset %}
{# we may not have any public members, in which case we don't want to print anything. #}
{% if member_html %}
<div><dt>{{ base | link }}</dt>
{{ member_html }}
</div>
{% endif %}
{% endfor %}
{% enddefaultmacro %}
{# fmt: on #}
{% defaultmacro view_source_state(doc) %}
{% if show_source and doc.source %}
<input id="{{ doc.qualname or "mod-" + doc.name }}-view-source" class="view-source-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
{% endif %}
{% enddefaultmacro %}
{% defaultmacro view_source_button(doc) %}
{% if show_source and doc.source %}
<label class="view-source-button" for="{{ doc.qualname or "mod-" + doc.name }}-view-source"><span>View Source</span></label>
{% endif %}
{% enddefaultmacro %}
{% defaultmacro view_source_code(doc) %}
{% if show_source and doc.source %}
{{ doc | highlight }}
{% endif %}
{% enddefaultmacro %}
{% defaultmacro module_name() %}
<h1 class="modulename">
{% set parts = module.modulename.split(".") %}
{% for part in parts %}
{%- set fullname = ".".join(parts[:loop.index]) -%}
{%- if fullname in all_modules and fullname != module.modulename -%}
<a href="./{{ "../" * loop.revindex0 }}{{ part }}.html">{{ part }}</a>
{%- else -%}
{{ part }}
{%- endif -%}
{%- if loop.nextitem -%}
<wbr>.
{%- endif -%}
{% endfor %}
</h1>
{% enddefaultmacro %}
|
