pdoc

pdoc Best Practices

pdoc is our definitive tool for generating API documentation from Python docstrings and type annotations. This guide outlines the mandatory practices to ensure our generated documentation is consistent, accurate, and immediately useful.

1. Docstrings: The Foundation (Google Style)

Always use Google Style docstrings for all public modules, classes, functions, and methods. This provides a clear, structured format that pdoc parses effectively.

Mandatory Docstring Sections:

• Summary Line: A concise, one-line summary of the object's purpose.
• Detailed Description: Elaborate on behavior, context, and important considerations.
• Args: List each parameter with its type and description.
• Returns: Describe the return value and its type.
• Raises: Document any exceptions that can be raised.
• Example: Provide a short, copy-pasteable usage example.

❌ BAD: Incomplete and inconsistent docstring

def calculate_discount(price, percentage):
    """Applies a discount to a price.
    Returns the discounted price.
    """
    return price * (1 - percentage / 100)

✅ GOOD: Comprehensive Google Style docstring

def calculate_discount(price: float, percentage: float) -> float:
    """Applies a percentage-based discount to a given price.

    This function calculates the final price after applying a specified
    discount percentage. The percentage should be a value between 0 and 100.

    Args:
        price (float): The original price of the item.
        percentage (float): The discount percentage to apply (0-100).

    Returns:
        float: The discounted price.

    Raises:
        ValueError: If the percentage is not within the 0-100 range.

    Example:
        >>> calculate_discount(100.0, 10.0)
        90.0
        >>> calculate_discount(50.0, 0.0)
        50.0
    """
    if not (0 <= percentage <= 100):
        raise ValueError("Discount percentage must be between 0 and 100.")
    return price * (1 - percentage / 100)