---
name: docs
description: Automatically generate documentation including docstrings, README, and API docs
---

# Documentation Generation Skill

## Description

This skill provides automatic documentation generation for Python codebases. It can generate docstrings for functions and classes, create README files, and produce API documentation in various formats.

## When to Use

- When adding docstrings to undocumented code
- When creating or updating README files
- When generating API documentation
- When standardizing documentation style across a codebase

## Commands

```
/docs                           # Show documentation options
/docs --docstring <function>    # Generate docstring for function
/docs --readme                  # Generate README.md
/docs --api <module>            # Generate API docs for module
/docs --style google|numpy      # Set documentation style
```

## Docstring Styles

### Google Style (Default)

```python
def function(arg1: str, arg2: int = 0) -> bool:
    """Short description.

    Longer description if needed.

    Args:
        arg1 (str): Description of arg1.
        arg2 (int): Description of arg2. Defaults to 0.

    Returns:
        bool: Description of return value.

    Raises:
        ValueError: When arg1 is empty.

    Examples:
        >>> function("hello", 42)
        True
    """
```

### NumPy Style

```python
def function(arg1, arg2=0):
    """Short description.

    Longer description if needed.

    Parameters
    ----------
    arg1 : str
        Description of arg1.
    arg2 : int, optional
        Description of arg2 (default is 0).

    Returns
    -------
    bool
        Description of return value.

    Raises
    ------
    ValueError
        When arg1 is empty.
    """
```

### Sphinx Style

```python
def function(arg1, arg2=0):
    """Short description.

    :param arg1: Description of arg1.
    :type arg1: str
    :param arg2: Description of arg2.
    :type arg2: int
    :returns: Description of return value.
    :rtype: bool
    :raises ValueError: When arg1 is empty.
    """
```

## How to Use

### Step 1: Generate Docstrings

Add docstrings to functions:

```
/docs --docstring process_data
```

The skill will:
1. Parse the function signature
2. Extract type hints
3. Generate appropriate docstring
4. Optionally use AI for description

### Step 2: Generate README

Create a README for your project:

```
/docs --readme
```

This generates:
- Project title and description
- Installation instructions
- Basic usage examples
- API reference (optional)
- License information

### Step 3: Generate API Documentation

Create comprehensive API docs:

```
/docs --api src/mymodule.py
```

Output includes:
- Module description
- Class documentation
- Method signatures and descriptions
- Function documentation

## Output Formats

| Format | Command | Best For |
|--------|---------|----------|
| Markdown | `--format markdown` | GitHub, general |
| reStructuredText | `--format rst` | Sphinx docs |
| HTML | `--format html` | Web hosting |

## Best Practices

1. **Keep Descriptions Concise**: First line should be a brief summary
2. **Document All Parameters**: Include type and description
3. **Show Examples**: Add usage examples when helpful
4. **Note Exceptions**: Document raised exceptions
5. **Stay Consistent**: Use the same style throughout

## Examples

### Example 1: Add Missing Docstrings

**User Request:** "Add docstrings to all functions in utils.py"

**Approach:**
1. Parse utils.py to find undocumented functions
2. Generate Google-style docstrings for each
3. Show preview of changes
4. Apply on confirmation

### Example 2: Generate Project README

**User Request:** "/docs --readme"

**Approach:**
1. Analyze project structure
2. Extract info from pyproject.toml
3. Generate installation instructions
4. Add usage examples
5. Include API overview

### Example 3: Full API Documentation

**User Request:** "Generate API documentation for the entire src/ directory"

**Approach:**
1. Find all Python modules in src/
2. Extract classes and functions
3. Generate documentation for each
4. Create index with cross-references
5. Output in requested format

## AI-Enhanced Documentation

When an LLM model is available:

- **Smart Descriptions**: AI generates meaningful descriptions
- **Example Generation**: AI creates realistic usage examples
- **Context-Aware**: AI considers function purpose and usage
- **Natural Language**: More readable documentation

## Integration

Documentation can be generated:
- On-demand via commands
- As part of commit workflow
- In CI/CD pipelines
- Through pre-commit hooks

## Notes

- Works best with type-hinted code
- Existing docstrings are preserved unless --force
- Large files may be processed incrementally
- AI generation requires model configuration
- Style consistency is enforced within files
