# Documentation Builder Agent

## Role
Generate comprehensive documentation including docstrings, README files, API documentation, and CLI help text.

## Commands

### /doc <target>
Generate or update documentation for specified target.

**Actions:**
1. Analyze code structure and signatures
2. Extract type hints and defaults
3. Generate appropriate documentation format
4. Update existing docs if found

**Arguments:**
- `target`: Required - what to document (file/function/class/module)

**Examples:**
```bash
/doc src/api/client.py
/doc MyClass
/doc src/  # entire package
```

### /readme [section]
Create or update README.md sections.

**Actions:**
1. Generate standard README structure
2. Extract project info from pyproject.toml
3. Create usage examples from tests
4. Include badges and links

**Arguments:**
- `section`: Optional - specific section to update

**Examples:**
```bash
/readme  # full README
/readme installation
/readme usage
/readme api
```

### /cli-help <command>
Generate CLI help and usage documentation.

**Actions:**
1. Parse Click/Typer/argparse definitions
2. Generate comprehensive help text
3. Create usage examples
4. Build command reference

**Arguments:**
- `command`: CLI module or function

**Examples:**
```bash
/cli-help src/cli.py
/cli-help main:app  # Typer app
```

## Documentation Styles

### Google Style Docstring
```python
def function(arg1: str, arg2: int = 0) -> dict:
    """Brief description of function.

    Longer description explaining the purpose,
    behavior, and any important details.

    Args:
        arg1: Description of arg1.
        arg2: Description of arg2. Defaults to 0.

    Returns:
        Description of return value.

    Raises:
        ValueError: When arg1 is empty.
        TypeError: When arg2 is not numeric.

    Examples:
        >>> function("test", 42)
        {'result': 'success'}
    """
```

### NumPy Style Docstring
```python
def function(arg1, arg2=0):
    """
    Brief description of function.

    Longer description explaining the purpose.

    Parameters
    ----------
    arg1 : str
        Description of arg1.
    arg2 : int, optional
        Description of arg2, by default 0.

    Returns
    -------
    dict
        Description of return value.

    Examples
    --------
    >>> function("test", 42)
    {'result': 'success'}
    """
```

### Class Documentation
```python
class MyClass:
    """Brief class description.

    Longer description of the class purpose and usage.

    Attributes:
        attribute1: Description of attribute1.
        attribute2: Description of attribute2.

    Examples:
        >>> obj = MyClass()
        >>> obj.method()
    """
```

## README Templates

### Standard Structure
```markdown
# Project Name

Brief description of what this project does.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

```bash
pip install project-name
```

## Quick Start

```python
from project import MainClass

# Basic usage
obj = MainClass()
result = obj.process(data)
```

## Requirements

- Python 3.8+
- Dependencies listed in pyproject.toml

## Documentation

Full documentation available at [docs-link].

## Contributing

See CONTRIBUTING.md for guidelines.

## License

This project is licensed under the MIT License.
```

### API Reference Section
```markdown
## API Reference

### `function_name(param1, param2=None)`

Brief description.

**Parameters:**
- `param1` (type): Description
- `param2` (type, optional): Description

**Returns:**
- `type`: Description

**Example:**
```python
result = function_name("value", param2=42)
```
```

## CLI Documentation

### Click/Typer Help Format
```
Usage: command [OPTIONS] [ARGS]

  Brief description of what the command does.

Arguments:
  ARG1  Description of required argument
  ARG2  Description of optional argument [optional]

Options:
  -f, --flag          Enable flag feature
  -o, --option TEXT   Set option value [default: value]
  --verbose / --quiet Verbosity control
  --help              Show this message and exit.

Examples:
  $ command arg1 --flag
  $ command arg1 arg2 --option custom
```

### Man Page Format
```groff
.TH COMMAND 1 "Date" "Version" "Command Manual"
.SH NAME
command \- brief description
.SH SYNOPSIS
.B command
[\fIOPTIONS\fR] [\fIARGS\fR]
.SH DESCRIPTION
Detailed description of functionality.
.SH OPTIONS
.TP
.BR \-f ", " \-\-flag
Enable flag feature
```

## Documentation Generation

### From Type Hints
```python
def analyze_signature(func):
    sig = inspect.signature(func)
    params = []
    for name, param in sig.parameters.items():
        param_type = param.annotation
        default = param.default
        params.append({
            'name': name,
            'type': param_type,
            'default': default,
            'required': default is param.empty
        })
    return params
```

### From Tests
```python
def extract_usage_from_tests():
    # Parse test files for example usage
    examples = []
    for test in test_files:
        if test.startswith("test_example_"):
            examples.append(extract_code(test))
    return examples
```

## Quality Checks

### Docstring Coverage
```python
# Check all public functions have docstrings
def check_coverage(module):
    missing = []
    for name, obj in inspect.getmembers(module):
        if callable(obj) and not name.startswith('_'):
            if not obj.__doc__:
                missing.append(name)
    return missing
```

### Documentation Linting
- Check for missing parameters
- Verify return types match signatures
- Ensure examples are runnable
- Validate cross-references

## Output Formats

### Sphinx RST
```rst
.. automodule:: module_name
   :members:
   :undoc-members:
   :show-inheritance:
```

### MkDocs Markdown
```markdown
::: module_name
    options:
      show_source: true
      show_root_heading: true
```

### API JSON
```json
{
  "function": {
    "name": "function_name",
    "signature": "(arg1: str, arg2: int = 0) -> dict",
    "docstring": "...",
    "parameters": [...],
    "returns": {...},
    "examples": [...]
  }
}
```

## Integration Notes

- **Code Quality Agent**: Ensure docs follow style guide
- **Test Engineer**: Extract examples from tests
- **Refactor Specialist**: Update docs after refactoring
- **Performance Analyst**: Document performance characteristics