aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc changes

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-01-21 17:36:08 +05:30
parent e33133cb0e
commit 15c59ab274
13 changed files with 110 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docforge/cli/main.py
View File

@@ -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()

36
docforge/loaders/griffe_loader.py
View File

@@ -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)

12
docforge/nav/resolver.py
View File

@@ -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)

22
docforge/servers/mcp_server.py
View File

@@ -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"

14
mcp_docs/modules/docforge.cli.json
View File

@@ -140,43 +140,43 @@
"name": "generate",
"kind": "function",
"path": "docforge.cli.main.generate",
"signature": "<bound method Function.signature of Function('generate', 78, 118)>",
"signature": "<bound method Function.signature of Function('generate', 82, 122)>",
"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": "<bound method Function.signature of Function('generate_mcp', 125, 164)>",
"signature": "<bound method Function.signature of Function('generate_mcp', 129, 168)>",
"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": "<bound method Function.signature of Function('build', 171, 192)>",
"signature": "<bound method Function.signature of Function('build', 175, 196)>",
"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": "<bound method Function.signature of Function('serve_mcp', 199, 226)>",
"signature": "<bound method Function.signature of Function('serve_mcp', 203, 230)>",
"docstring": "Serve MCP documentation from the local mcp_docs directory."
},
"serve": {
"name": "serve",
"kind": "function",
"path": "docforge.cli.main.serve",
"signature": "<bound method Function.signature of Function('serve', 233, 256)>",
"signature": "<bound method Function.signature of Function('serve', 237, 260)>",
"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": "<bound method Function.signature of Function('main', 263, 267)>",
"docstring": "CLI Entry point."
"signature": "<bound method Function.signature of Function('main', 267, 271)>",
"docstring": "CLI Entry point. Boots the click application."
}
}
},

14
mcp_docs/modules/docforge.cli.main.json
View File

@@ -133,43 +133,43 @@
"name": "generate",
"kind": "function",
"path": "docforge.cli.main.generate",
"signature": "<bound method Function.signature of Function('generate', 78, 118)>",
"signature": "<bound method Function.signature of Function('generate', 82, 122)>",
"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": "<bound method Function.signature of Function('generate_mcp', 125, 164)>",
"signature": "<bound method Function.signature of Function('generate_mcp', 129, 168)>",
"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": "<bound method Function.signature of Function('build', 171, 192)>",
"signature": "<bound method Function.signature of Function('build', 175, 196)>",
"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": "<bound method Function.signature of Function('serve_mcp', 199, 226)>",
"signature": "<bound method Function.signature of Function('serve_mcp', 203, 230)>",
"docstring": "Serve MCP documentation from the local mcp_docs directory."
},
"serve": {
"name": "serve",
"kind": "function",
"path": "docforge.cli.main.serve",
"signature": "<bound method Function.signature of Function('serve', 233, 256)>",
"signature": "<bound method Function.signature of Function('serve', 237, 260)>",
"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": "<bound method Function.signature of Function('main', 263, 267)>",
"docstring": "CLI Entry point."
"signature": "<bound method Function.signature of Function('main', 267, 271)>",
"docstring": "CLI Entry point. Boots the click application."
}
}
}

24
mcp_docs/modules/docforge.json
View File

