Documentation Generator

Generate clear, consistent documentation for Python code.

Documentation Workflow

Progress:
- [ ] Step 1: Analyze code structure
- [ ] Step 2: Generate docstrings
- [ ] Step 3: Validate documentation
- [ ] Step 4: Fix validation errors
- [ ] Step 5: Final review

Step 1: Analyze Code

Identify what needs documentation:

• Public functions and methods
• Classes and their attributes
• Module-level docstrings
• Complex logic blocks

Step 2: Generate Docstrings

Use Google-style docstrings:

def fetch_user(user_id: int, include_profile: bool = False) -> User:
    """Fetch a user from the database.
    
    Args:
        user_id: The unique identifier of the user.
        include_profile: Whether to load the full profile. Defaults to False.
    
    Returns:
        The User object with requested data.
    
    Raises:
        UserNotFoundError: If no user exists with the given ID.
        DatabaseError: If the database connection fails.
    
    Example:
        >>> user = fetch_user(123)
        >>> print(user.name)
        'John Doe'
    """

Step 3: Validate Documentation

Run validation after generating docs:

python scripts/validate_docs.py src/

Expected output:

• OK - All docstrings valid
• Error list - Issues to fix

Step 4: Fix Validation Errors

Common issues:

Loop back to Step 3 until validation passes.

Step 5: Final Review

• Verify examples are runnable
• Check for spelling/grammar
• Ensure consistency across module

Templates

See templates/ for:

• module.md - Module docstring template
• class.md - Class documentation template
• api.md - REST API documentation template