home / skills / basher83 / agent-auditor / doc-generator

doc-generator skill

safe

This skill generates comprehensive Markdown documentation from Python code by extracting docstrings, type hints, and structure for API docs and READMEs.

npx playbooks add skill basher83/agent-auditor --skill doc-generator

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.5 KB

---
name: doc-generator
description: Generate markdown documentation from Python codebases by analyzing source files, extracting docstrings, type hints, and code structure. Use when the user asks to document Python code, create API docs, or generate README files from source code.
---

# 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:

```markdown
# 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

```python
# 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

Overview

This skill generates Markdown documentation from Python code by analyzing source files, extracting docstrings, type hints, and code structure. It produces organized API references, class/method summaries, and usage examples suitable for READMEs or developer docs. The output is clean, hierarchical Markdown that preserves docstring text and highlights type signatures. It is optimized for quick integration into project documentation pipelines.

How this skill works

The generator parses files using the Python AST and can optionally use runtime inspection where available. It extracts module docstrings, class and function definitions, method signatures with type hints, and docstring content (Google, NumPy, or Sphinx styles). Files are processed individually or recursively for directories, then assembled into a standardized Markdown layout with sections for classes, functions, parameters, and examples.

When to use it

When a user asks to document Python code, create API docs, or generate a README from source files
To extract docstrings and type signatures into a readable reference for developers
When preparing library or service documentation before a release
To create quick usage examples from embedded docstring examples
When converting multiple modules into a single Markdown API reference

Best practices

Include clear module, class, and function docstrings to maximize output quality
Use type hints for public APIs so signatures in docs are informative
Follow a consistent docstring style (Google/NumPy/Sphinx) for better parsing
Exclude private members (leading underscore) unless explicitly requested
Run the generator on clean code; files with syntax errors will be skipped with a warning

Example use cases

Generate an API reference Markdown file for a Python package before publishing
Create a README with basic usage examples extracted from docstrings
Produce class and method overviews for internal developer onboarding
Batch-generate docs from a directory of modules for CI documentation steps
Convert type-annotated function signatures into a human-friendly reference

FAQ

What input formats are supported?

Single Python file, a directory (recursively processing .py files), or a list of specific files.

How are missing docstrings handled?

Members without docstrings are included with a 'No description provided' note; you can exclude them if desired.

Does it require external dependencies?

No. It relies on the Python standard library (ast, inspect, pathlib) for basic generation.