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

2026-09-11 05:37:56 +05:30
parent 17e8628197
commit bacf17b930
26 changed files with 1404 additions and 174 deletions
--- a/docs/mcp/modules/docforge.cli.api_utils.json
+++ b/docs/mcp/modules/docforge.cli.api_utils.json
@@ -0,0 +1,102 @@
+{
+  "module": "docforge.cli.api_utils",
+  "content": {
+    "path": "docforge.cli.api_utils",
+    "docstring": "# Summary\n\nUtilities for building API documentation from an OpenAPI specification.",
+    "objects": {
+      "json": {
+        "name": "json",
+        "kind": "alias",
+        "path": "docforge.cli.api_utils.json",
+        "signature": "<bound method Alias.signature of Alias('json', 'json')>",
+        "docstring": null
+      },
+      "dataclass": {
+        "name": "dataclass",
+        "kind": "alias",
+        "path": "docforge.cli.api_utils.dataclass",
+        "signature": "<bound method Alias.signature of Alias('dataclass', 'dataclasses.dataclass')>",
+        "docstring": null
+      },
+      "Path": {
+        "name": "Path",
+        "kind": "alias",
+        "path": "docforge.cli.api_utils.Path",
+        "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
+        "docstring": null
+      },
+      "click": {
+        "name": "click",
+        "kind": "alias",
+        "path": "docforge.cli.api_utils.click",
+        "signature": "<bound method Alias.signature of Alias('click', 'click')>",
+        "docstring": null
+      },
+      "SWAGGER_SPEC_FILENAME": {
+        "name": "SWAGGER_SPEC_FILENAME",
+        "kind": "attribute",
+        "path": "docforge.cli.api_utils.SWAGGER_SPEC_FILENAME",
+        "signature": null,
+        "docstring": null
+      },
+      "OpenAPIMetadata": {
+        "name": "OpenAPIMetadata",
+        "kind": "class",
+        "path": "docforge.cli.api_utils.OpenAPIMetadata",
+        "signature": "<bound method Class.signature of Class('OpenAPIMetadata', 16, 30)>",
+        "docstring": "Metadata derived from the ``info`` block of an OpenAPI specification.\n\nAttributes:\n    site_name: Spec title, used as the MkDocs site name.\n    site_description: Spec description, used as the site description.\n    site_author: Contact name (fallback: contact email), used as the\n        site author.",
+        "members": {
+          "site_name": {
+            "name": "site_name",
+            "kind": "attribute",
+            "path": "docforge.cli.api_utils.OpenAPIMetadata.site_name",
+            "signature": null,
+            "docstring": null
+          },
+          "site_description": {
+            "name": "site_description",
+            "kind": "attribute",
+            "path": "docforge.cli.api_utils.OpenAPIMetadata.site_description",
+            "signature": null,
+            "docstring": null
+          },
+          "site_author": {
+            "name": "site_author",
+            "kind": "attribute",
+            "path": "docforge.cli.api_utils.OpenAPIMetadata.site_author",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "load_openapi_spec": {
+        "name": "load_openapi_spec",
+        "kind": "function",
+        "path": "docforge.cli.api_utils.load_openapi_spec",
+        "signature": "<bound method Function.signature of Function('load_openapi_spec', 33, 63)>",
+        "docstring": "Load and validate an OpenAPI specification from a JSON file.\n\nArgs:\n    spec_path: Path to the OpenAPI JSON specification file.\n\nReturns:\n    dict:\n        The parsed OpenAPI specification.\n\nRaises:\n    click.ClickException:\n        If the file cannot be read or the ``info`` block is invalid."
+      },
+      "derive_metadata": {
+        "name": "derive_metadata",
+        "kind": "function",
+        "path": "docforge.cli.api_utils.derive_metadata",
+        "signature": "<bound method Function.signature of Function('derive_metadata', 66, 89)>",
+        "docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n    spec: Parsed OpenAPI specification.\n\nReturns:\n    OpenAPIMetadata:\n        Site name, description, and author derived from the spec."
+      },
+      "generate_api_sources": {
+        "name": "generate_api_sources",
+        "kind": "function",
+        "path": "docforge.cli.api_utils.generate_api_sources",
+        "signature": "<bound method Function.signature of Function('generate_api_sources', 92, 114)>",
+        "docstring": "Generate swagger-enabled Markdown sources and the spec copy.\n\nThe specification is written as ``openapi.json`` inside ``docs_dir`` and\nan ``index.md`` embedding the swagger UI is generated alongside it.\n\nArgs:\n    spec: Parsed OpenAPI specification.\n    docs_dir: Directory (for example ``docs/api``) where the swagger\n        sources are written."
+      },
+      "Any": {
+        "name": "Any",
+        "kind": "alias",
+        "path": "docforge.cli.api_utils.Any",
+        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+        "docstring": null
+      }
+    }
+  }
+}