pdoc
What is pdoc?
pdoc auto-generates API documentation that follows your project's Python module hierarchy.
pdoc's main feature is a focus on simplicity: pdoc aims to do one thing and do it well.
- Easy setup, no configuration necessary.
- Documentation is plain Markdown.
- First-class support for type annotations.
- Builtin web server with live reloading.
- Customizable HTML templates.
- Understands numpydoc and Google-style docstrings.
Quickstart
As an example, we want to generate API documentation for demo.py
.
Our demo module already includes a bunch of docstrings:
"""
A small `pdoc` example.
"""
class Dog:
"""🐕"""
name: str
"""The name of our dog."""
friends: list["Dog"]
"""The friends of our dog."""
def __init__(self, name: str):
"""Make a Dog without any friends (yet)."""
self.name = name
self.friends = []
def bark(self, loud: bool = True):
"""*woof*"""
We can invoke pdoc to take our docstrings and render them into a standalone HTML document:
pdoc ./demo.py # or: pdoc my_module_name
This opens a browser with our module documentation. Here's a copy of what you should see:
If you look closely, you'll notice that docstrings are interpreted as Markdown.
For example, `pdoc` is rendered as pdoc
. Additionally, identifiers such as the type annotation
for Dog.friends
are automatically linked.
If we edit demo.py
now, the page will reload automatically.
Once we are happy with everything, we can export the documentation to an HTML file:
pdoc ./demo.py -o ./docs
This will create an HTML file at docs/demo.html
which contains our module documentation. 🎉
Customizing pdoc
We can optionally configure pdoc's output via command line flags. For example, we can add a project logo to the documentation:
pdoc ./demo.py --logo "https://placedog.net/300?random"
To get a list of all available rendering options, run:
pdoc --help
If you need more advanced customization options, see How can I edit pdoc's HTML template?.
Deploying to GitHub Pages
In this example we'll deploy pdoc's documentation to GitHub Pages. Of course, you can distribute the generated documentation however you want! pdoc's job is to "just" produce self-contained HTML files for you.
A very simple way to host your API documentation is to set up a continuous integration job which pushes your documentation to GitHub Pages. This keeps your docs updated automatically.
- Enable GitHub Actions and GitHub Pages for your project.
- In the GitHub Pages settings, select GitHub Actions as your build and deployment source.
- Copy pdoc's GitHub Actions workflow into your own repository and adjust it to how you build your docs:
.github/workflows/docs.yml
That's it – no need to fiddle with any secrets or set up any gh-pages
branches. 🥳
How can I ... ?
...add documentation?
In Python, objects like modules, functions and classes have
a special attribute named __doc__
which contains that object's
docstring. The docstring comes from a special placement of a string
in your source code. For example, the following code shows how to
define a function with a docstring and access the contents of that
docstring:
>>> def test():
... """This is a docstring."""
... pass
...
>>> test.__doc__
'This is a docstring.'
Something similar can be done for classes and modules too. For classes,
the docstring should come on the line immediately following class
...
. For modules, the docstring should start on the first line of
the file. These docstrings are what you see for each module, class,
function and method listed in the documentation produced by pdoc.
...document variables?
Python itself does not attach docstrings to variables. For example:
variable = "SomeValue"
"""Docstring for variable."""
The resulting variable
will have no __doc__
attribute.
To compensate, pdoc will read the abstract syntax tree (an abstract representation of the source code)
and include all assignment statements immediately followed by a docstring. This approach is not formally standardized,
but followed by many tools, including Sphinx's autodoc extension in case you ever decide to migrate off pdoc.
Docstring detection is limited to the current module, docstrings for variables imported from other modules are not
picked up.
Something similar is done for instance variables, which are either type-annotated in the class
or defined in a class's __init__
. Here is an example showing both conventions detected by pdoc:
class GoldenRetriever(Dog):
name: str
"""Full Name"""
def __init__(self):
self.weight: int = 10
"""Weight in kilograms"""
If you would like to distinguish an instance variable from a class variable,
you can use typing.ClassVar
:
class GoldenRetriever(Dog):
breed_code: ClassVar[str] = "GOLD"
"""International breed code (same for all instances)"""
name: str
"""Full Name (different for each instance)"""
...control what is documented?
The public interface of a module is determined through one of two ways.
- If
__all__
is defined in the module, then all identifiers in that list will be considered public. No other identifiers will be considered public. - If
__all__
is not defined, then pdoc will consider all items public that do not start with an underscore and that are defined in the current module (i.e. they are not imported).
If you want to override the default behavior for a particular item, you can do so by including an annotation in its docstring:
@private
hides an item unconditionally.@public
shows an item unconditionally.
In general, we recommend keeping the following conventions:
- If you want to document a private member, consider making it public.
- If you want to hide a public member, consider making it private.
- If you want to document a special
__dunder__
method, the recommended way to do so is to not document the dunder method specifically, but to add some usage examples in the class documentation.
Hiding an item only removes it from documentation. It is still displayed in the source code when clicking the "View Source" button.
As a last resort, you can override pdoc's behavior with a custom module template (see
How can I edit pdoc's HTML template?).
You can find an example at
examples/custom-template/module.html.jinja2
.
Hiding an item only removes it from documentation. It is still displayed in the source code when clicking the "View Source" button.
...exclude submodules from being documented?
If you would like to exclude specific submodules from the documentation, the recommended way is to specify __all__
as
shown in the previous section. Alternatively, you can pass negative regular expression !patterns
as part of the
module specification. Each pattern removes all previously specified (sub)module names that match. For example, the following
invocation documents foo
and all submodules of foo
, but not foo.bar
:
pdoc foo !foo.bar
Likewise, pdoc pdoc !pdoc.
would document the pdoc module itself, but none of its submodules. Patterns are always
matched on the final module name, even if modules are passed as file paths.
...link to other identifiers?
In your documentation, you can link to other identifiers by enclosing them in backticks:
`pdoc`
will link to pdoc
.
When linking to identifiers in other modules, the identifier name must be fully qualified.
For example, `pdoc.doc.Doc`
will be automatically linked to pdoc.doc.Doc
,
while `Doc`
only works within the pdoc.doc
module.
pdoc will link all identifiers that are rendered in the current run.
This means that you need to run pdoc module_a module_b
to have interlinking between module_a and module_b.
If you run pdoc module_a
followed by pdoc module_b
, there will be no cross-linking between the two modules.
...change the item order?
By default, documentation items are sorted in order of (first) appearance in the source code. This means that if you want to move a particular function to the beginning of your documentation, you need to move it there in your source code. This is not only useful to the readers of your documentation, but also useful to the consumers of your source code.
...use numpydoc or Google docstrings?
While pdoc prefers docstrings that are plain Markdown, it also understands numpydoc and Google-style docstrings. If your documentation follows one of these styles, you can:
- Run
pdoc --docformat ...
to enable a particular docstring flavor globally, or - Add
__docformat__ = "..."
at the top-level of the module you are documenting.
The following values are supported:
markdown
: Process Markdown syntax only.restructuredtext
: Process reStructuredText elements, then Markdown (default setting).google
: Process reStructuredText elements, then Google-style syntax, then Markdown.numpy
: Process reStructuredText elements, then Numpydoc syntax, then Markdown.
pdoc only interprets a subset of the reStructuredText specification.
Adding additional syntax elements is usually easy. If you feel that pdoc doesn't parse a docstring element properly,
please amend pdoc.docstrings
and send us a pull request!
...render math formulas?
Run pdoc --math
, and pdoc will render formulas in your docstrings. See
math_demo
for details.
...render Mermaid diagrams?
Run pdoc --mermaid
, and pdoc will render mermaid diagrams in your docstrings. See
mermaid_demo
for details.
...add my project's logo?
See Customizing pdoc.
...include Markdown files?
You can include external Markdown files in your documentation by using reStructuredText's
.. include::
directive. For example, a common pattern is to include your project's README in your top-level __init__.py
like this:
"""
.. include:: ../README.md
"""
You can also include only parts of a file with the
start-line
, end-line
, start-after
, and end-after
options:
"""
.. include:: ../README.md
:start-line: 1
:end-before: Changelog
"""
...add a title page?
The landing page for your documentation is your project's top-level <modulename>/__init__.py
file.
Adding a module-level docstring here is a great way to introduce users to your project.
For example, the documentation you are reading right now is sourced from
pdoc/__init__.py
.
You can also include your title page from a Markdown file.
If you have multiple top-level modules, a custom title page requires modifying the index.html.jinja2
template.
You can find an example in #410.
...edit pdoc's HTML template?
For more advanced customization, we can edit pdoc's default HTML template, which uses the Jinja2 templating language.
Let's assume you want to replace the logo with a custom button. We first find the right location in the template by searching
for "logo", which shows us that the logo is defined in a Jinja2 block named nav_title
.
We now extend the default template by creating a file titled module.html.jinja2
in the current directory
with the following contents:
{% extends "default/module.html.jinja2" %}
{% block nav_title %}
<button>Donate dog food</button>
{% endblock %}
We then specify our custom template directory when invoking pdoc...
pdoc -t . ./demo.py
...and the updated documentation – with button – renders! 🎉
See examples/
for more examples.
...pass arguments to the Jinja2 template?
If you need to pass additional data to pdoc's Jinja2 templates,
you can use system environment variables.
For example,
examples/custom-template/module.html.jinja2
shows how to include a version number in the rendered HTML.
...integrate pdoc into other systems?
pdoc's HTML and CSS are written in a way that the default template can be easily adjusted to produce standalone HTML fragments that can be embedded in other systems. This makes it possible to integrate pdoc with almost every CMS or static site generator. The only limitation is that you need to retain pdoc's directory structure if you would like to link between modules.
To do so, create a custom frame.html.jinja2
template which only emits CSS and the main
page contents instead of a full standalone HTML document:
{% block content %}{% endblock %}
{% filter minify_css %}
{% block style %}
{# The same CSS files as in pdoc's default template, except for layout.css.
You may leave out Bootstrap Reboot, which corrects inconsistences across browsers
but may conflict with you website's stylesheet. #}
<style>{% include "resources/bootstrap-reboot.min.css" %}</style>
<style>{% include "syntax-highlighting.css" %}</style>
<style>{% include "theme.css" %}</style>
<style>{% include "content.css" %}</style>
{% endblock %}
{% endfilter %}
This should be enough to produce HTML files that can be embedded into other pages.
All CSS selectors are prefixed with .pdoc
so that pdoc's page style does not interfere with the rest of your website.
You can find a full example for mkdocs in examples/mkdocs
.
Docstring Inheritance
pdoc extends the standard use of docstrings in two important ways: by introducing variable docstrings (see How can I document variables?), and by allowing functions and classes to inherit docstrings and type annotations.
This is useful to not unnecessarily repeat information. Consider this example:
class Dog:
def bark(self, loud: bool) -> None:
"""
Make the dog bark. If `loud` is True,
use full volume. Not supported by all breeds.
"""
class GoldenRetriever(Dog):
def bark(self, loud: bool) -> None:
print("Woof Woof")
In Python, the docstring for GoldenRetriever.bark
is empty, even though one was
defined in Dog.bark
. If pdoc generates documentation for the above
code, then it will automatically attach the docstring for Dog.bark
to
GoldenRetriever.bark
if it does not have a docstring.
Limitations
- Scope: pdoc main use case is API documentation. If you have substantially more complex documentation needs, we recommend using Sphinx!
- Dynamic analysis: pdoc makes heavy use of dynamic analysis to extract docstrings. This means your Python modules will be executed/imported when pdoc runs.
- HTML Output: pdoc only supports HTML as an output format. If you want to use pdoc with a static site generator that only accepts Markdown, that may work nonetheless – take a look at integrating pdoc into other systems.
Markdown Support
Markdown is a lightweight and popular markup language for text formatting. There are many versions or "flavors" of Markdown. pdoc uses the markdown2 library, which closely matches the behavior of the original Markdown 1.0.1 spec. In addition, the following extra syntax elements are enabled:
- code-friendly: Disable
_
and__
forem
andstrong
. - cuddled-lists: Allow lists to be cuddled to the preceding paragraph.
- fenced-code-blocks: Allows a code block to not have to be
indented by fencing it with
```
on a line before and after. Based on GitHub-Flavored Markdown with support for syntax highlighting. - footnotes: Support footnotes as in use on daringfireball.net and implemented in other Markdown processors.
- header-ids: Adds "id" attributes to headers. The id value is a slug of the header text.
- markdown-in-html: Allow the use of
markdown="1"
in a block HTML tag to have markdown processing be done on its contents. Similar to PHP-Markdown Extra but with some limitations. - mermaid: Allows rendering Mermaid diagrams from included Markdown files using
```mermaid
fence blocks. - pyshell: Treats unindented Python interactive shell
sessions as
<code>
blocks. - strike: Parse
~~strikethrough~~
formatting. - tables: Tables using the same format as GitHub-Flavored Markdown and PHP-Markdown Extra.
- task_list: Allows GitHub-style task lists (i.e. check boxes)
- toc: The returned HTML string gets a new "toc_html" attribute which is a Table of Contents for the document.
It is possible (but not recommended) to use another Markdown library with pdoc. See #401 for details.
Using pdoc as a library
pdoc provides the high-level pdoc.pdoc()
interface explained below. This makes it possible to do custom adjustments
to your Python code before pdoc is used.
It is also possible to create pdoc.doc.Module
objects directly and modify them before rendering.
You can find an example in examples/library-usage
.
1r''' 2# What is pdoc? 3 4pdoc auto-generates API documentation that follows your project's Python module hierarchy. 5 6pdoc's main feature is a focus on simplicity: pdoc aims to do one thing and do it well. 7 8 - Easy setup, no configuration necessary. 9 - Documentation is plain [Markdown](#markdown-support). 10 - First-class support for type annotations. 11 - Builtin web server with live reloading. 12 - Customizable HTML templates. 13 - Understands numpydoc and Google-style docstrings. 14 15# Quickstart 16 17As an example, we want to generate API documentation for `demo.py`. 18Our demo module already includes a bunch of docstrings: 19 20```python 21""" 22A small `pdoc` example. 23""" 24 25class Dog: 26 """🐕""" 27 name: str 28 """The name of our dog.""" 29 friends: list["Dog"] 30 """The friends of our dog.""" 31 32 def __init__(self, name: str): 33 """Make a Dog without any friends (yet).""" 34 self.name = name 35 self.friends = [] 36 37 def bark(self, loud: bool = True): 38 """*woof*""" 39``` 40 41We can invoke pdoc to take our docstrings and render them into a standalone HTML document: 42 43```shell 44pdoc ./demo.py # or: pdoc my_module_name 45``` 46 47This opens a browser with our module documentation. Here's a copy of what you should see: 48 49<iframe style=" 50 width: 100%; 51 height: 250px; 52 border: solid gray 1px; 53 display: block; 54 margin: 1rem auto; 55 border-radius: 5px;" 56 title="rendered demo.py documentation" 57 src="https://pdoc.dev/docs/demo-standalone.html"></iframe> 58 59If you look closely, you'll notice that docstrings are interpreted as Markdown. 60For example, \`pdoc\` is rendered as `pdoc`. Additionally, identifiers such as the type annotation 61for `Dog.friends` are automatically linked. 62 63If we edit `demo.py` now, the page will reload automatically. 64Once we are happy with everything, we can export the documentation to an HTML file: 65 66```shell 67pdoc ./demo.py -o ./docs 68``` 69 70This will create an HTML file at `docs/demo.html` which contains our module documentation. 🎉 71 72## Customizing pdoc 73 74We can optionally configure pdoc's output via command line flags. 75For example, we can add a project logo to the documentation: 76 77```shell 78pdoc ./demo.py --logo "https://placedog.net/300?random" 79``` 80 81To get a list of all available rendering options, run: 82 83```shell 84pdoc --help 85``` 86 87If you need more advanced customization options, see [*How can I edit pdoc's HTML template?*](#edit-pdocs-html-template). 88 89 90## Deploying to GitHub Pages 91 92*In this example we'll deploy pdoc's documentation to GitHub Pages. Of course, you can distribute 93the generated documentation however you want! pdoc's job is to "just" produce self-contained HTML files for you.* 94 95A very simple way to host your API documentation is to set up a continuous integration job which 96pushes your documentation to GitHub Pages. This keeps your docs updated automatically. 97 98 1. Enable GitHub Actions and GitHub Pages for your project. 99 2. In the GitHub Pages settings, select GitHub Actions as your build and deployment source. 100 3. Copy pdoc's GitHub Actions workflow into your own repository and adjust it to how you build your docs: 101 [`.github/workflows/docs.yml`](https://github.com/mitmproxy/pdoc/blob/main/.github/workflows/docs.yml) 102 103That's it – no need to fiddle with any secrets or set up any `gh-pages` branches. 🥳 104 105# How can I ... ? 106 107## ...add documentation? 108 109In Python, objects like modules, functions and classes have 110a special attribute named `__doc__` which contains that object's 111*docstring*. The docstring comes from a special placement of a string 112in your source code. For example, the following code shows how to 113define a function with a docstring and access the contents of that 114docstring: 115 116```python 117>>> def test(): 118... """This is a docstring.""" 119... pass 120... 121>>> test.__doc__ 122'This is a docstring.' 123``` 124 125Something similar can be done for classes and modules too. For classes, 126the docstring should come on the line immediately following `class 127...`. For modules, the docstring should start on the first line of 128the file. These docstrings are what you see for each module, class, 129function and method listed in the documentation produced by pdoc. 130 131 132## ...document variables? 133 134Python itself [does not attach docstrings to 135variables](https://www.python.org/dev/peps/pep-0224/). For example: 136 137```python 138variable = "SomeValue" 139"""Docstring for variable.""" 140``` 141 142The resulting `variable` will have no `__doc__` attribute. 143To compensate, pdoc will read the abstract syntax tree (an abstract representation of the source code) 144and include all assignment statements immediately followed by a docstring. This approach is not formally standardized, 145but followed by many tools, including Sphinx's autodoc extension in case you ever decide to migrate off pdoc. 146Docstring detection is limited to the current module, docstrings for variables imported from other modules are not 147picked up. 148 149Something similar is done for instance variables, which are either type-annotated in the class 150or defined in a class's `__init__`. Here is an example showing both conventions detected by pdoc: 151 152```python 153class GoldenRetriever(Dog): 154 name: str 155 """Full Name""" 156 157 def __init__(self): 158 self.weight: int = 10 159 """Weight in kilograms""" 160``` 161 162 163If you would like to distinguish an instance variable from a class variable, 164you can use [`typing.ClassVar`](https://docs.python.org/3/library/typing.html#typing.ClassVar): 165 166```python 167class GoldenRetriever(Dog): 168 breed_code: ClassVar[str] = "GOLD" 169 """International breed code (same for all instances)""" 170 name: str 171 """Full Name (different for each instance)""" 172``` 173 174 175## ...control what is documented? 176 177The public interface of a module is determined through one of two 178ways. 179- If `__all__` is defined in the module, then all identifiers in that list will be considered public. 180 No other identifiers will be considered public. 181- If `__all__` is not defined, then pdoc will consider all items public that do not start with an 182 underscore and that are defined in the current module (i.e. they are not imported). 183 184If you want to override the default behavior for a particular item, 185you can do so by including an annotation in its docstring: 186 187- `@private` hides an item unconditionally. 188- <code>@public</code> shows an item unconditionally. 189 190In general, we recommend keeping the following conventions: 191 192- If you want to document a private member, consider making it public. 193- If you want to hide a public member, consider making it private. 194- If you want to document a special `__dunder__` method, the recommended way to do so is 195 to not document the dunder method specifically, but to add some usage examples in the class documentation. 196 197> [!NOTE] 198> Hiding an item only removes it from documentation. 199> It is still displayed in the source code when clicking the "View Source" button. 200 201As a last resort, you can override pdoc's behavior with a custom module template (see 202[*How can I edit pdoc's HTML template?*](#edit-pdocs-html-template)). 203You can find an example at 204[`examples/custom-template/module.html.jinja2`](https://github.com/mitmproxy/pdoc/blob/main/examples/custom-template/module.html.jinja2). 205 206Hiding an item only removes it from documentation. It is still displayed in the source code when clicking the "View Source" button. 207 208## ...exclude submodules from being documented? 209 210If you would like to exclude specific submodules from the documentation, the recommended way is to specify `__all__` as 211shown in the previous section. Alternatively, you can pass negative regular expression `!patterns` as part of the 212module specification. Each pattern removes all previously specified (sub)module names that match. For example, the following 213invocation documents `foo` and all submodules of `foo`, but not `foo.bar`: 214 215``` 216pdoc foo !foo.bar 217``` 218 219Likewise, `pdoc pdoc !pdoc.` would document the pdoc module itself, but none of its submodules. Patterns are always 220matched on the final module name, even if modules are passed as file paths. 221 222 223## ...link to other identifiers? 224 225In your documentation, you can link to other identifiers by enclosing them in backticks: 226<code>\`pdoc\`</code> will link to `pdoc`. 227When linking to identifiers in other modules, the identifier name must be fully qualified. 228For example, <code>\`pdoc.doc.Doc\`</code> will be automatically linked to `pdoc.doc.Doc`, 229while <code>\`Doc\`</code> only works within the `pdoc.doc` module. 230 231pdoc will link all identifiers that are rendered in the current run. 232This means that you need to run `pdoc module_a module_b` to have interlinking between module_a and module_b. 233If you run `pdoc module_a` followed by `pdoc module_b`, there will be no cross-linking between the two modules. 234 235 236## ...change the item order? 237 238By default, documentation items are sorted in order of (first) appearance in the source code. 239This means that if you want to move a particular function to the beginning of your documentation, 240you need to move it there in your source code. This is not only useful to the readers of your documentation, 241but also useful to the consumers of your source code. 242 243 244## ...use numpydoc or Google docstrings? 245 246While pdoc prefers docstrings that are plain Markdown, it also understands numpydoc and Google-style docstrings. 247If your documentation follows one of these styles, you can: 248 2491. Run `pdoc --docformat ...` to enable a particular docstring flavor globally, or 2502. Add `__docformat__ = "..."` at the top-level of the module you are documenting. 251 252The following values are supported: 253 254- `markdown`: Process Markdown syntax only. 255- `restructuredtext`: Process reStructuredText elements, then Markdown (default setting). 256- `google`: Process reStructuredText elements, then Google-style syntax, then Markdown. 257- `numpy`: Process reStructuredText elements, then Numpydoc syntax, then Markdown. 258 259pdoc only interprets a subset of the reStructuredText specification. 260Adding additional syntax elements is usually easy. If you feel that pdoc doesn't parse a docstring element properly, 261please amend `pdoc.docstrings` and send us a pull request! 262 263 264## ...render math formulas? 265 266Run `pdoc --math`, and pdoc will render formulas in your docstrings. See 267[`math_demo`](https://pdoc.dev/docs/math/math_demo.html) for details. 268 269 270## ...render Mermaid diagrams? 271 272Run `pdoc --mermaid`, and pdoc will render mermaid diagrams in your docstrings. See 273[`mermaid_demo`](https://pdoc.dev/docs/mermaid/mermaid_demo.html) for details. 274 275 276## ...add my project's logo? 277 278See [*Customizing pdoc*](#customizing-pdoc). 279 280 281## ...include Markdown files? 282 283You can include external Markdown files in your documentation by using reStructuredText's 284`.. include::` directive. For example, a common pattern is to include your project's README in your top-level `__init__.py` like this: 285 286```python 287""" 288.. include:: ../README.md 289""" 290``` 291 292You can also include only parts of a file with the 293[`start-line`, `end-line`, `start-after`, and `end-after` options](https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment): 294 295```python 296""" 297.. include:: ../README.md 298 :start-line: 1 299 :end-before: Changelog 300""" 301``` 302 303 304## ...add a title page? 305 306The landing page for your documentation is your project's top-level `<modulename>/__init__.py` file. 307Adding a module-level docstring here is a great way to introduce users to your project. 308For example, the documentation you are reading right now is sourced from 309[`pdoc/__init__.py`](https://github.com/mitmproxy/pdoc/blob/main/pdoc/__init__.py). 310You can also include your title page from a [Markdown file](#include-markdown-files). 311 312If you have multiple top-level modules, a custom title page requires modifying the `index.html.jinja2` template. 313You can find an example in [#410](https://github.com/mitmproxy/pdoc/issues/410). 314 315## ...edit pdoc's HTML template? 316 317For more advanced customization, we can edit pdoc's 318[default HTML template](https://github.com/mitmproxy/pdoc/blob/main/pdoc/templates/default/module.html.jinja2), 319which uses the 320[Jinja2](https://jinja.palletsprojects.com/) templating language. 321 322Let's assume you want to replace the logo with a custom button. We first find the right location in the template by searching 323for "logo", which shows us that the logo is defined in a Jinja2 block named `nav_title`. 324We now extend the default template by creating a file titled `module.html.jinja2` in the current directory 325 with the following contents: 326 327```html+jinja 328{% extends "default/module.html.jinja2" %} 329{% block nav_title %} 330<button>Donate dog food</button> 331{% endblock %} 332``` 333 334We then specify our custom template directory when invoking pdoc... 335 336```shell 337pdoc -t . ./demo.py 338``` 339 340...and the updated documentation – with button – renders! 🎉 341 342See [`examples/`](https://github.com/mitmproxy/pdoc/tree/main/examples/) 343for more examples. 344 345 346## ...pass arguments to the Jinja2 template? 347 348If you need to pass additional data to pdoc's Jinja2 templates, 349you can use system environment variables. 350For example, 351[`examples/custom-template/module.html.jinja2`](https://github.com/mitmproxy/pdoc/blob/main/examples/custom-template/module.html.jinja2) 352shows how to include a version number in the rendered HTML. 353 354 355## ...integrate pdoc into other systems? 356 357pdoc's HTML and CSS are written in a way that the default template can be easily adjusted 358to produce standalone HTML fragments that can be embedded in other systems. 359This makes it possible to integrate pdoc with almost every CMS or static site generator. 360The only limitation is that you need to retain pdoc's directory structure 361if you would like to link between modules. 362 363To do so, [create a custom `frame.html.jinja2` template](#edit-pdocs-html-template) which only emits CSS and the main 364page contents instead of a full standalone HTML document: 365```html+jinja 366{% block content %}{% endblock %} 367 368{% filter minify_css %} 369 {% block style %} 370 {# The same CSS files as in pdoc's default template, except for layout.css. 371 You may leave out Bootstrap Reboot, which corrects inconsistences across browsers 372 but may conflict with you website's stylesheet. #} 373 <style>{% include "resources/bootstrap-reboot.min.css" %}</style> 374 <style>{% include "syntax-highlighting.css" %}</style> 375 <style>{% include "theme.css" %}</style> 376 <style>{% include "content.css" %}</style> 377 {% endblock %} 378{% endfilter %} 379``` 380 381This should be enough to produce HTML files that can be embedded into other pages. 382All CSS selectors are prefixed with `.pdoc` so that pdoc's page style does not interfere with the rest of your website. 383 384You can find a full example for mkdocs in [`examples/mkdocs`](https://github.com/mitmproxy/pdoc/tree/main/examples/mkdocs/). 385 386 387# Docstring Inheritance 388 389pdoc extends the standard use of docstrings in two important ways: 390by introducing variable docstrings (see [*How can I document variables?*](#document-variables)), 391and by allowing functions and classes to inherit docstrings and type annotations. 392 393This is useful to not unnecessarily repeat information. Consider this example: 394 395```python 396class Dog: 397 def bark(self, loud: bool) -> None: 398 """ 399 Make the dog bark. If `loud` is True, 400 use full volume. Not supported by all breeds. 401 """ 402 403class GoldenRetriever(Dog): 404 def bark(self, loud: bool) -> None: 405 print("Woof Woof") 406``` 407 408In Python, the docstring for `GoldenRetriever.bark` is empty, even though one was 409defined in `Dog.bark`. If pdoc generates documentation for the above 410code, then it will automatically attach the docstring for `Dog.bark` to 411`GoldenRetriever.bark` if it does not have a docstring. 412 413 414# Limitations 415 416 - **Scope:** pdoc main use case is API documentation. 417 If you have substantially more complex documentation needs, we recommend using [Sphinx](https://www.sphinx-doc.org/)! 418 - **Dynamic analysis:** pdoc makes heavy use of dynamic analysis to extract docstrings. 419 This means your Python modules will be executed/imported when pdoc runs. 420 - **HTML Output:** pdoc only supports HTML as an output format. If you want to use pdoc with a static site 421 generator that only accepts Markdown, that may work nonetheless – take a look at 422 [integrating pdoc into other systems](https://pdoc.dev/docs/pdoc.html#integrate-pdoc-into-other-systems). 423 424 425# Markdown Support 426 427[Markdown](https://guides.github.com/features/mastering-markdown/) is a lightweight and popular markup language for text 428formatting. There are many versions or *"flavors"* of Markdown. 429pdoc uses the [markdown2](https://github.com/trentm/python-markdown2) library, which closely matches 430the behavior of the original [Markdown 1.0.1 spec][]. 431In addition, the following extra syntax elements are enabled: 432 433 - **[code-friendly][]:** Disable `_` and `__` for `em` and `strong`. 434 - **[cuddled-lists][]:** Allow lists to be cuddled to the preceding 435 paragraph. 436 - **[fenced-code-blocks][]:** Allows a code block to not have to be 437 indented by fencing it with <code>```</code> on a line before and after. 438 Based on [GitHub-Flavored Markdown][] with support for syntax highlighting. 439 - **[footnotes][]:** Support footnotes as in use on daringfireball.net 440 and implemented in other Markdown processors. 441 - **[header-ids][]:** Adds "id" attributes to headers. The id value 442 is a slug of the header text. 443 - **[markdown-in-html][]:** Allow the use of `markdown="1"` in a 444 block HTML tag to have markdown processing be done on its contents. 445 Similar to [PHP-Markdown Extra][] but with some limitations. 446 - **[mermaid][]:** Allows rendering Mermaid diagrams from included Markdown files using <code>```mermaid</code> fence blocks. 447 - **[pyshell][]:** Treats unindented Python interactive shell 448 sessions as `<code>` blocks. 449 - **strike:** Parse `~~strikethrough~~` formatting. 450 - **[tables][]:** Tables using the same format as [GitHub-Flavored Markdown][] and 451 [PHP-Markdown Extra][]. 452 - **task_list:** Allows GitHub-style task lists (i.e. check boxes) 453 - **toc:** The returned HTML string gets a new "toc_html" 454 attribute which is a Table of Contents for the document. 455 456[Markdown 1.0.1 spec]: https://daringfireball.net/projects/markdown/ 457[code-friendly]: https://github.com/trentm/python-markdown2/wiki/code-friendly 458[cuddled-lists]: https://github.com/trentm/python-markdown2/wiki/cuddled-lists 459[fenced-code-blocks]: https://github.com/trentm/python-markdown2/wiki/fenced-code-blocks 460[footnotes]: https://github.com/trentm/python-markdown2/wiki/footnotes 461[header-ids]: https://github.com/trentm/python-markdown2/wiki/header-ids 462[markdown-in-html]: https://github.com/trentm/python-markdown2/wiki/markdown-in-html 463[mermaid]: https://github.com/trentm/python-markdown2/wiki/mermaid 464[pyshell]: https://github.com/trentm/python-markdown2/wiki/pyshell 465[tables]: https://github.com/trentm/python-markdown2/wiki/tables 466[GitHub-Flavored Markdown]: https://github.github.com/gfm/ 467[PHP-Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/#table 468 469It is possible (but not recommended) to use another Markdown library with pdoc. 470See [#401](https://github.com/mitmproxy/pdoc/issues/401#issuecomment-1148661829) for details. 471 472# Using pdoc as a library 473 474pdoc provides the high-level `pdoc.pdoc()` interface explained below. This makes it possible to do custom adjustments 475to your Python code before pdoc is used. 476 477It is also possible to create `pdoc.doc.Module` objects directly and modify them before rendering. 478You can find an example in [`examples/library-usage`](https://github.com/mitmproxy/pdoc/tree/main/examples/library-usage). 479''' 480 481from __future__ import annotations 482 483__docformat__ = "markdown" # explicitly disable rST processing in the examples above. 484__version__ = "15.0.0" # this is read from setup.py 485 486from pathlib import Path 487from typing import overload 488 489from pdoc import doc 490from pdoc import extract 491from pdoc import render 492 493 494@overload 495def pdoc( 496 *modules: Path | str, 497 output_directory: None = None, 498) -> str: 499 pass 500 501 502@overload 503def pdoc( 504 *modules: Path | str, 505 output_directory: Path, 506) -> None: 507 pass 508 509 510def pdoc( 511 *modules: Path | str, 512 output_directory: Path | None = None, 513) -> str | None: 514 """ 515 Render the documentation for a list of modules. 516 517 - If `output_directory` is `None`, returns the rendered documentation 518 for the first module in the list. 519 - If `output_directory` is set, recursively writes the rendered output 520 for all specified modules and their submodules to the target destination. 521 522 Rendering options can be configured by calling `pdoc.render.configure` in advance. 523 """ 524 all_modules: dict[str, doc.Module] = {} 525 for module_name in extract.walk_specs(modules): 526 all_modules[module_name] = doc.Module.from_name(module_name) 527 528 for module in all_modules.values(): 529 out = render.html_module(module, all_modules) 530 if not output_directory: 531 return out 532 else: 533 outfile = output_directory / f"{module.fullname.replace('.', '/')}.html" 534 outfile.parent.mkdir(parents=True, exist_ok=True) 535 outfile.write_bytes(out.encode()) 536 537 assert output_directory 538 539 index = render.html_index(all_modules) 540 if index: 541 (output_directory / "index.html").write_bytes(index.encode()) 542 543 search = render.search_index(all_modules) 544 if search: 545 (output_directory / "search.js").write_bytes(search.encode()) 546 547 return None
511def pdoc( 512 *modules: Path | str, 513 output_directory: Path | None = None, 514) -> str | None: 515 """ 516 Render the documentation for a list of modules. 517 518 - If `output_directory` is `None`, returns the rendered documentation 519 for the first module in the list. 520 - If `output_directory` is set, recursively writes the rendered output 521 for all specified modules and their submodules to the target destination. 522 523 Rendering options can be configured by calling `pdoc.render.configure` in advance. 524 """ 525 all_modules: dict[str, doc.Module] = {} 526 for module_name in extract.walk_specs(modules): 527 all_modules[module_name] = doc.Module.from_name(module_name) 528 529 for module in all_modules.values(): 530 out = render.html_module(module, all_modules) 531 if not output_directory: 532 return out 533 else: 534 outfile = output_directory / f"{module.fullname.replace('.', '/')}.html" 535 outfile.parent.mkdir(parents=True, exist_ok=True) 536 outfile.write_bytes(out.encode()) 537 538 assert output_directory 539 540 index = render.html_index(all_modules) 541 if index: 542 (output_directory / "index.html").write_bytes(index.encode()) 543 544 search = render.search_index(all_modules) 545 if search: 546 (output_directory / "search.js").write_bytes(search.encode()) 547 548 return None
Render the documentation for a list of modules.
- If
output_directory
isNone
, returns the rendered documentation for the first module in the list. - If
output_directory
is set, recursively writes the rendered output for all specified modules and their submodules to the target destination.
Rendering options can be configured by calling pdoc.render.configure
in advance.