![A Python reading Documentation](/images/blog/generate-python-docs-instantly-with-pdoc-leading.png)
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.