doc-generator

• 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"

Accept either:

• Single Python file path
• Directory path (recursively process .py files)
• List of specific files

Generate standard markdown with:

```markdown

# Module Name

Brief description from module docstring.

ClassName

Description from class docstring.

Methods:

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

function_name(param: type) -> return_type

Description from docstring.

Parameters:

• param (type): Description

Returns:

• type: Description

```python

# Extract from docstring examples or generate basic usage

```

```

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)

1. Organize hierarchically (modules -> classes -> methods -> functions)
2. Generate clean markdown with consistent formatting

• 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")

Prefer standard library:

• ast module for parsing
• inspect module for runtime introspection
• pathlib for file handling

No external dependencies required for basic documentation generation.

• 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