@@ -252,7 +252,7 @@
"kind": "function",
"path": "docforge.main.main",
"signature": "<bound method Alias.signature of Alias('main', 'docforge.cli.main.main')>",
"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": "<bound method Function.signature of Function('generate', 78, 118)>",
"signature": "<bound method Function.signature of Function('generate', 82, 122)>",
"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": "<bound method Function.signature of Function('generate_mcp', 125, 164)>",
"signature": "<bound method Function.signature of Function('generate_mcp', 129, 168)>",
"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": "<bound method Function.signature of Function('build', 171, 192)>",
"signature": "<bound method Function.signature of Function('build', 175, 196)>",
"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": "<bound method Function.signature of Function('serve_mcp', 199, 226)>",
"signature": "<bound method Function.signature of Function('serve_mcp', 203, 230)>",
"docstring": "Serve MCP documentation from the local mcp_docs directory."
},
"serve": {
"name": "serve",
"kind": "function",
"path": "docforge.cli.main.serve",
"signature": "<bound method Function.signature of Function('serve', 233, 256)>",
"signature": "<bound method Function.signature of Function('serve', 237, 260)>",
"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": "<bound method Function.signature of Function('main', 263, 267)>",
"docstring": "CLI Entry point."
"signature": "<bound method Function.signature of Function('main', 267, 271)>",
"docstring": "CLI Entry point. Boots the click application."
}
}
},
@@ -828,7 +828,7 @@
"name": "GriffeLoader",
"kind": "class",
"path": "docforge.loaders.griffe_loader.GriffeLoader",
"signature": "<bound method Class.signature of Class('GriffeLoader', 65, 188)>",
"signature": "<bound method Class.signature of Class('GriffeLoader', 65, 224)>",
"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": "<bound method Function.signature of Function('resolve_nav', 59, 112)>",
"signature": "<bound method Function.signature of Function('resolve_nav', 59, 124)>",
"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": "<bound method Class.signature of Class('MCPServer', 10, 73)>",
"signature": "<bound method Class.signature of Class('MCPServer', 10, 95)>",
"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": "<bound method Function.signature of Function('run', 66, 73)>",
"signature": "<bound method Function.signature of Function('run', 88, 95)>",
"docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)"
}
}

2
mcp_docs/modules/docforge.loaders.griffe_loader.json
View File

@@ -252,7 +252,7 @@
"name": "GriffeLoader",
"kind": "class",
"path": "docforge.loaders.griffe_loader.GriffeLoader",
"signature": "<bound method Class.signature of Class('GriffeLoader', 65, 188)>",
"signature": "<bound method Class.signature of Class('GriffeLoader', 65, 224)>",
"docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": {
"load_project": {

2
mcp_docs/modules/docforge.loaders.json
View File

@@ -289,7 +289,7 @@
"name": "GriffeLoader",
"kind": "class",
"path": "docforge.loaders.griffe_loader.GriffeLoader",
"signature": "<bound method Class.signature of Class('GriffeLoader', 65, 188)>",
"signature": "<bound method Class.signature of Class('GriffeLoader', 65, 224)>",
"docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": {
"load_project": {

2
mcp_docs/modules/docforge.nav.json
View File

@@ -297,7 +297,7 @@
"name": "resolve_nav",
"kind": "function",
"path": "docforge.nav.resolver.resolve_nav",
"signature": "<bound method Function.signature of Function('resolve_nav', 59, 112)>",
"signature": "<bound method Function.signature of Function('resolve_nav', 59, 124)>",
"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": {

2
mcp_docs/modules/docforge.nav.resolver.json
View File

@@ -110,7 +110,7 @@
"name": "resolve_nav",
"kind": "function",
"path": "docforge.nav.resolver.resolve_nav",
"signature": "<bound method Function.signature of Function('resolve_nav', 59, 112)>",
"signature": "<bound method Function.signature of Function('resolve_nav', 59, 124)>",
"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": {

4
mcp_docs/modules/docforge.servers.json
View File

@@ -87,7 +87,7 @@
"name": "MCPServer",
"kind": "class",
"path": "docforge.servers.mcp_server.MCPServer",
"signature": "<bound method Class.signature of Class('MCPServer', 10, 73)>",
"signature": "<bound method Class.signature of Class('MCPServer', 10, 95)>",
"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": "<bound method Function.signature of Function('run', 66, 73)>",
"signature": "<bound method Function.signature of Function('run', 88, 95)>",
"docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)"
}
}

4
mcp_docs/modules/docforge.servers.mcp_server.json
View File

@@ -50,7 +50,7 @@
"name": "MCPServer",
"kind": "class",
"path": "docforge.servers.mcp_server.MCPServer",
"signature": "<bound method Class.signature of Class('MCPServer', 10, 73)>",
"signature": "<bound method Class.signature of Class('MCPServer', 10, 95)>",
"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": "<bound method Function.signature of Function('run', 66, 73)>",
"signature": "<bound method Function.signature of Function('run', 88, 95)>",
"docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)"
}
}