pdoc3

0.11.6 · active · verified Mon Apr 13

pdoc3 is a Python library and command-line tool that automatically generates API documentation from your Python project's docstrings and type annotations. It supports various docstring formats like Markdown, numpydoc, and Google-style, and can output documentation in HTML or PDF formats. As an actively maintained fork of the original `pdoc` project, it focuses on Python 3+ compatibility and ease of use, aiming to provide sensible documentation with minimal configuration.

Warnings

breaking pdoc3 is a fork of the original `pdoc` and is exclusively for Python 3.9+. Older Python 2 or earlier Python 3 projects will not be compatible. The `0.5.0` release marked a major refactoring for Python 3 compatibility.
Fix: Ensure your project runs on Python 3.9+ and use `pdoc3`. If targeting older Python versions, consider the legacy `pdoc` releases or other documentation tools.
gotcha The `pdoc` and `pdoc3` projects have diverged. Features like the `__pdoc__` module-level dictionary (used to override or exclude docstrings) are supported in `pdoc3` but were removed from the original `pdoc` in its 1.0.0 release. Consult the correct project's documentation.
Fix: Always refer to the official `pdoc3` documentation for current features. If migrating, check for feature parity or changes.
gotcha Users frequently encounter `ValueError: File or module not found` or `ImportError` if the Python modules or packages to be documented are not correctly discoverable in the Python path (`PYTHONPATH`) or current working directory.
Fix: Ensure the directory containing your module/package is in your `PYTHONPATH` environment variable or run `pdoc` from the parent directory of your module/package.
breaking Since version `0.6.0`, `__init__` methods are no longer documented separately. Their docstrings are merged into the class docstring, and constructor parameters are displayed on the class definition line, aligning with Sphinx/Python stdlib documentation conventions.
Fix: Adjust documentation expectations; class-level docstrings should now include `__init__` documentation. If you relied on separate `__init__` documentation, you may need to refactor docstrings.
gotcha The `--skip-errors` flag might not function as expected in `pdoc3` versions prior to `0.11.2`, leading to documentation generation failures even when errors should be skipped.
Fix: Upgrade to `pdoc3` version `0.11.2` or newer to ensure `--skip-errors` works reliably. Alternatively, ensure all modules are error-free.

Install

pip install pdoc3 Install pdoc3

Imports

pdoc
```
import pdoc
```
The PyPI package is 'pdoc3', but the primary module for programmatic use is named 'pdoc'.

Quickstart

This quickstart demonstrates how to generate HTML documentation for a simple Python module using pdoc3 programmatically. It creates a temporary Python file, generates docs into a 'docs/' directory, and then cleans up the temporary file. For command-line usage, simply run `pdoc your_module_or_package`.

import pdoc
import os

# Create a dummy module file for documentation
dummy_module_content = """
\"\"\"
A simple example module.
\"\"\"

class MyClass:
    \"\"\"
    A sample class.

    Attributes:
        name (str): The name of the instance.
    \"\"\"
    def __init__(self, name: str):
        self.name = name

    def greet(self) -> str:
        \"\"\"
        Greets the user.
        \"\"\"
        return f"Hello, {self.name}!"

def my_function(value: int) -> int:
    \"\"\"
    A sample function.

    Args:
        value (int): An integer input.

    Returns:
        int: The input value multiplied by 2.
    \"\"\"
    return value * 2
"""
with open("my_example_module.py", "w") as f:
    f.write(dummy_module_content)

# Generate documentation for the module
# Output to a 'docs' directory
pdoc.pdoc("my_example_module", output_directory="docs")

print("Documentation generated in 'docs/' directory.")
print("You can view it by opening docs/my_example_module.html")

# Clean up the dummy module file
os.remove("my_example_module.py")
# To clean up the generated documentation directory:
# import shutil
# shutil.rmtree("docs")

view raw JSON →