feat: add --api OpenAPI build mode with docs/api scheme and lib-prefixed nav

docforge/cli/commands.py

@@ -10,7 +10,7 @@ from pathlib import Path
 
 import click
 
-from docforge.cli import mcp_utils, mkdocs_utils
+from docforge.cli import api_utils, mcp_utils, mkdocs_utils
 from docforge.loaders import GriffeLoader
 
 
@@ -28,19 +28,25 @@ def cli() -> None:
 @cli.command()
 @click.option("--mcp", is_flag=True, help="Build MCP resources")
 @click.option("--mkdocs", is_flag=True, help="Build MkDocs site")
+@click.option("--api", is_flag=True, help="Build API docs from an OpenAPI spec")
 @click.option(
     "--module-is-source",
     is_flag=True,
     help="Module is source folder and to be treated as root folder",
 )
 @click.option("--module", help="Python module to document")
+@click.option(
+    "--openapi-spec",
+    type=click.Path(path_type=Path),
+    help="Path to the OpenAPI JSON specification",
+)
 @click.option("--project-name", help="Project name override")
 @click.option("--site-name", help="MkDocs site name")
 @click.option(
     "--docs-dir",
     type=click.Path(path_type=Path),
-    default=Path("docs/lib"),
-    help="Directory for MD sources",
+    default=Path("docs"),
+    help="MkDocs documentation root",
 )
 @click.option(
     "--nav",
@@ -67,8 +73,10 @@ def cli() -> None:
 def build(
     mcp: bool,
     mkdocs: bool,
+    api: bool,
     module_is_source: bool,
     module: str | None,
+    openapi_spec: Path | None,
     project_name: str | None,
     site_name: str | None,
     docs_dir: Path,
@@ -81,14 +89,13 @@ def build(
     Build documentation artifacts.
 
     This command performs the full documentation build pipeline:
-
-    1. Introspects the Python project using Griffe
-    2. Generates renderer-specific documentation sources
-    3. Optionally builds the final documentation output
+    style of the selected platform, generates renderer-specific
+    documentation sources, and optionally builds the final output.
 
     Depending on the selected options, the build can target:
 
-    - MkDocs static documentation sites
+    - MkDocs static documentation sites for library reference docs
+    - Swagger-enabled API docs generated from an OpenAPI spec
     - MCP structured documentation resources
 
     Args:
@@ -96,7 +103,10 @@ def build(
             Enable MCP documentation generation.
 
         mkdocs (bool):
-            Enable MkDocs documentation generation.
+            Enable MkDocs library documentation generation.
+
+        api (bool):
+            Enable API documentation generation from an OpenAPI spec.
 
         module_is_source (bool):
             Treat the specified module directory as the project root.
@@ -104,6 +114,9 @@ def build(
         module (Optional[str]):
             Python module import path to document.
 
+        openapi_spec (Optional[Path]):
+            Path to the OpenAPI JSON specification used for API docs.
+
         project_name (Optional[str]):
             Optional override for the project name.
 
@@ -111,7 +124,7 @@ def build(
             Display name for the MkDocs site.
 
         docs_dir (Path):
-            Directory where Markdown documentation sources will be generated.
+            Shared documentation root used as the MkDocs ``docs_dir``.
 
         nav_file (Path):
             Path to the navigation specification file.
@@ -129,27 +142,72 @@ def build(
         click.UsageError:
             If required options are missing or conflicting.
     """
-    if not mcp and not mkdocs:
-        raise click.UsageError("Must specify either --mcp or --mkdocs")
+    if not mcp and not mkdocs and not api:
+        raise click.UsageError("Must specify either --mcp, --mkdocs, or --api")
+
+    if api:
+        if not openapi_spec:
+            raise click.UsageError("--openapi-spec is required for API build")
+        if site_name and not mkdocs:
+            raise click.UsageError(
+                "--site-name cannot be overridden for API build; "
+                "the OpenAPI spec provides the site name"
+            )
+
+    if (mkdocs or mcp) and not module:
+        raise click.UsageError(
+            "--module is required for MkDocs build"
+            if mkdocs
+            else "--module is required for MCP build"
+        )
+
+    spec: dict | None = None
+    if api:
+        spec = api_utils.load_openapi_spec(openapi_spec)
 
     if mkdocs:
-        if not module:
-            raise click.UsageError("--module is required for MkDocs build")
-        if not site_name:
-            site_name = module
-
-        click.echo(f"Generating MkDocs sources in {docs_dir}...")
+        lib_dir = docs_dir / "lib"
+        click.echo(f"Generating MkDocs sources in {lib_dir}...")
         mkdocs_utils.generate_sources(
             module,
-            docs_dir,
+            lib_dir,
             project_name,
             module_is_source,
             readme_dir=mkdocs_yml.parent,
         )
 
+    if api:
+        api_dir = docs_dir / "api"
+        click.echo(f"Generating API sources in {api_dir}...")
+        api_utils.generate_api_sources(spec, api_dir)
+
+    if mkdocs or api:
+        modes: list[str] = []
+        if mkdocs:
+            modes.append("lib")
+        if api:
+            modes.append("api")
+
+        site_description: str | None = None
+        site_author: str | None = None
+        effective_site_name = site_name or module
+
+        if api:
+            metadata = api_utils.derive_metadata(spec)
+            effective_site_name = metadata.site_name
+            site_description = metadata.site_description
+            site_author = metadata.site_author
+
         click.echo(f"Generating MkDocs config {mkdocs_yml}...")
         mkdocs_utils.generate_config(
-            docs_dir, nav_file, template, mkdocs_yml, site_name
+            docs_dir,
+            nav_file,
+            template,
+            mkdocs_yml,
+            effective_site_name,
+            modes=modes,
+            site_description=site_description,
+            site_author=site_author,
         )
 
         click.echo("Running MkDocs build...")