From 15c59ab27406c5a11b6e90af760169bb91264b3f Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Wed, 21 Jan 2026 17:36:08 +0530 Subject: [PATCH] doc changes --- docforge/cli/main.py | 8 +++-- docforge/loaders/griffe_loader.py | 36 +++++++++++++++++++ docforge/nav/resolver.py | 12 +++++++ docforge/servers/mcp_server.py | 22 ++++++++++++ mcp_docs/modules/docforge.cli.json | 14 ++++---- mcp_docs/modules/docforge.cli.main.json | 14 ++++---- mcp_docs/modules/docforge.json | 24 ++++++------- .../docforge.loaders.griffe_loader.json | 2 +- mcp_docs/modules/docforge.loaders.json | 2 +- mcp_docs/modules/docforge.nav.json | 2 +- mcp_docs/modules/docforge.nav.resolver.json | 2 +- mcp_docs/modules/docforge.servers.json | 4 +-- .../modules/docforge.servers.mcp_server.json | 4 +-- 13 files changed, 110 insertions(+), 36 deletions(-) diff --git a/docforge/cli/main.py b/docforge/cli/main.py index c7151a7..09bf0a4 100644 --- a/docforge/cli/main.py +++ b/docforge/cli/main.py @@ -64,7 +64,11 @@ def tree( def _print_object(obj, indent: str) -> None: """ - Recursive helper to print doc objects. + Recursive helper to print doc objects and their members to the console. + + Args: + obj: The DocObject to print. + indent: The current line indentation string. """ click.echo(f"{indent}├── {obj.name}") for member in obj.get_all_members(): @@ -262,7 +266,7 @@ def serve(mkdocs_yml: Path) -> None: def main() -> None: """ - CLI Entry point. + CLI Entry point. Boots the click application. """ cli() diff --git a/docforge/loaders/griffe_loader.py b/docforge/loaders/griffe_loader.py index d08b8b2..c4ff540 100644 --- a/docforge/loaders/griffe_loader.py +++ b/docforge/loaders/griffe_loader.py @@ -134,6 +134,15 @@ class GriffeLoader: # ------------------------- def _convert_module(self, obj: Object) -> Module: + """ + Convert a Griffe Object (module) into a docforge Module. + + Args: + obj: The Griffe Object representing the module. + + Returns: + A populated Module instance. + """ module = Module( path=obj.path, docstring=self._safe_docstring(obj), @@ -148,6 +157,15 @@ class GriffeLoader: return module def _convert_object(self, obj: Object) -> DocObject: + """ + Recursively convert a Griffe Object into a DocObject hierarchy. + + Args: + obj: The Griffe Object to convert. + + Returns: + A DocObject instance. + """ kind = obj.kind.value signature = self._safe_signature(obj) @@ -174,12 +192,30 @@ class GriffeLoader: # ------------------------- def _safe_docstring(self, obj: Object) -> Optional[str]: + """ + Safely retrieve the docstring value from a Griffe object. + + Args: + obj: The Griffe Object to inspect. + + Returns: + The raw docstring string, or None if missing or unresolvable. + """ try: return obj.docstring.value if obj.docstring else None except AliasResolutionError: return None def _safe_signature(self, obj: Object) -> Optional[str]: + """ + Safely retrieve the signature string from a Griffe object. + + Args: + obj: The Griffe Object to inspect. + + Returns: + The string representation of the signature, or None. + """ try: if hasattr(obj, "signature") and obj.signature: return str(obj.signature) diff --git a/docforge/nav/resolver.py b/docforge/nav/resolver.py index 3333ab6..ee97617 100644 --- a/docforge/nav/resolver.py +++ b/docforge/nav/resolver.py @@ -78,6 +78,18 @@ def resolve_nav( raise FileNotFoundError(docs_root) def resolve_pattern(pattern: str) -> List[Path]: + """ + Resolve a single glob pattern relative to the docs_root. + + Args: + pattern: The glob pattern to resolve. + + Returns: + A sorted list of matching Path objects. + + Raises: + FileNotFoundError: If the pattern doesn't match any files. + """ full = docs_root / pattern matches = sorted( Path(p) for p in glob.glob(str(full), recursive=True) diff --git a/docforge/servers/mcp_server.py b/docforge/servers/mcp_server.py index 75d2f3a..9ba34d9 100644 --- a/docforge/servers/mcp_server.py +++ b/docforge/servers/mcp_server.py @@ -13,6 +13,13 @@ class MCPServer: """ def __init__(self, mcp_root: Path, name: str) -> None: + """ + Initialize the MCPServer. + + Args: + mcp_root: Path to the directory containing pre-built MCP JSON resources. + name: Name of the MCP server. + """ self.mcp_root = mcp_root self.app = FastMCP(name) @@ -24,6 +31,15 @@ class MCPServer: # ------------------------------------------------------------------ def _read_json(self, path: Path) -> Any: + """ + Read and parse a JSON file, returning diagnostic errors if missing. + + Args: + path: Path to the JSON file. + + Returns: + The parsed JSON data or an error dictionary. + """ if not path.exists(): return { "error": "not_found", @@ -36,6 +52,9 @@ class MCPServer: # ------------------------------------------------------------------ def _register_resources(self) -> None: + """ + Register MCP resources for index, nav, and individual modules. + """ @self.app.resource("docs://index") def index(): return self._read_json(self.mcp_root / "index.json") @@ -55,6 +74,9 @@ class MCPServer: # ------------------------------------------------------------------ def _register_tools(self) -> None: + """ + Register high-level MCP tools for diagnostics. + """ @self.app.tool() def ping() -> str: return "pong" diff --git a/mcp_docs/modules/docforge.cli.json b/mcp_docs/modules/docforge.cli.json index 1d2b07d..bb68c75 100644 --- a/mcp_docs/modules/docforge.cli.json +++ b/mcp_docs/modules/docforge.cli.json @@ -140,43 +140,43 @@ "name": "generate", "kind": "function", "path": "docforge.cli.main.generate", - "signature": "", + "signature": "", "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The primary module path to document.\n project_name: Optional project name override.\n docs_dir: Directory where documentation sources will be written." }, "generate_mcp": { "name": "generate_mcp", "kind": "function", "path": "docforge.cli.main.generate_mcp", - "signature": "", + "signature": "", "docstring": "Generate MCP-compatible documentation resources for the specified module.\n\nArgs:\n module: The primary module path to document.\n project_name: Optional project name override.\n out_dir: Directory where MCP resources will be written." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.main.build", - "signature": "", + "signature": "", "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." }, "serve_mcp": { "name": "serve_mcp", "kind": "function", "path": "docforge.cli.main.serve_mcp", - "signature": "", + "signature": "", "docstring": "Serve MCP documentation from the local mcp_docs directory." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.main.serve", - "signature": "", + "signature": "", "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." }, "main": { "name": "main", "kind": "function", "path": "docforge.cli.main.main", - "signature": "", - "docstring": "CLI Entry point." + "signature": "", + "docstring": "CLI Entry point. Boots the click application." } } }, diff --git a/mcp_docs/modules/docforge.cli.main.json b/mcp_docs/modules/docforge.cli.main.json index a102155..16965a2 100644 --- a/mcp_docs/modules/docforge.cli.main.json +++ b/mcp_docs/modules/docforge.cli.main.json @@ -133,43 +133,43 @@ "name": "generate", "kind": "function", "path": "docforge.cli.main.generate", - "signature": "", + "signature": "", "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The primary module path to document.\n project_name: Optional project name override.\n docs_dir: Directory where documentation sources will be written." }, "generate_mcp": { "name": "generate_mcp", "kind": "function", "path": "docforge.cli.main.generate_mcp", - "signature": "", + "signature": "", "docstring": "Generate MCP-compatible documentation resources for the specified module.\n\nArgs:\n module: The primary module path to document.\n project_name: Optional project name override.\n out_dir: Directory where MCP resources will be written." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.main.build", - "signature": "", + "signature": "", "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." }, "serve_mcp": { "name": "serve_mcp", "kind": "function", "path": "docforge.cli.main.serve_mcp", - "signature": "", + "signature": "", "docstring": "Serve MCP documentation from the local mcp_docs directory." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.main.serve", - "signature": "", + "signature": "", "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." }, "main": { "name": "main", "kind": "function", "path": "docforge.cli.main.main", - "signature": "", - "docstring": "CLI Entry point." + "signature": "", + "docstring": "CLI Entry point. Boots the click application." } } } diff --git a/mcp_docs/modules/docforge.json b/mcp_docs/modules/docforge.json index 0c1633d..df5969d 100644 --- a/mcp_docs/modules/docforge.json +++ b/mcp_docs/modules/docforge.json @@ -252,7 +252,7 @@ "kind": "function", "path": "docforge.main.main", "signature": "", - "docstring": "CLI Entry point." + "docstring": "CLI Entry point. Boots the click application." } } }, @@ -399,43 +399,43 @@ "name": "generate", "kind": "function", "path": "docforge.cli.main.generate", - "signature": "", + "signature": "", "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The primary module path to document.\n project_name: Optional project name override.\n docs_dir: Directory where documentation sources will be written." }, "generate_mcp": { "name": "generate_mcp", "kind": "function", "path": "docforge.cli.main.generate_mcp", - "signature": "", + "signature": "", "docstring": "Generate MCP-compatible documentation resources for the specified module.\n\nArgs:\n module: The primary module path to document.\n project_name: Optional project name override.\n out_dir: Directory where MCP resources will be written." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.main.build", - "signature": "", + "signature": "", "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." }, "serve_mcp": { "name": "serve_mcp", "kind": "function", "path": "docforge.cli.main.serve_mcp", - "signature": "", + "signature": "", "docstring": "Serve MCP documentation from the local mcp_docs directory." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.main.serve", - "signature": "", + "signature": "", "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." }, "main": { "name": "main", "kind": "function", "path": "docforge.cli.main.main", - "signature": "", - "docstring": "CLI Entry point." + "signature": "", + "docstring": "CLI Entry point. Boots the click application." } } }, @@ -828,7 +828,7 @@ "name": "GriffeLoader", "kind": "class", "path": "docforge.loaders.griffe_loader.GriffeLoader", - "signature": "", + "signature": "", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", "members": { "load_project": { @@ -1714,7 +1714,7 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolver.resolve_nav", - "signature": "", + "signature": "", "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n spec: The navigation specification to resolve.\n docs_root: The root directory for documentation files.\n\nReturns:\n A ResolvedNav instance.\n\nRaises:\n FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist." }, "Optional": { @@ -2463,7 +2463,7 @@ "name": "MCPServer", "kind": "class", "path": "docforge.servers.mcp_server.MCPServer", - "signature": "", + "signature": "", "docstring": "MCP server for serving a pre-built MCP documentation bundle.", "members": { "mcp_root": { @@ -2484,7 +2484,7 @@ "name": "run", "kind": "function", "path": "docforge.servers.mcp_server.MCPServer.run", - "signature": "", + "signature": "", "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" } } diff --git a/mcp_docs/modules/docforge.loaders.griffe_loader.json b/mcp_docs/modules/docforge.loaders.griffe_loader.json index d179ba4..85323ea 100644 --- a/mcp_docs/modules/docforge.loaders.griffe_loader.json +++ b/mcp_docs/modules/docforge.loaders.griffe_loader.json @@ -252,7 +252,7 @@ "name": "GriffeLoader", "kind": "class", "path": "docforge.loaders.griffe_loader.GriffeLoader", - "signature": "", + "signature": "", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", "members": { "load_project": { diff --git a/mcp_docs/modules/docforge.loaders.json b/mcp_docs/modules/docforge.loaders.json index 5dac927..8e833b2 100644 --- a/mcp_docs/modules/docforge.loaders.json +++ b/mcp_docs/modules/docforge.loaders.json @@ -289,7 +289,7 @@ "name": "GriffeLoader", "kind": "class", "path": "docforge.loaders.griffe_loader.GriffeLoader", - "signature": "", + "signature": "", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", "members": { "load_project": { diff --git a/mcp_docs/modules/docforge.nav.json b/mcp_docs/modules/docforge.nav.json index 2416f69..164fb34 100644 --- a/mcp_docs/modules/docforge.nav.json +++ b/mcp_docs/modules/docforge.nav.json @@ -297,7 +297,7 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolver.resolve_nav", - "signature": "", + "signature": "", "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n spec: The navigation specification to resolve.\n docs_root: The root directory for documentation files.\n\nReturns:\n A ResolvedNav instance.\n\nRaises:\n FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist." }, "Optional": { diff --git a/mcp_docs/modules/docforge.nav.resolver.json b/mcp_docs/modules/docforge.nav.resolver.json index 174cc97..4c12de7 100644 --- a/mcp_docs/modules/docforge.nav.resolver.json +++ b/mcp_docs/modules/docforge.nav.resolver.json @@ -110,7 +110,7 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolver.resolve_nav", - "signature": "", + "signature": "", "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n spec: The navigation specification to resolve.\n docs_root: The root directory for documentation files.\n\nReturns:\n A ResolvedNav instance.\n\nRaises:\n FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist." }, "Optional": { diff --git a/mcp_docs/modules/docforge.servers.json b/mcp_docs/modules/docforge.servers.json index 20cd8cd..cdf9e81 100644 --- a/mcp_docs/modules/docforge.servers.json +++ b/mcp_docs/modules/docforge.servers.json @@ -87,7 +87,7 @@ "name": "MCPServer", "kind": "class", "path": "docforge.servers.mcp_server.MCPServer", - "signature": "", + "signature": "", "docstring": "MCP server for serving a pre-built MCP documentation bundle.", "members": { "mcp_root": { @@ -108,7 +108,7 @@ "name": "run", "kind": "function", "path": "docforge.servers.mcp_server.MCPServer.run", - "signature": "", + "signature": "", "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" } } diff --git a/mcp_docs/modules/docforge.servers.mcp_server.json b/mcp_docs/modules/docforge.servers.mcp_server.json index e062ccd..8ab31cc 100644 --- a/mcp_docs/modules/docforge.servers.mcp_server.json +++ b/mcp_docs/modules/docforge.servers.mcp_server.json @@ -50,7 +50,7 @@ "name": "MCPServer", "kind": "class", "path": "docforge.servers.mcp_server.MCPServer", - "signature": "", + "signature": "", "docstring": "MCP server for serving a pre-built MCP documentation bundle.", "members": { "mcp_root": { @@ -71,7 +71,7 @@ "name": "run", "kind": "function", "path": "docforge.servers.mcp_server.MCPServer.run", - "signature": "", + "signature": "", "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" } }