File size: 5,507 Bytes
65be7f3 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 |
#!/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() |