pdoc Documentation

When integrating pdoc with mkdocs, be aware of the following technical constraints:

Cross-page Linking

If you need to link between different pages in your documentation, you must set use_directory_urls: false in your mkdocs.yml configuration. Otherwise, pdoc's generated links may not resolve correctly.

Table of Contents (TOC)

pdoc does not automatically populate the mkdocs Table of Contents because mkdocs' Markdown parser ignores the raw HTML generated by pdoc. To prevent a broken or empty TOC from appearing, you may need to hide the mkdocs table of contents using custom CSS within your frame.html.jinja2 template.

You can override pdoc's default documentation templates by providing a directory containing your own template files. Use the --template-directory or the short -t command line argument followed by the path to your template directory.

When using a custom template directory, pdoc will look for templates within that directory to match its internal lookup logic.

pdoc -t ./examples/custom-template pdoc

pdoc allows you to customize the look and feel of generated documentation by providing your own template directory. pdoc follows a lookup priority: it checks for a template file in your custom directory before falling back to the default/ directory.

To extend a default template rather than replacing it entirely, use the Jinja2 {% extends %} tag. This allows you to override specific blocks (like title) while keeping the rest of the default structure.

{% extends "default/module.html.jinja2" %}
{% block title %}new page title{% endblock %}

You can use pdoc to document a Python module or a specific file.

To document a module:

pdoc your_python_module

To document a specific file:

pdoc ./my_project.py

To generate standalone HTML output to a specific directory (e.g., ./html):

pdoc -o ./html pdoc

The examples/ directory provides several patterns for using and customizing pdoc:

• custom-template: Demonstrates various template configuration options.
• dark-mode: Shows how to apply a dark theme to pdoc styles.
• library-usage: Demonstrates how to use pdoc as a Python library rather than a CLI tool.
• mkdocs: Provides a guide for integrating pdoc with the MkDocs static site generator.

To use pdoc within an mkdocs site, you can generate HTML documentation using a custom template and then treat the output as Markdown files. Since mkdocs' Markdown parser accepts interspersed HTML, this allows you to leverage pdoc's API extraction while using mkdocs for site structure and hosting.

Workflow

1. Create a custom frame.html.jinja2 template to strip away pdoc's standard HTML wrappers, leaving only the core documentation content.
2. Run pdoc to generate the documentation.
3. Rename the resulting output files from .html to .md.
4. Run mkdocs serve to view the site.

Note: In this specific example repository, you can automate this by running ./make.py to generate the API docs and then mkdocs serve to view the website.

pdoc uses Pygments for syntax highlighting. The styles are defined in syntax-highlighting.css. You can generate a custom version of this file using the pygmentize command.

To generate a new stylesheet, use the following command, replacing <theme> with your desired Pygments theme name:

pygmentize -f html -a .pdoc-code -S <theme> > default/syntax-highlighting.css

To implement a dark mode theme in pdoc, you must override the default CSS variables and the Pygments syntax highlighting theme. pdoc defines its color scheme using CSS variables, which allows you to customize the appearance by providing a custom theme.css and a custom syntax-highlighting.css file.

To preview a dark mode implementation locally, navigate to the example directory and run pdoc using the -t (template) flag pointing to the current directory.

cd examples/dark-mode && pdoc -t . pdoc

Install the pdoc package using pip to generate API documentation for your Python projects.

pip install pdoc