Python pdoc API Docs — Core Concepts

What pdoc Does

pdoc is a zero-configuration API documentation generator for Python. It imports your package, inspects every public module, class, function, and variable, and renders browsable HTML documentation. Unlike Sphinx, which requires .rst files and a configuration directory, pdoc works out of the box.

Install and run:

pip install pdoc
pdoc mypackage

This opens a live-preview server at localhost:8080. Edit a docstring, save, and the browser refreshes automatically.

How pdoc Discovers Documentation

pdoc reads three sources of information for each object:

Source	What It Provides
Docstrings	The main description (supports Markdown, Google, NumPy styles)
Type annotations	Parameter types, return types
Source code	Default values, class hierarchy

A well-documented function:

def retry(func: Callable, max_attempts: int = 3, delay: float = 1.0) -> Callable:
    """Wrap a function with automatic retry logic.

    Retries the wrapped function up to `max_attempts` times,
    waiting `delay` seconds between each attempt.

    Args:
        func: The function to wrap.
        max_attempts: Maximum number of retry attempts.
        delay: Seconds to wait between retries.

    Returns:
        A wrapped version of `func` with retry behavior.

    Raises:
        RuntimeError: If all retry attempts fail.
    """

pdoc renders this with formatted parameter descriptions, type badges, and linked cross-references — all without any configuration files.

Controlling Visibility

By default, pdoc documents all public names (those without a leading underscore). You can fine-tune this:

# Explicitly hide from pdoc
__pdoc__ = {
    "InternalHelper": False,
    "MyClass.private_method": False,
}

Or use the __all__ variable:

__all__ = ["PublicClass", "public_function"]

pdoc respects __all__ — only listed names appear in the documentation.

Static Site Generation

For deployment, generate static HTML:

pdoc mypackage -o docs/api/

This creates a directory of HTML files you can host on GitHub Pages, Netlify, or any static hosting service. The output is self-contained — no server needed.

Markdown in Docstrings

pdoc renders Markdown natively in docstrings. This means you can use:

• Headers for sections within long docstrings
• Code blocks with syntax highlighting
• Tables for parameter comparisons
• Links to external resources or other modules

def connect(host: str, port: int = 5432) -> Connection:
    """Establish a database connection.

    ## Connection Pooling

    This function draws from a shared pool. See
    [PoolConfig][mypackage.pool.PoolConfig] for pool settings.

    | Parameter | Default | Range |
    |-----------|---------|-------|
    | host      | —       | any   |
    | port      | 5432    | 1024+ |
    """

Cross-references like [PoolConfig][mypackage.pool.PoolConfig] become clickable links in the generated docs.

When to Choose pdoc Over Sphinx or MkDocs

• Small to medium libraries where API reference is the main documentation need
• Quick internal documentation for team projects that need docs now, not next sprint
• Prototyping — get docs running in under a minute to validate your API design
• Complementary tool — some projects use MkDocs for guides and pdoc for API reference

Common Misconception

“pdoc is too simple for real projects.” pdoc handles inheritance, nested classes, generic types, dataclasses, and Pydantic models. It renders type annotations accurately and supports custom CSS templates. For pure API reference, it often produces cleaner output than Sphinx because it has fewer moving parts.

One thing to remember: pdoc trades configurability for speed — if your main goal is “make my docstrings browsable,” it gets you there faster than any alternative.