# Sphinx Integration with MkDocs

This document explains how Sphinx is integrated with MkDocs in the KGraph-MCP project to provide comprehensive API documentation.

## Overview

The KGraph-MCP project uses a hybrid documentation approach:

- **MkDocs** with Material theme for the main documentation site
- **Sphinx** for automatic API documentation generation from Python docstrings
- **mkdocstrings** for seamless integration between the two systems

## Architecture

```mermaid
graph TD
    A[Python Source Code] --> B[Sphinx autodoc]
    B --> C[Generated RST Files]
    C --> D[Sphinx HTML Build]
    
    A --> E[mkdocstrings]
    E --> F[Markdown API Docs]
    F --> G[MkDocs Build]
    
    G --> H[Unified Documentation Site]
    D --> H
```

## Key Components

### 1. Sphinx Configuration (`conf.py`)

The Sphinx configuration includes:

- **autodoc**: Automatic documentation from docstrings
- **napoleon**: Google/NumPy docstring support
- **autoapi**: Advanced API documentation generation
- **intersphinx**: Cross-project reference linking
- **sphinx_autodoc_typehints**: Type hint documentation

### 2. Documentation Generator (`scripts/gen_sphinx_docs.py`)

This script:

- Runs Sphinx autodoc on all Python modules
- Converts generated content to Markdown
- Integrates with mkdocstrings for seamless rendering
- Maintains consistent theming with Material design

### 3. MkDocs Integration

MkDocs plugins used for integration:

- `mkdocs-gen-files`: Dynamic file generation during build
- `mkdocs-literate-nav`: Dynamic navigation generation
- `mkdocstrings[python]`: Python-specific documentation rendering

## File Structure

```
project/
├── conf.py                     # Sphinx configuration
├── _source/                    # Sphinx source files (generated)
├── _build/                     # Sphinx build output
├── _static/                    # Sphinx static files
├── docs/
│   ├── api/                    # Generated API documentation
│   │   ├── index.md           # Main API overview
│   │   ├── api/               # FastAPI framework docs
│   │   ├── agents/            # Agent framework docs
│   │   └── kg-services/       # Knowledge graph docs
│   └── SUMMARY.md             # Navigation structure
└── scripts/
    └── gen_sphinx_docs.py     # Documentation generator
```

## Usage

### Generating Documentation

```bash
# Generate only Sphinx API docs
just docs-sphinx-generate

# Build complete documentation (Sphinx + MkDocs)
just docs

# Serve with live reload
just docs-serve
```

### Individual Module Documentation

```bash
# Generate docs for specific module
just docs-sphinx-apidoc api
just docs-sphinx-apidoc agents
just docs-sphinx-apidoc kg_services
```

### Full Sphinx Workflow

```bash
# Clean, generate, and build everything
just docs-sphinx-full
```

## Customization

### Adding New Modules

1. Add module path to `scripts/gen_sphinx_docs.py`:

```python
self.modules = {
    "new_module": {
        "path": "new_module",
        "title": "New Module Title",
        "description": "Module description"
    },
    # ... existing modules
}
```

2. Update navigation in `mkdocs.yml`
3. Regenerate documentation

### Customizing Themes

The Sphinx theme is customized in `_static/custom.css` to match the Material theme:

- Color scheme consistency
- Typography matching (Roboto fonts)
- Component styling alignment
- Responsive design patterns

### Docstring Standards

Follow Google-style docstrings for best results:

```python
def example_function(param1: str, param2: int) -> bool:
    """Example function with proper docstring.
    
    Args:
        param1: Description of the first parameter.
        param2: Description of the second parameter.
        
    Returns:
        Description of the return value.
        
    Raises:
        ValueError: If param2 is negative.
        
    Example:
        >>> result = example_function("test", 42)
        >>> print(result)
        True
    """
    return param2 > 0
```

## Configuration Options

### Sphinx Extensions

Key extensions and their purposes:

| Extension | Purpose |
|-----------|---------|
| `sphinx.ext.autodoc` | Extract docstrings automatically |
| `sphinx.ext.napoleon` | Parse Google/NumPy docstrings |
| `sphinx.ext.viewcode` | Add source code links |
| `sphinx.ext.intersphinx` | Link to external documentation |
| `autoapi.extension` | Advanced API documentation |

### MkDocs Plugins

| Plugin | Purpose |
|--------|---------|
| `mkdocs-gen-files` | Generate files during build |
| `mkdocstrings` | Render Python documentation |
| `literate-nav` | Dynamic navigation |
| `section-index` | Section index pages |

## Troubleshooting

### Common Issues

1. **Import Errors**: Ensure all dependencies are installed
2. **Path Issues**: Check `sys.path` configuration in `conf.py`
3. **Docstring Formatting**: Verify Google-style docstring format
4. **Build Failures**: Check Sphinx and MkDocs logs

### Debug Commands

```bash
# Validate Sphinx configuration
just docs-sphinx-validate

# Check for docstring issues
uv run python -m sphinx.ext.autodoc --help

# Test individual module imports
uv run python -c "import api.main; help(api.main)"
```

### Performance Optimization

- Use `autoapi_keep_files = True` to cache generated files
- Enable `autoapi_python_class_content = 'both'` for comprehensive docs
- Configure `exclude_patterns` to skip unnecessary files

## Best Practices

1. **Consistent Docstrings**: Use Google-style docstrings throughout
2. **Type Hints**: Include comprehensive type annotations
3. **Examples**: Provide usage examples in docstrings
4. **Cross-References**: Use Sphinx cross-reference syntax
5. **Regular Updates**: Regenerate docs with code changes

## Integration Benefits

This hybrid approach provides:

- **Automatic Updates**: API docs stay in sync with code
- **Rich Formatting**: Support for code examples, cross-references, and media
- **Unified Experience**: Consistent theming and navigation
- **Performance**: Optimized build process with caching
- **Flexibility**: Easy customization of both content and presentation

The integration ensures that developers have access to comprehensive, up-to-date API documentation alongside the main project documentation, all within a single, cohesive site.