cli-cleanup (#2)

Reviewed-on: #2
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>

docforge/cli/commands.py

@@ -43,6 +43,23 @@ def build(
 ) -> None:
     """
     Build documentation (MkDocs site or MCP resources).
+
+    This command orchestrates the full build process:
+    1. Introspects the code (Griffe)
+    2. Renders sources (MkDocs Markdown or MCP JSON)
+    3. (MkDocs only) Generates config and runs the final site build.
+
+    Args:
+        mcp: Use the MCP documentation builder.
+        mkdocs: Use the MkDocs documentation builder.
+        module: The dotted path of the module to document.
+        project_name: Optional override for the project name.
+        site_name: (MkDocs) The site display name. Defaults to module name.
+        docs_dir: (MkDocs) Target directory for Markdown sources.
+        nav_file: (MkDocs) Path to the docforge.nav.yml specification.
+        template: (MkDocs) Optional custom mkdocs.yml template.
+        mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.
+        out_dir: (MCP) Target directory for MCP JSON resources.
     """
     if not mcp and not mkdocs:
         raise click.UsageError("Must specify either --mcp or --mkdocs")
@@ -84,7 +101,13 @@ def serve(
     out_dir: Path,
 ) -> None:
     """
-    Serve documentation.
+    Serve documentation (MkDocs or MCP).
+
+    Args:
+        mcp: Serve MCP resources via an MCP server.
+        mkdocs: Serve the MkDocs site using the built-in development server.
+        mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.
+        out_dir: (MCP) Path to the mcp_docs/ directory.
     """
     if mcp and mkdocs:
         raise click.UsageError("Cannot specify both --mcp and --mkdocs")
@@ -113,7 +136,11 @@ def tree(
     project_name: Optional[str],
 ) -> None:
     """
-    Visualize the project structure.
+    Visualize the project structure in the terminal.
+
+    Args:
+        modules: List of module import paths to recursively introspect.
+        project_name: Optional override for the project name shown at the root.
     """
     loader = GriffeLoader()
     project = loader.load_project(list(modules), project_name)
@@ -129,6 +156,10 @@ def tree(
 def _print_object(obj, indent: str) -> None:
     """
     Recursive helper to print doc objects and their members to the console.
+
+    Args:
+        obj: The DocObject instance to print.
+        indent: Current line indentation (e.g., '│   ').
     """
     click.echo(f"{indent}├── {obj.name}")
     for member in obj.get_all_members():

docforge/cli/main.py

@@ -1,5 +1,6 @@
 """
-Main entry point for the doc-forge CLI.
+Main entry point for the doc-forge CLI. This module delegates all command
+execution to docforge.cli.commands.
 """
 from docforge.cli.commands import cli
 

docforge/cli/mcp_utils.py

@@ -7,6 +7,11 @@ from docforge.servers import MCPServer
 def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None:
     """
     Generate MCP-compatible documentation resources.
+
+    Args:
+        module: The dotted path of the primary module to document.
+        project_name: Optional override for the project name.
+        out_dir: Directory where the MCP JSON resources and nav will be written.
     """
     loader = GriffeLoader()
     discovered_paths = discover_module_paths(module)
@@ -17,7 +22,10 @@ def generate_resources(module: str, project_name: str | None, out_dir: Path) ->
 
 def serve(mcp_root: Path) -> None:
     """
-    Serve MCP documentation.
+    Serve MCP documentation from a pre-built bundle.
+
+    Args:
+        mcp_root: Path to the directory containing index.json, nav.json, and modules/.
     """
     if not mcp_root.exists():
         raise click.ClickException(f"mcp_docs directory not found: {mcp_root}")

docforge/cli/mkdocs_utils.py

@@ -9,6 +9,11 @@ from docforge.nav import load_nav_spec, resolve_nav, MkDocsNavEmitter
 def generate_sources(module: str, project_name: str | None, docs_dir: Path) -> None:
     """
     Generate Markdown source files for the specified module.
+
+    Args:
+        module: The dotted path of the primary module to document.
+        project_name: Optional override for the project name.
+        docs_dir: Directory where the generated Markdown files will be written.
     """
     loader = GriffeLoader()
     discovered_paths = discover_module_paths(module)
@@ -20,6 +25,13 @@ def generate_sources(module: str, project_name: str | None, docs_dir: Path) -> N
 def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None:
     """
     Generate an mkdocs.yml configuration file.
+
+    Args:
+        docs_dir: Path to the directory containing documentation Markdown files.
+        nav_file: Path to the docforge.nav.yml specification.
+        template: Optional path to an mkdocs.yml template (overrides built-in).
+        out: Path where the final mkdocs.yml will be written.
+        site_name: The display name for the documentation site.
     """
     if not nav_file.exists():
         raise click.FileError(str(nav_file), hint="Nav spec not found")
@@ -49,6 +61,9 @@ def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out:
 def build(mkdocs_yml: Path) -> None:
     """
     Build the documentation site using MkDocs.
+
+    Args:
+        mkdocs_yml: Path to the mkdocs.yml configuration file.
     """
     if not mkdocs_yml.exists():
         raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
@@ -61,6 +76,9 @@ def build(mkdocs_yml: Path) -> None:
 def serve(mkdocs_yml: Path) -> None:
     """
     Serve the documentation site with live-reload using MkDocs.
+
+    Args:
+        mkdocs_yml: Path to the mkdocs.yml configuration file.
     """
     if not mkdocs_yml.exists():
         raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")

docforge/renderers/mcp_renderer.py

@@ -15,6 +15,10 @@ class MCPRenderer:
     def generate_sources(self, project: Project, out_dir: Path) -> None:
         """
         Generate MCP-compatible JSON resources and navigation for the project.
+
+        Args:
+            project: The project model to render.
+            out_dir: Target directory for the generated JSON files.
         """
         modules_dir = out_dir / "modules"
         modules_dir.mkdir(parents=True, exist_ok=True)
@@ -50,7 +54,11 @@ class MCPRenderer:
 
     def _write_module(self, module: Module, modules_dir: Path) -> None:
         """
-        Serialize a module into an MCP JSON resource.
+        Serialize a module into an MCP JSON resource on disk.
+
+        Args:
+            module: The module instance to serialize.
+            modules_dir: The directory where the module JSON file should be written.
         """
         payload = {
             "module": module.path,
@@ -64,6 +72,12 @@ class MCPRenderer:
     def _render_module(self, module: Module) -> Dict:
         """
         Render a Module into MCP-friendly structured data.
+
+        Args:
+            module: The module instance to render.
+
+        Returns:
+            A dictionary following the MCP documentation resource schema.
         """
         data: Dict = {
             "path": module.path,
@@ -79,6 +93,12 @@ class MCPRenderer:
     def _render_object(self, obj: DocObject) -> Dict:
         """
         Recursively render a DocObject into structured MCP data.
+
+        Args:
+            obj: The documented object (class, func, etc.) to render.
+
+        Returns:
+            A dictionary representing the object and its members.
         """
         data: Dict = {
             "name": obj.name,