Vishesh 'ironeagle' Bangotra
b6306baafc
# Improve documentation look & feel via MkDocs Material template enhancements ## Summary This MR improves the overall **documentation experience and visual presentation** of the doc-forge docs by enhancing the MkDocs Material template configuration. The changes focus on **navigation usability, code readability, and richer Markdown rendering**, resulting in a cleaner and more professional documentation site. Docstring changes were made across the codebase for consistency, but this MR description focuses on the **template and presentation improvements**. --- ## Navigation Improvements The navigation system has been enhanced to provide a clearer structure and better discoverability. Key improvements include: * Section-aware navigation in the sidebar * Automatic expansion of module/package hierarchy * Scroll tracking within the sidebar * Clickable package index pages Material navigation features added: * `navigation.sections` * `navigation.expand` * `navigation.tracking` * `navigation.indexes` This results in a **single cohesive navigation tree** that exposes the entire documentation hierarchy from the sidebar. --- ## Code Block Improvements Code blocks previously appeared relatively plain. The template now enables richer syntax highlighting and improved readability. Enhancements include: * Syntax highlighting using `pymdownx.highlight` * Line numbers for code blocks * Anchored line numbers for deep linking * Improved fenced code block rendering Additional Material features: * `content.code.copy` — copy button for code blocks * `content.code.annotate` — support for code annotations These changes significantly improve the readability of examples and API snippets throughout the documentation. --- ## Markdown Rendering Enhancements Additional Markdown extensions were enabled to support richer documentation features: * `pymdownx.superfences` for advanced fenced blocks * `pymdownx.inlinehilite` for inline code highlighting * `pymdownx.snippets` for reusable snippets * `admonition` and `pymdownx.details` for callouts and collapsible sections * `pymdownx.tabbed` for tabbed content blocks * `pymdownx.tasklist` for checklist-style items * `tables`, `footnotes`, and advanced formatting extensions These extensions make it easier to write expressive and structured documentation. --- ## Search Experience The documentation search experience has been improved using Material search features: * `search.highlight` * `search.share` * `search.suggest` These enhancements provide: * highlighted search matches * sharable search URLs * auto-suggestions while typing --- ## mkdocstrings Improvements The mkdocstrings configuration has been expanded to produce clearer API documentation. Notable improvements include: * grouping objects by category * explicit category headings * improved symbol headings * cleaner object path display This results in more structured API documentation pages. --- ## Result Overall, these changes provide: * cleaner and more intuitive navigation * significantly improved code presentation * richer Markdown capabilities * better search usability The documentation now has a **more polished, modern appearance** and improved usability for both readers and contributors. Reviewed-on: #5 Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com> Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
67 lines
2.2 KiB
Python
67 lines
2.2 KiB
Python
from pathlib import Path
|
|
import click
|
|
from docforge.loaders import GriffeLoader, discover_module_paths
|
|
from docforge.renderers import MCPRenderer
|
|
from docforge.servers import MCPServer
|
|
|
|
|
|
def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None:
|
|
"""
|
|
Generate MCP documentation resources from a Python module.
|
|
|
|
The function performs project introspection, builds the internal
|
|
documentation model, and renders MCP-compatible JSON resources
|
|
to the specified output directory.
|
|
|
|
Args:
|
|
module: Python module import path used as the entry point for
|
|
documentation generation.
|
|
project_name: Optional override for the project name used in
|
|
generated documentation metadata.
|
|
out_dir: Directory where MCP resources (index.json, nav.json,
|
|
and module data) will be written.
|
|
"""
|
|
loader = GriffeLoader()
|
|
discovered_paths = discover_module_paths(module)
|
|
project = loader.load_project(discovered_paths, project_name)
|
|
|
|
renderer = MCPRenderer()
|
|
renderer.generate_sources(project, out_dir)
|
|
|
|
|
|
def serve(module: str, mcp_root: Path) -> None:
|
|
"""
|
|
Start an MCP server for a pre-generated documentation bundle.
|
|
|
|
The server exposes documentation resources such as project metadata,
|
|
navigation structure, and module documentation through MCP endpoints.
|
|
|
|
Args:
|
|
module: Python module import path used to identify the served
|
|
documentation instance.
|
|
mcp_root: Path to the directory containing the MCP documentation
|
|
bundle (index.json, nav.json, and modules/).
|
|
|
|
Raises:
|
|
click.ClickException: If the MCP documentation bundle is missing
|
|
required files or directories.
|
|
"""
|
|
if not mcp_root.exists():
|
|
raise click.ClickException(f"mcp_docs directory not found: {mcp_root}")
|
|
|
|
required = [
|
|
mcp_root / "index.json",
|
|
mcp_root / "nav.json",
|
|
mcp_root / "modules",
|
|
]
|
|
|
|
for path in required:
|
|
if not path.exists():
|
|
raise click.ClickException(f"Invalid MCP bundle, missing: {path.name}")
|
|
|
|
server = MCPServer(
|
|
mcp_root=mcp_root,
|
|
name=f"{module}-mcp",
|
|
)
|
|
server.run()
|