archive/development_logs/site/gen_api_docs.py

#!/usr/bin/env python3
"""Generate API documentation files for mkdocs-gen-files plugin."""

import os
from pathlib import Path
import mkdocs_gen_files

def generate_api_docs():
    """Generate API documentation files."""
    
    # Base project path
    project_root = Path(__file__).parent.parent
    
    # API modules to document
    modules = [
        # Main API
        ("api", "FastAPI Framework"),
        ("api.main", "Main Application"),
        ("api.core", "Core Framework"),
        ("api.core.config", "Configuration"),
        ("api.core.dependencies", "Dependencies"),
        ("api.models", "Data Models"),
        ("api.routes", "API Routes"),
        ("api.services", "Services"),
        
        # Agents
        ("agents", "Agent Framework"),
        ("agents.planner", "Planning Agent"),
        ("agents.executor", "Execution Agent"),
        
        # Knowledge Graph Services
        ("kg_services", "Knowledge Graph Services"),
        ("kg_services.knowledge_graph", "Knowledge Graph Core"),
        ("kg_services.embedder", "Embedding Service"),
        ("kg_services.ontology", "Ontology Management"),
        ("kg_services.tool_discovery", "Tool Discovery"),
    ]
    
    # Generate documentation for each module
    for module_path, title in modules:
        # Skip if module file/directory doesn't exist
        module_file_py = project_root / f"{module_path.replace('.', '/')}.py"
        module_dir = project_root / f"{module_path.replace('.', '/')}"
        
        if not module_file_py.exists() and not module_dir.exists():
            print(f"Skipping {module_path} - not found")
            continue
            
        # Check if it's importable (but don't fail build if not)
        try:
            __import__(module_path)
            importable = True
        except ImportError as e:
            print(f"Warning: {module_path} - import error: {e}")
            importable = False
        
        # Create API doc file path
        api_doc_path = f"api/{module_path.replace('.', '/')}.md"
        
        # Generate the documentation content
        with mkdocs_gen_files.open(api_doc_path, "w") as f:
            f.write(f"# {title}\n\n")
            
            if importable:
                f.write(f"::: {module_path}\n")
                f.write("    options:\n")
                f.write("      show_root_heading: true\n")
                f.write("      show_source: true\n")
                f.write("      members_order: source\n")
                f.write("      docstring_style: google\n")
                f.write("      show_if_no_docstring: false\n")
            else:
                f.write(f"!!! warning \"Module Not Available\"\n")
                f.write(f"    The module `{module_path}` could not be imported. ")
                f.write(f"This may be due to missing dependencies or the module is under development.\n\n")
                f.write(f"**Expected Location**: `{module_path.replace('.', '/')}.py`\n\n")
                f.write(f"Please check the module implementation or dependencies.\n")
        
        print(f"Generated API docs for {module_path}")

    # Generate index files
    generate_index_files()

def generate_index_files():
    """Generate index files for API sections."""
    
    # Main API index
    with mkdocs_gen_files.open("api/index.md", "w") as f:
        f.write("# API Reference\n\n")
        f.write("Complete API documentation for KGraph-MCP.\n\n")
        f.write("## Sections\n\n")
        f.write("- [FastAPI Framework](api/index.md) - Main application and routing\n")
        f.write("- [Agent Framework](agents/index.md) - Planning and execution agents\n")
        f.write("- [Knowledge Graph Services](kg-services/index.md) - Core KG functionality\n")

    # FastAPI section index
    with mkdocs_gen_files.open("api/api/index.md", "w") as f:
        f.write("# FastAPI Framework\n\n")
        f.write("FastAPI application structure and components.\n\n")
        f.write("## Components\n\n")
        f.write("- [Main Application](main.md)\n")
        f.write("- [Core Framework](core/index.md)\n")
        f.write("- [Data Models](models/index.md)\n")
        f.write("- [API Routes](routes/index.md)\n")
        f.write("- [Services](services/index.md)\n")

    # Agents section index
    with mkdocs_gen_files.open("api/agents/index.md", "w") as f:
        f.write("# Agent Framework\n\n")
        f.write("AI agents for planning and task execution.\n\n")
        f.write("## Components\n\n")
        f.write("- [Planning Agent](planner.md)\n")
        f.write("- [Execution Agent](executor.md)\n")

    # KG Services section index
    with mkdocs_gen_files.open("api/kg-services/index.md", "w") as f:
        f.write("# Knowledge Graph Services\n\n")
        f.write("Core knowledge graph functionality and services.\n\n")
        f.write("## Components\n\n")
        f.write("- [Knowledge Graph Core](knowledge_graph.md)\n")
        f.write("- [Embedding Service](embedder.md)\n")
        f.write("- [Ontology Management](ontology.md)\n")
        f.write("- [Tool Discovery](tool_discovery.md)\n")

    # Core subsection index
    with mkdocs_gen_files.open("api/api/core/index.md", "w") as f:
        f.write("# Core Framework\n\n")
        f.write("Core application components and utilities.\n\n")
        f.write("## Components\n\n")
        f.write("- [Configuration](config.md)\n")
        f.write("- [Dependencies](dependencies.md)\n")

if __name__ == "__main__":
    generate_api_docs()