Python Documentation Generator

Generate comprehensive markdown documentation from Python source code.

When to Use This Skill

• User asks to "document this code" or "generate docs"

• Creating API documentation from Python modules

• Generating README files with usage examples

• Extracting docstrings and type signatures into readable format

• User mentions "documentation", "docstrings", or "API reference"

Input

Accept either:

• Single Python file path

• Directory path (recursively process .py files)

• List of specific files

Output Format

Generate standard markdown with:

Module Name

Brief description from module docstring.

Classes

ClassName

Description from class docstring.

Methods:

• method_name(param: type) -> return_type: Brief description

Functions

function_name(param: type) -> return_type

Description from docstring.

Parameters:

• param (type): Description

Returns:

• type: Description

Usage Examples

# Extract from docstring examples or generate basic usage

## Analysis Approach

1. **Parse Python files** using AST or inspection
2. **Extract key elements:**
   - Module-level docstrings
   - Class definitions and docstrings
   - Function/method signatures with type hints
   - Docstring content (support Google, NumPy, Sphinx formats)
3. **Organize hierarchically** (modules -> classes -> methods -> functions)
4. **Generate clean markdown** with consistent formatting

## Quality Guidelines

- Preserve original docstring formatting when meaningful
- Include type hints prominently in signatures
- Group related items (all classes together, all functions together)
- Add table of contents for large modules
- Skip private members (leading underscore) unless explicitly requested
- Handle missing docstrings gracefully (note "No description provided")

## Python Tools

Prefer standard library:
- `ast` module for parsing
- `inspect` module for runtime introspection
- `pathlib` for file handling

No external dependencies required for basic documentation generation.

## Error Handling

- Skip files with syntax errors (log warning)
- Handle missing type hints gracefully
- Warn if no docstrings found but continue processing
- Validate file paths exist before processing