Improve documentation look & feel via MkDocs Material template enhancements (#5)
# 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>
This commit is contained in:
@@ -1,5 +1,15 @@
|
||||
"""
|
||||
Server layer for doc-forge.
|
||||
|
||||
This module exposes server implementations used to provide live access
|
||||
to generated documentation resources. Currently, it includes the MCP
|
||||
documentation server.
|
||||
|
||||
---
|
||||
"""
|
||||
|
||||
from .mcp_server import MCPServer
|
||||
|
||||
__all__ = [
|
||||
"MCPServer",
|
||||
]
|
||||
]
|
||||
|
||||
@@ -9,16 +9,21 @@ from mcp.server.fastmcp import FastMCP
|
||||
|
||||
class MCPServer:
|
||||
"""
|
||||
MCP server for serving a pre-built MCP documentation bundle.
|
||||
MCP server for serving a pre-generated documentation bundle.
|
||||
|
||||
The server exposes documentation resources and diagnostic tools through
|
||||
MCP endpoints backed by JSON files generated by the MCP renderer.
|
||||
"""
|
||||
|
||||
def __init__(self, mcp_root: Path, name: str) -> None:
|
||||
"""
|
||||
Initialize the MCPServer.
|
||||
Initialize the MCP server.
|
||||
|
||||
Args:
|
||||
mcp_root: Path to the directory containing pre-built MCP JSON resources.
|
||||
name: Name of the MCP server.
|
||||
mcp_root: Directory containing the generated MCP documentation
|
||||
bundle (for example ``index.json``, ``nav.json``, and
|
||||
``modules/``).
|
||||
name: Identifier used for the MCP server instance.
|
||||
"""
|
||||
self.mcp_root = mcp_root
|
||||
self.app = FastMCP(name)
|
||||
@@ -32,19 +37,24 @@ class MCPServer:
|
||||
|
||||
def _read_json(self, path: Path) -> Any:
|
||||
"""
|
||||
Read and parse a JSON file, returning diagnostic errors if missing.
|
||||
Load and parse a JSON file.
|
||||
|
||||
If the file does not exist, a structured error response is returned
|
||||
instead of raising an exception.
|
||||
|
||||
Args:
|
||||
path: Path to the JSON file.
|
||||
path: Path to the JSON file to read.
|
||||
|
||||
Returns:
|
||||
The parsed JSON data or an error dictionary.
|
||||
Parsed JSON data if the file exists, otherwise an error dictionary
|
||||
describing the missing resource.
|
||||
"""
|
||||
if not path.exists():
|
||||
return {
|
||||
"error": "not_found",
|
||||
"path": str(path),
|
||||
}
|
||||
|
||||
return json.loads(path.read_text(encoding="utf-8"))
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
@@ -53,8 +63,16 @@ class MCPServer:
|
||||
|
||||
def _register_resources(self) -> None:
|
||||
"""
|
||||
Register MCP resources for index, nav, and individual modules.
|
||||
Register MCP resource endpoints.
|
||||
|
||||
The server exposes documentation resources through the following
|
||||
endpoints:
|
||||
|
||||
- ``docs://index`` – Project metadata
|
||||
- ``docs://nav`` – Navigation structure
|
||||
- ``docs://modules/{module}`` – Individual module documentation
|
||||
"""
|
||||
|
||||
@self.app.resource("docs://index")
|
||||
def index():
|
||||
return self._read_json(self.mcp_root / "index.json")
|
||||
@@ -70,26 +88,35 @@ class MCPServer:
|
||||
)
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# MCP tools (optional / diagnostic)
|
||||
# MCP tools
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _register_tools(self) -> None:
|
||||
"""
|
||||
Register high-level MCP tools for diagnostics.
|
||||
Register optional MCP diagnostic tools.
|
||||
|
||||
These tools provide lightweight endpoints useful for verifying that
|
||||
the MCP server is operational.
|
||||
"""
|
||||
|
||||
@self.app.tool()
|
||||
def ping() -> str:
|
||||
"""Return a simple health check response."""
|
||||
return "pong"
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Server lifecycle
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def run(self, transport: Literal["stdio", "sse", "streamable-http"] = "streamable-http") -> None:
|
||||
def run(
|
||||
self,
|
||||
transport: Literal["stdio", "sse", "streamable-http"] = "streamable-http",
|
||||
) -> None:
|
||||
"""
|
||||
Start the MCP server.
|
||||
|
||||
Args:
|
||||
transport: MCP transport (default: streamable-http)
|
||||
transport: Transport mechanism used by the MCP server. Supported
|
||||
options include ``stdio``, ``sse``, and ``streamable-http``.
|
||||
"""
|
||||
self.app.run(transport=transport)
|
||||
|
||||
Reference in New Issue
Block a user