Creating and maintaining documentation for your projects can often feel like a daunting task, but it doesn’t have to be. Imagine if, with a single console command, you could generate a web app that documents your project for you. Enter PDoc!

What is PDoc?

PDoc is a straightforward and lightweight tool designed to generate HTML documentation for Python projects. It analyses your codebase, extracts docstrings, and creates attractive, readable documentation pages. Unlike more complex tools like Sphinx, PDoc is focused on simplicity and ease of use, making it ideal for small to medium-sized projects.

Key keatures of PDoc

• Simplicity: PDoc is easy to set up and use, allowing you to generate documentation with just a few commands.
• Docstring Support: It supports both Google-style and NumPy-style docstrings, giving you flexibility in writing your documentation.
• Interactive HTML: The generated HTML documentation is interactive, featuring collapsible sections and search functionality.
• Minimal Configuration: PDoc requires minimal configuration, reducing the time needed to set up your documentation pipeline.
• Type Annotations: Supports type annotations, enhancing the clarity and usability of the generated documentation.

Doc generation with PDoc

PDoc works by importing your modules and using introspection on the various objects within them. It leverages the abstract syntax tree to parse documentation from attributes as well as from modules, classes, and functions.

Here’s an example:

"""PDoc supports module level docs"""

class Example:
    """Class Level documentation"""

    a: int
    """Attr level docs"""

    def __init__(self):
        """Method level docs"""

def func():
    """And Function level docs"""

PDoc supports inheritance. If you create a subclass of a documented class and do not define new docs, it will search the parent for appropriate docs.

To generate documentation for this code, simply run pdoc my_module in the console. This will start a web server and provide you with a link to the documentation. Alternatively, run pdoc pdoc to get documentation for pdoc itself.

If you prefer to generate the files without running the web server, use pdoc my_module -o docs, which will create the HTML and JS files needed to render your documentation.

Customizing PDoc

PDoc can be customized by enabling various flags when launching it via the console:

• d {markdown,google,numpy,restructuredtext}, --docformat {markdown,google,numpy,restructuredtext}

  Set the default docstring format. For non-Markdown formats, PDoc will convert matching syntax elements to Markdown and then process everything as Markdown. Default is restructuredtext.

• -include-undocumented, --no-include-undocumented

  Show classes/functions/variables that do not have a docstring. Default is True.

• e module=url, --edit-url module=url

  Provide a mapping between module names and URL prefixes to display an ‘Edit’ button. Can be passed multiple times. Example: pdoc=https://github.com/mitmproxy/pdoc/blob/main/pdoc/ Default is an empty list.

• -favicon URL

  Specify a custom favicon URL. Default is None.

• -footer-text TEXT

  Add custom text for the page footer, such as the project name and current version number. Default is None.

• -logo URL

  Add a project logo image. Default is None.

• -logo-link URL

  Specify an optional URL the logo should point to. Default is None.

• -math**,** -no-math

  Include MathJax from a CDN to enable math formula rendering. Default is False.

• -mermaid**,** -no-mermaid

  Include Mermaid.js from a CDN to enable Mermaid diagram rendering. Default is False.

• -search**,** -no-search

  Enable search functionality if multiple modules are documented. Default is True.

• -show-source**,** -no-show-source

  Display “View Source” buttons. Default is True.

Final thoughts

PDoc’s simplicity and minimal configuration make it an excellent choice for developers who need to create clear, comprehensive documentation without the hassle of complex setup processes. Whether you’re documenting a small library or a medium-sized application, PDoc can help you maintain high-quality, interactive documentation that enhances your project’s usability and accessibility.

Give PDoc a try on your next project and experience the ease of automatic documentation generation.