How to Document Python Code

Good documentation gets new contributors productive faster and cuts repeat support questions. Python's dynamic nature makes documentation even more critical - without type hints and docstrings, developers have to read implementation code to understand interfaces.

Python supports several docstring formats. Here are the most common:

1. Google Style (Recommended)

def calculate_total(price: float, tax_rate: float = 0.1) -> float:
    """Calculate total price including tax.

    Args:
        price: Base price before tax.
        tax_rate: Tax rate as decimal (default 0.1 for 10%).

    Returns:
        Total price with tax applied.

    Raises:
        ValueError: If price is negative.

    Example:
        >>> calculate_total(100, 0.08)
        108.0
    """
    if price < 0:
        raise ValueError("Price cannot be negative")
    return price * (1 + tax_rate)

2. NumPy Style

def calculate_total(price, tax_rate=0.1):
    """
    Calculate total price including tax.

    Parameters
    ----------
    price : float
        Base price before tax.
    tax_rate : float, optional
        Tax rate as decimal (default is 0.1).

    Returns
    -------
    float
        Total price with tax applied.
    """
    return price * (1 + tax_rate)

3. Sphinx/reStructuredText Style

def calculate_total(price, tax_rate=0.1):
    """Calculate total price including tax.

    :param price: Base price before tax.
    :type price: float
    :param tax_rate: Tax rate as decimal.
    :type tax_rate: float
    :returns: Total price with tax applied.
    :rtype: float
    """
    return price * (1 + tax_rate)

Python 3.5+ supports type hints which serve as inline documentation and enable IDE autocompletion:

from typing import List, Optional, Dict

class UserService:
    """Service for managing user operations."""

    def get_user(self, user_id: int) -> Optional[Dict[str, str]]:
        """Fetch user by ID."""
        ...

    def list_users(self, limit: int = 100) -> List[Dict[str, str]]:
        """List all users with optional limit."""
        ...

1. Document public APIs first - Focus on functions and classes others will use
2. Include examples - Show how to use the code, not just what it does
3. Keep it updated - Outdated docs are worse than no docs
4. Use type hints - They document types and enable IDE features
5. Document exceptions - List what errors can be raised

The hardest part of documentation is keeping it current. Tools like AutomaDocs can:

• Generate documentation from code automatically
• Update docs when code changes via GitHub webhooks
• Provide AI chat to answer questions about your codebase

• Python docstrings (official docs)
• PEP 257 - Docstring conventions
• Sphinx documentation