docs/developer-guide/sphinx-integration.md

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

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

# 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

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

Full Sphinx Workflow

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

Customization

Adding New Modules

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

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:

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

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