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

tests/cli/test_build_api.py

@@ -0,0 +1,134 @@
+import json
+from pathlib import Path
+
+from docforge.cli.main import cli
+
+
+def _write_spec(cwd, title="Aetoskia Auth Server", description="Auth docs"):
+    spec = {
+        "openapi": "3.1.0",
+        "info": {
+            "title": title,
+            "description": description,
+            "contact": {
+                "name": "Aetoskia Dev Team",
+                "email": "dev@aetoskia.com",
+            },
+            "version": "0.0.5",
+        },
+        "paths": {},
+    }
+    path = cwd / "openapi.json"
+    path.write_text(json.dumps(spec), encoding="utf-8")
+    return path
+
+
+def test_api_build_full_flow(
+    cli_runner,
+    mock_mkdocs_build,
+    mock_mkdocs_load_config,
+):
+    with cli_runner.isolated_filesystem():
+        cwd = Path.cwd()
+
+        spec_path = _write_spec(cwd)
+
+        nav_file = cwd / "docforge.nav.yml"
+        nav_file.write_text(
+            "home: api/index.md\ngroups: {}\n"
+            "icon:\n"
+            "  logo: material/database\n"
+            "  repo: fontawesome/brands/github\n",
+            encoding="utf-8",
+        )
+
+        result = cli_runner.invoke(
+            cli,
+            ["build", "--api", "--openapi-spec", str(spec_path)],
+        )
+
+        assert result.exit_code == 0, result.output
+        assert mock_mkdocs_build() is True
+
+        api_dir = cwd / "docs" / "api"
+        assert (api_dir / "openapi.json").exists()
+        index = (api_dir / "index.md").read_text(encoding="utf-8")
+        assert '<swagger-ui src="openapi.json"/>' in index
+
+        config = (cwd / "mkdocs.yml").read_text(encoding="utf-8")
+        assert "docs_dir: docs" in config
+        assert "site_name: Aetoskia Auth Server" in config
+        assert "site_description: Auth docs" in config
+        assert "site_author: Aetoskia Dev Team" in config
+        assert "swagger-ui-tag" in config
+        assert "logo: material/database" in config
+        assert "repo: fontawesome/brands/github" in config
+
+
+def test_api_build_missing_spec_fails(cli_runner):
+    result = cli_runner.invoke(cli, ["build", "--api"])
+    assert result.exit_code != 0
+    assert "--openapi-spec is required" in result.output
+
+
+def test_api_build_spec_not_found(cli_runner):
+    result = cli_runner.invoke(cli, ["build", "--api", "--openapi-spec", "nope.json"])
+    assert result.exit_code != 0
+    assert "OpenAPI spec not found" in result.output
+
+
+def test_api_build_rejects_site_name_override(cli_runner):
+    with cli_runner.isolated_filesystem():
+        cwd = Path.cwd()
+        spec_path = _write_spec(cwd)
+
+        result = cli_runner.invoke(
+            cli,
+            ["build", "--api", "--openapi-spec", str(spec_path), "--site-name", "X"],
+        )
+        assert result.exit_code != 0
+        assert "cannot be overridden" in result.output
+
+
+def test_api_build_combined_with_mkdocs_allows_site_name_for_lib(
+    cli_runner, mock_mkdocs_build, mock_mkdocs_load_config
+):
+    # site_name is accepted when --mkdocs is also present (lib mode owns it)
+    with cli_runner.isolated_filesystem():
+        cwd = Path.cwd()
+
+        pkg = cwd / "testpkg"
+        pkg.mkdir()
+        (pkg / "__init__.py").write_text("")
+        (pkg / "mod.py").write_text("def f(): ...\n")
+
+        spec_path = _write_spec(cwd)
+
+        nav_file = cwd / "docforge.nav.yml"
+        nav_file.write_text(
+            "home: lib/testpkg/index.md\n"
+            "groups:\n"
+            "  API:\n"
+            "    - api/index.md\n",
+            encoding="utf-8",
+        )
+
+        result = cli_runner.invoke(
+            cli,
+            [
+                "build",
+                "--mkdocs",
+                "--api",
+                "--module",
+                "testpkg",
+                "--openapi-spec",
+                str(spec_path),
+            ],
+        )
+
+        assert result.exit_code == 0, result.output
+
+        config = (cwd / "mkdocs.yml").read_text(encoding="utf-8")
+        assert "docs_dir: docs" in config
+        assert "swagger-ui-tag" in config
+        assert "mkdocstrings" in config