Vishesh 'ironeagle' Bangotra
582b6809a0
- fix GSDFC spec contradictions in __init__ docstring (parenthesized types, fenced-block rule) and sync generated README - rewrite docstrings across loaders, models, nav, servers, renderers, cli; sync .pyi stubs - add pydoclint (google style) gate to dev extras and pyproject config - fix mcp nav resources doc:// -> docs:// - refresh docs/lib and docs/mcp, drop stale docforge/ duplicate group - update wiki pages and add GSDFC + MCP guides under 05_development
551 lines
48 KiB
JSON
551 lines
48 KiB
JSON
{
|
|
"module": "docforge.cli.commands",
|
|
"content": {
|
|
"path": "docforge.cli.commands",
|
|
"docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.\n\n---\n\nNotes:\n - The `build` command validates requested modes before generating anything.\n - `--mkdocs`, `--api`, and `--wiki` share a single MkDocs build; `--mcp`\n generates a machine-readable bundle independently.\n\n---",
|
|
"objects": {
|
|
"Path": {
|
|
"name": "Path",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.Path",
|
|
"signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
|
|
"docstring": null
|
|
},
|
|
"click": {
|
|
"name": "click",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.click",
|
|
"signature": "<bound method Alias.signature of Alias('click', 'click')>",
|
|
"docstring": null
|
|
},
|
|
"api_utils": {
|
|
"name": "api_utils",
|
|
"kind": "module",
|
|
"path": "docforge.cli.commands.api_utils",
|
|
"signature": "<bound method Alias.signature of Alias('api_utils', 'docforge.cli.api_utils')>",
|
|
"docstring": "# Summary\n\nUtilities for building API documentation from an OpenAPI specification.",
|
|
"members": {
|
|
"json": {
|
|
"name": "json",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.api_utils.json",
|
|
"signature": "<bound method Alias.signature of Alias('json', 'docforge.cli.api_utils.json')>",
|
|
"docstring": null
|
|
},
|
|
"dataclass": {
|
|
"name": "dataclass",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.api_utils.dataclass",
|
|
"signature": "<bound method Alias.signature of Alias('dataclass', 'docforge.cli.api_utils.dataclass')>",
|
|
"docstring": null
|
|
},
|
|
"Path": {
|
|
"name": "Path",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.api_utils.Path",
|
|
"signature": "<bound method Alias.signature of Alias('Path', 'docforge.cli.api_utils.Path')>",
|
|
"docstring": null
|
|
},
|
|
"click": {
|
|
"name": "click",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.api_utils.click",
|
|
"signature": "<bound method Alias.signature of Alias('click', 'docforge.cli.api_utils.click')>",
|
|
"docstring": null
|
|
},
|
|
"SWAGGER_SPEC_FILENAME": {
|
|
"name": "SWAGGER_SPEC_FILENAME",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.api_utils.SWAGGER_SPEC_FILENAME",
|
|
"signature": "<bound method Alias.signature of Alias('SWAGGER_SPEC_FILENAME', 'docforge.cli.api_utils.SWAGGER_SPEC_FILENAME')>",
|
|
"docstring": null
|
|
},
|
|
"OpenAPIMetadata": {
|
|
"name": "OpenAPIMetadata",
|
|
"kind": "class",
|
|
"path": "docforge.cli.commands.api_utils.OpenAPIMetadata",
|
|
"signature": "<bound method Alias.signature of Alias('OpenAPIMetadata', 'docforge.cli.api_utils.OpenAPIMetadata')>",
|
|
"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.commands.api_utils.OpenAPIMetadata.site_name",
|
|
"signature": "<bound method Alias.signature of Alias('site_name', 'docforge.cli.api_utils.OpenAPIMetadata.site_name')>",
|
|
"docstring": null
|
|
},
|
|
"site_description": {
|
|
"name": "site_description",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.api_utils.OpenAPIMetadata.site_description",
|
|
"signature": "<bound method Alias.signature of Alias('site_description', 'docforge.cli.api_utils.OpenAPIMetadata.site_description')>",
|
|
"docstring": null
|
|
},
|
|
"site_author": {
|
|
"name": "site_author",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.api_utils.OpenAPIMetadata.site_author",
|
|
"signature": "<bound method Alias.signature of Alias('site_author', 'docforge.cli.api_utils.OpenAPIMetadata.site_author')>",
|
|
"docstring": null
|
|
}
|
|
}
|
|
},
|
|
"load_openapi_spec": {
|
|
"name": "load_openapi_spec",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.api_utils.load_openapi_spec",
|
|
"signature": "<bound method Alias.signature of Alias('load_openapi_spec', 'docforge.cli.api_utils.load_openapi_spec')>",
|
|
"docstring": "Load and validate an OpenAPI specification from a JSON file.\n\nArgs:\n spec_path (Path):\n 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.commands.api_utils.derive_metadata",
|
|
"signature": "<bound method Alias.signature of Alias('derive_metadata', 'docforge.cli.api_utils.derive_metadata')>",
|
|
"docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec (dict):\n 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.commands.api_utils.generate_api_sources",
|
|
"signature": "<bound method Alias.signature of Alias('generate_api_sources', 'docforge.cli.api_utils.generate_api_sources')>",
|
|
"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 (dict):\n Parsed OpenAPI specification.\n docs_dir (Path):\n Directory (for example ``docs/api``) where the swagger\n sources are written."
|
|
},
|
|
"Any": {
|
|
"name": "Any",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.api_utils.Any",
|
|
"signature": "<bound method Alias.signature of Alias('Any', 'docforge.cli.api_utils.Any')>",
|
|
"docstring": null
|
|
}
|
|
}
|
|
},
|
|
"mcp_utils": {
|
|
"name": "mcp_utils",
|
|
"kind": "module",
|
|
"path": "docforge.cli.commands.mcp_utils",
|
|
"signature": "<bound method Alias.signature of Alias('mcp_utils', 'docforge.cli.mcp_utils')>",
|
|
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.\n\n---\n\nNotes:\n - `generate_resources` produces the bundle consumed by `MCPServer`:\n `index.json`, `nav.json`, and per-module resources under `modules/`.\n - Resource URIs use the `docs://` scheme: `docs://index`, `docs://nav`,\n and `docs://modules/{module}`.\n\n---",
|
|
"members": {
|
|
"Path": {
|
|
"name": "Path",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.mcp_utils.Path",
|
|
"signature": "<bound method Alias.signature of Alias('Path', 'docforge.cli.mcp_utils.Path')>",
|
|
"docstring": null
|
|
},
|
|
"click": {
|
|
"name": "click",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.mcp_utils.click",
|
|
"signature": "<bound method Alias.signature of Alias('click', 'docforge.cli.mcp_utils.click')>",
|
|
"docstring": null
|
|
},
|
|
"GriffeLoader": {
|
|
"name": "GriffeLoader",
|
|
"kind": "class",
|
|
"path": "docforge.cli.commands.mcp_utils.GriffeLoader",
|
|
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp_utils.GriffeLoader')>",
|
|
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.\n\nAttributes:\n _loader (_GriffeLoader):\n Internal Griffe loader with dedicated module and line collections.",
|
|
"members": {
|
|
"load_project": {
|
|
"name": "load_project",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project",
|
|
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
|
|
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
|
|
},
|
|
"load_module": {
|
|
"name": "load_module",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module",
|
|
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
|
|
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance.\n\nRaises:\n ImportError:\n If the module cannot be loaded by Griffe.\n\n KeyError:\n If the loaded module is missing from the module collection.\n\nExample:\n Load a single module:\n\n ```python\n loader = GriffeLoader()\n module = loader.load_module(\"mypackage.submodule\")\n ```"
|
|
}
|
|
}
|
|
},
|
|
"discover_module_paths": {
|
|
"name": "discover_module_paths",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mcp_utils.discover_module_paths",
|
|
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp_utils.discover_module_paths')>",
|
|
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path | None):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n list[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
|
|
},
|
|
"MCPRenderer": {
|
|
"name": "MCPRenderer",
|
|
"kind": "class",
|
|
"path": "docforge.cli.commands.mcp_utils.MCPRenderer",
|
|
"signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.cli.mcp_utils.MCPRenderer')>",
|
|
"docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).",
|
|
"members": {
|
|
"name": {
|
|
"name": "name",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.mcp_utils.MCPRenderer.name",
|
|
"signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mcp_renderer.MCPRenderer.name')>",
|
|
"docstring": null
|
|
},
|
|
"generate_sources": {
|
|
"name": "generate_sources",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources",
|
|
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>",
|
|
"docstring": "Generate MCP documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as `nav.json` and `index.json`.\n\nArgs:\n project (Project):\n Documentation project model to render.\n\n out_dir (Path):\n Directory where MCP resources will be written."
|
|
}
|
|
}
|
|
},
|
|
"MCPServer": {
|
|
"name": "MCPServer",
|
|
"kind": "class",
|
|
"path": "docforge.cli.commands.mcp_utils.MCPServer",
|
|
"signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.cli.mcp_utils.MCPServer')>",
|
|
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.\n\nAttributes:\n mcp_root (Path):\n Directory containing the generated MCP documentation bundle.\n\n app (FastMCP):\n Underlying FastMCP application instance that registers resources\n and tools.",
|
|
"members": {
|
|
"mcp_root": {
|
|
"name": "mcp_root",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.mcp_utils.MCPServer.mcp_root",
|
|
"signature": "<bound method Alias.signature of Alias('mcp_root', 'docforge.servers.mcp_server.MCPServer.mcp_root')>",
|
|
"docstring": null
|
|
},
|
|
"app": {
|
|
"name": "app",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.mcp_utils.MCPServer.app",
|
|
"signature": "<bound method Alias.signature of Alias('app', 'docforge.servers.mcp_server.MCPServer.app')>",
|
|
"docstring": null
|
|
},
|
|
"run": {
|
|
"name": "run",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mcp_utils.MCPServer.run",
|
|
"signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>",
|
|
"docstring": "Start the MCP server.\n\nArgs:\n transport (Literal[\"stdio\", \"sse\", \"streamable-http\"]):\n Transport mechanism used by the MCP server. Supported options\n include `stdio`, `sse`, and `streamable-http`."
|
|
}
|
|
}
|
|
},
|
|
"generate_resources": {
|
|
"name": "generate_resources",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mcp_utils.generate_resources",
|
|
"signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp_utils.generate_resources')>",
|
|
"docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n project_name (str | None):\n Optional override for the project name used in generated\n documentation metadata.\n\n out_dir (Path):\n Directory where MCP resources (index.json, nav.json, and module data)\n will be written."
|
|
},
|
|
"serve": {
|
|
"name": "serve",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mcp_utils.serve",
|
|
"signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mcp_utils.serve')>",
|
|
"docstring": "Start an MCP server for a pre-generated documentation bundle.\n\nThe server exposes documentation resources such as project metadata,\nnavigation structure, and module documentation through MCP endpoints.\n\nArgs:\n module (str):\n Python module import path used to identify the served\n documentation instance.\n\n mcp_root (Path):\n Path to the directory containing the MCP documentation\n bundle (index.json, nav.json, and modules/).\n\nRaises:\n click.ClickException:\n If the MCP documentation bundle is missing required files or directories."
|
|
}
|
|
}
|
|
},
|
|
"mkdocs_utils": {
|
|
"name": "mkdocs_utils",
|
|
"kind": "module",
|
|
"path": "docforge.cli.commands.mkdocs_utils",
|
|
"signature": "<bound method Alias.signature of Alias('mkdocs_utils', 'docforge.cli.mkdocs_utils')>",
|
|
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A single generated `mkdocs.yml` serves lib, api, and wiki content with\n merged navigation. Wiki navigation, when enabled, precedes every other\n group and its `index.md` becomes the site `Home`.\n\n---",
|
|
"members": {
|
|
"os": {
|
|
"name": "os",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.mkdocs_utils.os",
|
|
"signature": "<bound method Alias.signature of Alias('os', 'docforge.cli.mkdocs_utils.os')>",
|
|
"docstring": null
|
|
},
|
|
"Iterable": {
|
|
"name": "Iterable",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.mkdocs_utils.Iterable",
|
|
"signature": "<bound method Alias.signature of Alias('Iterable', 'docforge.cli.mkdocs_utils.Iterable')>",
|
|
"docstring": null
|
|
},
|
|
"resources": {
|
|
"name": "resources",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.mkdocs_utils.resources",
|
|
"signature": "<bound method Alias.signature of Alias('resources', 'docforge.cli.mkdocs_utils.resources')>",
|
|
"docstring": null
|
|
},
|
|
"Path": {
|
|
"name": "Path",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.mkdocs_utils.Path",
|
|
"signature": "<bound method Alias.signature of Alias('Path', 'docforge.cli.mkdocs_utils.Path')>",
|
|
"docstring": null
|
|
},
|
|
"click": {
|
|
"name": "click",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.mkdocs_utils.click",
|
|
"signature": "<bound method Alias.signature of Alias('click', 'docforge.cli.mkdocs_utils.click')>",
|
|
"docstring": null
|
|
},
|
|
"yaml": {
|
|
"name": "yaml",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.mkdocs_utils.yaml",
|
|
"signature": "<bound method Alias.signature of Alias('yaml', 'docforge.cli.mkdocs_utils.yaml')>",
|
|
"docstring": null
|
|
},
|
|
"GriffeLoader": {
|
|
"name": "GriffeLoader",
|
|
"kind": "class",
|
|
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader",
|
|
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>",
|
|
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.\n\nAttributes:\n _loader (_GriffeLoader):\n Internal Griffe loader with dedicated module and line collections.",
|
|
"members": {
|
|
"load_project": {
|
|
"name": "load_project",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project",
|
|
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
|
|
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
|
|
},
|
|
"load_module": {
|
|
"name": "load_module",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module",
|
|
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
|
|
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance.\n\nRaises:\n ImportError:\n If the module cannot be loaded by Griffe.\n\n KeyError:\n If the loaded module is missing from the module collection.\n\nExample:\n Load a single module:\n\n ```python\n loader = GriffeLoader()\n module = loader.load_module(\"mypackage.submodule\")\n ```"
|
|
}
|
|
}
|
|
},
|
|
"discover_module_paths": {
|
|
"name": "discover_module_paths",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mkdocs_utils.discover_module_paths",
|
|
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs_utils.discover_module_paths')>",
|
|
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path | None):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n list[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
|
|
},
|
|
"MkDocsNavEmitter": {
|
|
"name": "MkDocsNavEmitter",
|
|
"kind": "class",
|
|
"path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter",
|
|
"signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.cli.mkdocs_utils.MkDocsNavEmitter')>",
|
|
"docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.",
|
|
"members": {
|
|
"emit": {
|
|
"name": "emit",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit",
|
|
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
|
|
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav (ResolvedNav):\n Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n list[dict[str, Any]]:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages."
|
|
}
|
|
}
|
|
},
|
|
"build_wiki_nav": {
|
|
"name": "build_wiki_nav",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mkdocs_utils.build_wiki_nav",
|
|
"signature": "<bound method Alias.signature of Alias('build_wiki_nav', 'docforge.cli.mkdocs_utils.build_wiki_nav')>",
|
|
"docstring": "Derive an MkDocs navigation block from a wiki directory.\n\nReturned paths are relative to the parent of ``wiki_dir`` and carry the\nwiki directory name as their leading component (for example\n``wiki/01_overview.md`` when the wiki lives at ``docs/wiki``). This makes\nthe result directly usable in an MkDocs ``nav`` block with\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries compatible with the MkDocs ``nav`` configuration.\n The list is empty if the wiki contains no Markdown files.\n\nRaises:\n FileNotFoundError:\n If the wiki directory does not exist."
|
|
},
|
|
"load_nav_spec": {
|
|
"name": "load_nav_spec",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mkdocs_utils.load_nav_spec",
|
|
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs_utils.load_nav_spec')>",
|
|
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path (Path):\n Path to the navigation specification file.\n\nReturns:\n NavSpec:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid."
|
|
},
|
|
"resolve_nav": {
|
|
"name": "resolve_nav",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mkdocs_utils.resolve_nav",
|
|
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs_utils.resolve_nav')>",
|
|
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec (NavSpec):\n Navigation specification describing documentation layout.\n docs_root (Path):\n Root directory containing documentation Markdown files.\n\nReturns:\n ResolvedNav:\n A `ResolvedNav` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files."
|
|
},
|
|
"MkDocsRenderer": {
|
|
"name": "MkDocsRenderer",
|
|
"kind": "class",
|
|
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer",
|
|
"signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.cli.mkdocs_utils.MkDocsRenderer')>",
|
|
"docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.",
|
|
"members": {
|
|
"name": {
|
|
"name": "name",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.name",
|
|
"signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.name')>",
|
|
"docstring": null
|
|
},
|
|
"generate_sources": {
|
|
"name": "generate_sources",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources",
|
|
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
|
|
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool | None):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder."
|
|
},
|
|
"generate_readme": {
|
|
"name": "generate_readme",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme",
|
|
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
|
|
"docstring": "Generate a `README.md` file from the root module docstring.\n\nNotes:\n - If `module_is_source` is True, `README.md` is written to the\n project root directory.\n - If False, README generation is currently not implemented.\n\nArgs:\n project (Project):\n Project model containing documentation metadata.\n\n docs_dir (Path):\n Directory containing generated documentation sources.\n\n module_is_source (bool | None):\n Whether the module is treated as the project source root.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`."
|
|
}
|
|
}
|
|
},
|
|
"generate_sources": {
|
|
"name": "generate_sources",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mkdocs_utils.generate_sources",
|
|
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>",
|
|
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``."
|
|
},
|
|
"generate_config": {
|
|
"name": "generate_config",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mkdocs_utils.generate_config",
|
|
"signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs_utils.generate_config')>",
|
|
"docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification (and, when a wiki directory is provided, from the wiki\nfile structure).\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories\nand hand-written wiki content under a ``wiki/`` subdirectory.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Iterable[str] | None):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib``, ``api``, or\n ``wiki``), merged on top of the shared ``mkdocs.common.yml``\n template.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n wiki_dir (Path | None):\n Optional path to a hand-written wiki directory (for example\n ``docs/wiki``). When provided, the site navigation is derived\n from the wiki file structure and placed before the navigation\n groups defined in ``nav_file``.\n\nRaises:\n click.FileError:\n If the navigation specification, template, or wiki directory\n cannot be found."
|
|
},
|
|
"build": {
|
|
"name": "build",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mkdocs_utils.build",
|
|
"signature": "<bound method Alias.signature of Alias('build', 'docforge.cli.mkdocs_utils.build')>",
|
|
"docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist."
|
|
},
|
|
"serve": {
|
|
"name": "serve",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.mkdocs_utils.serve",
|
|
"signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mkdocs_utils.serve')>",
|
|
"docstring": "Start an MkDocs development server with live reload.\n\nThe server watches documentation files and automatically reloads\nthe site when changes are detected.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist."
|
|
}
|
|
}
|
|
},
|
|
"GriffeLoader": {
|
|
"name": "GriffeLoader",
|
|
"kind": "class",
|
|
"path": "docforge.cli.commands.GriffeLoader",
|
|
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
|
|
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.\n\nAttributes:\n _loader (_GriffeLoader):\n Internal Griffe loader with dedicated module and line collections.",
|
|
"members": {
|
|
"load_project": {
|
|
"name": "load_project",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.GriffeLoader.load_project",
|
|
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
|
|
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
|
|
},
|
|
"load_module": {
|
|
"name": "load_module",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.GriffeLoader.load_module",
|
|
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
|
|
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance.\n\nRaises:\n ImportError:\n If the module cannot be loaded by Griffe.\n\n KeyError:\n If the loaded module is missing from the module collection.\n\nExample:\n Load a single module:\n\n ```python\n loader = GriffeLoader()\n module = loader.load_module(\"mypackage.submodule\")\n ```"
|
|
}
|
|
}
|
|
},
|
|
"DocObject": {
|
|
"name": "DocObject",
|
|
"kind": "class",
|
|
"path": "docforge.cli.commands.DocObject",
|
|
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
|
|
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (str | None):\n Callable signature if the object represents a callable.\n\n docstring (str | None):\n Raw docstring text extracted from the source code.\n\n members (dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.",
|
|
"members": {
|
|
"name": {
|
|
"name": "name",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.DocObject.name",
|
|
"signature": "<bound method Alias.signature of Alias('name', 'docforge.models.object.DocObject.name')>",
|
|
"docstring": null
|
|
},
|
|
"kind": {
|
|
"name": "kind",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.DocObject.kind",
|
|
"signature": "<bound method Alias.signature of Alias('kind', 'docforge.models.object.DocObject.kind')>",
|
|
"docstring": null
|
|
},
|
|
"path": {
|
|
"name": "path",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.DocObject.path",
|
|
"signature": "<bound method Alias.signature of Alias('path', 'docforge.models.object.DocObject.path')>",
|
|
"docstring": null
|
|
},
|
|
"signature": {
|
|
"name": "signature",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.DocObject.signature",
|
|
"signature": "<bound method Alias.signature of Alias('signature', 'docforge.models.object.DocObject.signature')>",
|
|
"docstring": null
|
|
},
|
|
"docstring": {
|
|
"name": "docstring",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.DocObject.docstring",
|
|
"signature": "<bound method Alias.signature of Alias('docstring', 'docforge.models.object.DocObject.docstring')>",
|
|
"docstring": null
|
|
},
|
|
"members": {
|
|
"name": "members",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.DocObject.members",
|
|
"signature": "<bound method Alias.signature of Alias('members', 'docforge.models.object.DocObject.members')>",
|
|
"docstring": null
|
|
},
|
|
"add_member": {
|
|
"name": "add_member",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.DocObject.add_member",
|
|
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
|
|
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member."
|
|
},
|
|
"get_member": {
|
|
"name": "get_member",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.DocObject.get_member",
|
|
"signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
|
|
"docstring": "Retrieve a member object by name.\n\nArgs:\n name (str):\n Name of the member to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If the member does not exist."
|
|
},
|
|
"get_all_members": {
|
|
"name": "get_all_members",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.DocObject.get_all_members",
|
|
"signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
|
|
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members."
|
|
}
|
|
}
|
|
},
|
|
"cli": {
|
|
"name": "cli",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.commands.cli",
|
|
"signature": null,
|
|
"docstring": null
|
|
},
|
|
"build": {
|
|
"name": "build",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.build",
|
|
"signature": "<bound method Function.signature of Function('build', 38, 260)>",
|
|
"docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds or serves the final output.\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites for library reference docs\n- Swagger-enabled API docs generated from an OpenAPI spec\n- Hand-written wiki pages included in the MkDocs site\n- MCP structured documentation resources\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` are combined into a single MkDocs\n build, while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs library documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Include a hand-written wiki directory in the MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
|
|
},
|
|
"serve": {
|
|
"name": "serve",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.serve",
|
|
"signature": "<bound method Function.signature of Function('serve', 263, 324)>",
|
|
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided."
|
|
},
|
|
"tree": {
|
|
"name": "tree",
|
|
"kind": "function",
|
|
"path": "docforge.cli.commands.tree",
|
|
"signature": "<bound method Function.signature of Function('tree', 327, 363)>",
|
|
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (str | None):\n Optional name to display as the project root."
|
|
},
|
|
"Group": {
|
|
"name": "Group",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.commands.Group",
|
|
"signature": "<bound method Alias.signature of Alias('Group', 'click.core.Group')>",
|
|
"docstring": null
|
|
}
|
|
}
|
|
}
|
|
} |