chore(release): 0.0.7
Squash-merge lib-standardisation: adopt repo standards across packaging, tooling, docs, and CI. - standardize pyproject.toml (canonical packaging, lint config, extras, GSDFC pydoclint) - add py.typed marker, modernize type hints and Google-style docstrings - nest generated docs under docs/lib and docs/mcp; add hand-written wiki - adopt standard Type A PyPI CI pipeline (tag==version guard + quality gate) - promote generated CHANGELOG.md; bump version to 0.0.7
This commit is contained in:
3
docs/lib/cli/api_utils.md
Normal file
3
docs/lib/cli/api_utils.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Api Utils
|
||||
|
||||
::: docforge.cli.api_utils
|
||||
3
docs/lib/nav/wiki.md
Normal file
3
docs/lib/nav/wiki.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Wiki
|
||||
|
||||
::: docforge.nav.wiki
|
||||
6
docs/mcp/index.json
Normal file
6
docs/mcp/index.json
Normal file
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"project": "docforge",
|
||||
"type": "docforge-model",
|
||||
"modules_count": 24,
|
||||
"source": "docforge"
|
||||
}
|
||||
67
docs/mcp/modules/docforge.cli.api_utils.json
Normal file
67
docs/mcp/modules/docforge.cli.api_utils.json
Normal file
@@ -0,0 +1,67 @@
|
||||
{
|
||||
"module": "docforge.cli.api_utils",
|
||||
"content": {
|
||||
"path": "docforge.cli.api_utils",
|
||||
"docstring": "# Summary\n\nUtilities for building API documentation from an OpenAPI specification.",
|
||||
"objects": {
|
||||
"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": "OpenAPIMetadata(site_name: str, site_description: str | None, site_author: str | None)",
|
||||
"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": "load_openapi_spec(spec_path: Path) -> dict[Any, Any]",
|
||||
"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.api_utils.derive_metadata",
|
||||
"signature": "derive_metadata(spec: dict[Any, Any]) -> OpenAPIMetadata",
|
||||
"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.api_utils.generate_api_sources",
|
||||
"signature": "generate_api_sources(spec: dict[Any, Any], docs_dir: Path) -> None",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
460
docs/mcp/modules/docforge.cli.commands.json
Normal file
460
docs/mcp/modules/docforge.cli.commands.json
Normal file
@@ -0,0 +1,460 @@
|
||||
{
|
||||
"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` each emit their own MkDocs config and\n build (`docs/mkdocs.{kind}.yml` into `site/{kind}`); `--mcp` generates a\n machine-readable bundle independently.\n\n---",
|
||||
"objects": {
|
||||
"api_utils": {
|
||||
"name": "api_utils",
|
||||
"kind": "module",
|
||||
"path": "docforge.cli.commands.api_utils",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nUtilities for building API documentation from an OpenAPI specification.",
|
||||
"members": {
|
||||
"SWAGGER_SPEC_FILENAME": {
|
||||
"name": "SWAGGER_SPEC_FILENAME",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.api_utils.SWAGGER_SPEC_FILENAME",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"OpenAPIMetadata": {
|
||||
"name": "OpenAPIMetadata",
|
||||
"kind": "class",
|
||||
"path": "docforge.cli.commands.api_utils.OpenAPIMetadata",
|
||||
"signature": "OpenAPIMetadata(site_name: str, site_description: str | None, site_author: str | None)",
|
||||
"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": null,
|
||||
"docstring": null
|
||||
},
|
||||
"site_description": {
|
||||
"name": "site_description",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.api_utils.OpenAPIMetadata.site_description",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"site_author": {
|
||||
"name": "site_author",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.api_utils.OpenAPIMetadata.site_author",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
}
|
||||
}
|
||||
},
|
||||
"load_openapi_spec": {
|
||||
"name": "load_openapi_spec",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.api_utils.load_openapi_spec",
|
||||
"signature": "load_openapi_spec(spec_path: Path)",
|
||||
"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": "derive_metadata(spec: dict[Any, Any])",
|
||||
"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": "generate_api_sources(spec: dict[Any, Any], docs_dir: Path)",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"mcp_utils": {
|
||||
"name": "mcp_utils",
|
||||
"kind": "module",
|
||||
"path": "docforge.cli.commands.mcp_utils",
|
||||
"signature": null,
|
||||
"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": {
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
"kind": "class",
|
||||
"path": "docforge.cli.commands.mcp_utils.GriffeLoader",
|
||||
"signature": "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": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None)",
|
||||
"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": "load_module(path: str)",
|
||||
"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": "discover_module_paths(module_name: str, project_root: Path | None = None)",
|
||||
"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": null,
|
||||
"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": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path)",
|
||||
"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": "MCPServer(mcp_root: Path, name: str)",
|
||||
"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": null,
|
||||
"docstring": null
|
||||
},
|
||||
"app": {
|
||||
"name": "app",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.mcp_utils.MCPServer.app",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"run": {
|
||||
"name": "run",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mcp_utils.MCPServer.run",
|
||||
"signature": "run(transport: Literal['stdio', 'sse', 'streamable-http'] = 'streamable-http')",
|
||||
"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": "generate_resources(module: str, project_name: str | None, out_dir: Path)",
|
||||
"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": "serve(module: str, mcp_root: Path)",
|
||||
"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": null,
|
||||
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A separate `mkdocs.{kind}.yml` configuration and build is emitted per\n enabled kind (lib, api, wiki), each scoped to its own `docs_dir` and\n written into its own `site_dir` (`site/lib`, `site/api`, `site/wiki`).\n - Navigation blocks are re-rooted per kind: the wiki navigation drops its\n leading `wiki/` scope and the resolved nav spec drops its `lib/` scope.\n\n---",
|
||||
"members": {
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
"kind": "class",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader",
|
||||
"signature": "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": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None)",
|
||||
"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": "load_module(path: str)",
|
||||
"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": "discover_module_paths(module_name: str, project_root: Path | None = None)",
|
||||
"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": null,
|
||||
"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": "emit(nav: ResolvedNav)",
|
||||
"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": "build_wiki_nav(wiki_dir: Path)",
|
||||
"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": "load_nav_spec(path: Path)",
|
||||
"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": "resolve_nav(spec: NavSpec, docs_root: Path)",
|
||||
"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": null,
|
||||
"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": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path, module_is_source: bool | None = None)",
|
||||
"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": "generate_readme(project: Project, docs_dir: Path, module_is_source: bool | None = None, readme_dir: Path | None = None)",
|
||||
"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": "generate_sources(module: str, docs_dir: Path, project_name: str | None = None, module_is_source: bool | None = None, readme_dir: Path | None = None)",
|
||||
"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``."
|
||||
},
|
||||
"build_lib_nav": {
|
||||
"name": "build_lib_nav",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build_lib_nav",
|
||||
"signature": "build_lib_nav(nav_file: Path, docs_root: Path)",
|
||||
"docstring": "Build the re-rooted navigation block for a lib site.\n\nThe navigation specification is resolved against the shared documentation\nroot and every resulting path is re-rooted relative to the ``lib``\nsubdirectory by stripping its leading ``lib/`` scope component.\n\nArgs:\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n docs_root (Path):\n Shared documentation root containing the ``lib`` sources.\n\nReturns:\n tuple[list[dict[str, Any]], dict[str, str] | None]:\n The re-rooted navigation block and the optional theme icon\n mapping from the specification.\n\nRaises:\n click.FileError:\n If the navigation specification cannot be found."
|
||||
},
|
||||
"build_wiki_nav_block": {
|
||||
"name": "build_wiki_nav_block",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build_wiki_nav_block",
|
||||
"signature": "build_wiki_nav_block(wiki_dir: Path)",
|
||||
"docstring": "Build the re-rooted navigation block for a wiki site.\n\nThe wiki navigation derived from the wiki file structure is re-rooted\nrelative to the wiki directory itself by stripping the leading ``wiki/``\nscope component.\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 relative to the wiki directory.\n\nRaises:\n click.FileError:\n If the wiki directory does not exist."
|
||||
},
|
||||
"load_spec_icon": {
|
||||
"name": "load_spec_icon",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.load_spec_icon",
|
||||
"signature": "load_spec_icon(nav_file: Path)",
|
||||
"docstring": "Load the theme icon mapping from a navigation specification.\n\nArgs:\n nav_file (Path):\n Path to the navigation specification file.\n\nReturns:\n dict[str, str] | None:\n The icon mapping, or ``None`` when the specification file is\n absent or cannot be parsed."
|
||||
},
|
||||
"generate_site_config": {
|
||||
"name": "generate_site_config",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.generate_site_config",
|
||||
"signature": "generate_site_config(kind: str, kind_root: Path, nav_block: list[dict[str, Any]], out: Path, site_name: str, docs_dir: str, site_dir: str, template: Path | None = None, site_description: str | None = None, site_author: str | None = None, theme_icon: dict[str, str] | None = None)",
|
||||
"docstring": "Generate a per-kind `mkdocs.{kind}.yml` configuration file.\n\nThe configuration is created by merging the shared ``mkdocs.common.yml``\ntemplate with the fragment contributed by the kind (``lib``, ``api``, or\n``wiki``). Both ``docs_dir`` and ``site_dir`` are written relative to the\nconfiguration file's directory: the kind's sources when expressed as a\nsibling path (for example ``lib``) and the per-kind site output (for\nexample ``../site/lib``).\n\nArgs:\n kind (str):\n Documentation kind, one of ``lib``, ``api``, or ``wiki``.\n\n kind_root (Path):\n Directory scoped to the kind (for example ``docs/lib``) that\n serves as the MkDocs ``docs_dir``.\n\n nav_block (list[dict[str, Any]]):\n Re-rooted navigation entries for the kind's site.\n\n out (Path):\n Destination path where the generated ``mkdocs.{kind}.yml`` file\n is written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n docs_dir (str):\n MkDocs ``docs_dir`` value, relative to the configuration\n file's directory.\n\n site_dir (str):\n MkDocs ``site_dir`` value, relative to the configuration\n file's directory.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template\n that replaces the built-in templates entirely.\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 theme_icon (dict[str, str] | None):\n Optional mapping of theme icon entries injected as\n ``theme.icon``."
|
||||
},
|
||||
"build_configs": {
|
||||
"name": "build_configs",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build_configs",
|
||||
"signature": "build_configs(yml_paths: Iterable[Path])",
|
||||
"docstring": "Build the MkDocs documentation site for every given configuration.\n\nEach configuration file is loaded and built in turn, producing the\nper-kind static sites (``site/lib``, ``site/api``, ``site/wiki``).\n\nArgs:\n yml_paths (Iterable[Path]):\n Configuration files to build, in order.\n\nRaises:\n click.ClickException:\n If a configuration file does not exist."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.serve",
|
||||
"signature": "serve(mkdocs_yml: Path)",
|
||||
"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": "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": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None)",
|
||||
"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": "load_module(path: str)",
|
||||
"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": "DocObject(name: str, kind: str, path: str, signature: str | None = None, docstring: str | None = None)",
|
||||
"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": null,
|
||||
"docstring": null
|
||||
},
|
||||
"kind": {
|
||||
"name": "kind",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.DocObject.kind",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.DocObject.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"signature": {
|
||||
"name": "signature",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.DocObject.signature",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.DocObject.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.DocObject.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_member": {
|
||||
"name": "add_member",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.DocObject.add_member",
|
||||
"signature": "add_member(obj: DocObject)",
|
||||
"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": "get_member(name: str)",
|
||||
"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": "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": "build(mcp: bool, mkdocs: bool, api: bool, wiki: bool, refresh: bool, module_is_source: bool, module: str | None, openapi_spec: Path | None, project_name: str | None, site_name: str | None, docs_dir: Path, wiki_dir: Path, nav_file: Path, template: Path | None, out_dir: Path) -> None",
|
||||
"docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n - Configuration files are generated only when absent; an existing\n `docs/mkdocs.{kind}.yml` is used as-is. Pass `--refresh` to\n rebaseline it from the templates.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n refresh (bool):\n Regenerate ``docs/mkdocs.{kind}.yml`` from templates even when\n it already exists. By default, existing configs are used as-is.\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 lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\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 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": "serve(mcp: bool, mkdocs: bool, lib: bool, api: bool, wiki: bool, module: str | None, mkdocs_yml: Path, out_dir: Path) -> None",
|
||||
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing a site, or\n- An MCP server exposing structured documentation resources\n\nThe kind flags (`--lib`, `--api`, `--wiki`) select the generated\nper-kind config (`docs/mkdocs.{kind}.yml`); `--mkdocs` serves the config\npassed via `--mkdocs-yml`.\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site from ``--mkdocs-yml``.\n\n lib (bool):\n Serve the lib MkDocs site.\n\n api (bool):\n Serve the API MkDocs site.\n\n wiki (bool):\n Serve the wiki MkDocs 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": "tree(module: str, project_name: str | None) -> None",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
820
docs/mcp/modules/docforge.cli.json
Normal file
820
docs/mcp/modules/docforge.cli.json
Normal file
@@ -0,0 +1,820 @@
|
||||
{
|
||||
"module": "docforge.cli",
|
||||
"content": {
|
||||
"path": "docforge.cli",
|
||||
"docstring": "# Summary\n\nCommand line interface entry point for doc-forge.\n\nThis module exposes the primary CLI entry function used by the\n`doc-forge` command. The actual command implementation resides in\n`docforge.cli.main`, while this module provides a stable import path\nfor external tools and the package entry point configuration.\n\nThe CLI is responsible for orchestrating documentation workflows such as\ngenerating renderer sources, building documentation sites, exporting\nmachine-readable documentation bundles, and starting development or MCP\nservers.\n\n---\n\n# Typical usage\n\nThe CLI is normally invoked through the installed command:\n\n```bash\ndoc-forge <command> [options]\n```\n\nProgrammatic invocation is also possible:\n\nExample:\n\n ```python\n from docforge.cli import main\n main()\n ```\n\n---",
|
||||
"objects": {
|
||||
"main": {
|
||||
"name": "main",
|
||||
"kind": "module",
|
||||
"path": "docforge.cli.main",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nCommand-line entry point for the doc-forge CLI.\n\nThis module exposes the executable entry point that initializes the\nClick command group defined in `docforge.cli.commands`.",
|
||||
"members": {
|
||||
"cli": {
|
||||
"name": "cli",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.main.cli",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"main": {
|
||||
"name": "main",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.main.main",
|
||||
"signature": "main() -> None",
|
||||
"docstring": "Run the doc-forge command-line interface.\n\nThis function initializes and executes the Click CLI application.\nIt is used as the console entry point when invoking `doc-forge`\nfrom the command line."
|
||||
}
|
||||
}
|
||||
},
|
||||
"api_utils": {
|
||||
"name": "api_utils",
|
||||
"kind": "module",
|
||||
"path": "docforge.cli.api_utils",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nUtilities for building API documentation from an OpenAPI specification.",
|
||||
"members": {
|
||||
"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": "OpenAPIMetadata(site_name: str, site_description: str | None, site_author: str | None)",
|
||||
"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": "load_openapi_spec(spec_path: Path) -> dict[Any, Any]",
|
||||
"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.api_utils.derive_metadata",
|
||||
"signature": "derive_metadata(spec: dict[Any, Any]) -> OpenAPIMetadata",
|
||||
"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.api_utils.generate_api_sources",
|
||||
"signature": "generate_api_sources(spec: dict[Any, Any], docs_dir: Path) -> None",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"commands": {
|
||||
"name": "commands",
|
||||
"kind": "module",
|
||||
"path": "docforge.cli.commands",
|
||||
"signature": null,
|
||||
"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` each emit their own MkDocs config and\n build (`docs/mkdocs.{kind}.yml` into `site/{kind}`); `--mcp` generates a\n machine-readable bundle independently.\n\n---",
|
||||
"members": {
|
||||
"api_utils": {
|
||||
"name": "api_utils",
|
||||
"kind": "module",
|
||||
"path": "docforge.cli.commands.api_utils",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nUtilities for building API documentation from an OpenAPI specification.",
|
||||
"members": {
|
||||
"SWAGGER_SPEC_FILENAME": {
|
||||
"name": "SWAGGER_SPEC_FILENAME",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.api_utils.SWAGGER_SPEC_FILENAME",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"OpenAPIMetadata": {
|
||||
"name": "OpenAPIMetadata",
|
||||
"kind": "class",
|
||||
"path": "docforge.cli.commands.api_utils.OpenAPIMetadata",
|
||||
"signature": "OpenAPIMetadata(site_name: str, site_description: str | None, site_author: str | None)",
|
||||
"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": null,
|
||||
"docstring": null
|
||||
},
|
||||
"site_description": {
|
||||
"name": "site_description",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.api_utils.OpenAPIMetadata.site_description",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"site_author": {
|
||||
"name": "site_author",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.api_utils.OpenAPIMetadata.site_author",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
}
|
||||
}
|
||||
},
|
||||
"load_openapi_spec": {
|
||||
"name": "load_openapi_spec",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.api_utils.load_openapi_spec",
|
||||
"signature": "load_openapi_spec(spec_path: Path)",
|
||||
"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": "derive_metadata(spec: dict[Any, Any])",
|
||||
"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": "generate_api_sources(spec: dict[Any, Any], docs_dir: Path)",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"mcp_utils": {
|
||||
"name": "mcp_utils",
|
||||
"kind": "module",
|
||||
"path": "docforge.cli.commands.mcp_utils",
|
||||
"signature": null,
|
||||
"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": {
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
"kind": "class",
|
||||
"path": "docforge.cli.commands.mcp_utils.GriffeLoader",
|
||||
"signature": "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": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None)",
|
||||
"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": "load_module(path: str)",
|
||||
"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": "discover_module_paths(module_name: str, project_root: Path | None = None)",
|
||||
"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": null,
|
||||
"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": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path)",
|
||||
"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": "MCPServer(mcp_root: Path, name: str)",
|
||||
"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": null,
|
||||
"docstring": null
|
||||
},
|
||||
"app": {
|
||||
"name": "app",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.mcp_utils.MCPServer.app",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"run": {
|
||||
"name": "run",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mcp_utils.MCPServer.run",
|
||||
"signature": "run(transport: Literal['stdio', 'sse', 'streamable-http'] = 'streamable-http')",
|
||||
"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": "generate_resources(module: str, project_name: str | None, out_dir: Path)",
|
||||
"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": "serve(module: str, mcp_root: Path)",
|
||||
"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": null,
|
||||
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A separate `mkdocs.{kind}.yml` configuration and build is emitted per\n enabled kind (lib, api, wiki), each scoped to its own `docs_dir` and\n written into its own `site_dir` (`site/lib`, `site/api`, `site/wiki`).\n - Navigation blocks are re-rooted per kind: the wiki navigation drops its\n leading `wiki/` scope and the resolved nav spec drops its `lib/` scope.\n\n---",
|
||||
"members": {
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
"kind": "class",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader",
|
||||
"signature": "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": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None)",
|
||||
"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": "load_module(path: str)",
|
||||
"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": "discover_module_paths(module_name: str, project_root: Path | None = None)",
|
||||
"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": null,
|
||||
"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": "emit(nav: ResolvedNav)",
|
||||
"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": "build_wiki_nav(wiki_dir: Path)",
|
||||
"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": "load_nav_spec(path: Path)",
|
||||
"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": "resolve_nav(spec: NavSpec, docs_root: Path)",
|
||||
"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": null,
|
||||
"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": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path, module_is_source: bool | None = None)",
|
||||
"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": "generate_readme(project: Project, docs_dir: Path, module_is_source: bool | None = None, readme_dir: Path | None = None)",
|
||||
"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": "generate_sources(module: str, docs_dir: Path, project_name: str | None = None, module_is_source: bool | None = None, readme_dir: Path | None = None)",
|
||||
"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``."
|
||||
},
|
||||
"build_lib_nav": {
|
||||
"name": "build_lib_nav",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build_lib_nav",
|
||||
"signature": "build_lib_nav(nav_file: Path, docs_root: Path)",
|
||||
"docstring": "Build the re-rooted navigation block for a lib site.\n\nThe navigation specification is resolved against the shared documentation\nroot and every resulting path is re-rooted relative to the ``lib``\nsubdirectory by stripping its leading ``lib/`` scope component.\n\nArgs:\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n docs_root (Path):\n Shared documentation root containing the ``lib`` sources.\n\nReturns:\n tuple[list[dict[str, Any]], dict[str, str] | None]:\n The re-rooted navigation block and the optional theme icon\n mapping from the specification.\n\nRaises:\n click.FileError:\n If the navigation specification cannot be found."
|
||||
},
|
||||
"build_wiki_nav_block": {
|
||||
"name": "build_wiki_nav_block",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build_wiki_nav_block",
|
||||
"signature": "build_wiki_nav_block(wiki_dir: Path)",
|
||||
"docstring": "Build the re-rooted navigation block for a wiki site.\n\nThe wiki navigation derived from the wiki file structure is re-rooted\nrelative to the wiki directory itself by stripping the leading ``wiki/``\nscope component.\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 relative to the wiki directory.\n\nRaises:\n click.FileError:\n If the wiki directory does not exist."
|
||||
},
|
||||
"load_spec_icon": {
|
||||
"name": "load_spec_icon",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.load_spec_icon",
|
||||
"signature": "load_spec_icon(nav_file: Path)",
|
||||
"docstring": "Load the theme icon mapping from a navigation specification.\n\nArgs:\n nav_file (Path):\n Path to the navigation specification file.\n\nReturns:\n dict[str, str] | None:\n The icon mapping, or ``None`` when the specification file is\n absent or cannot be parsed."
|
||||
},
|
||||
"generate_site_config": {
|
||||
"name": "generate_site_config",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.generate_site_config",
|
||||
"signature": "generate_site_config(kind: str, kind_root: Path, nav_block: list[dict[str, Any]], out: Path, site_name: str, docs_dir: str, site_dir: str, template: Path | None = None, site_description: str | None = None, site_author: str | None = None, theme_icon: dict[str, str] | None = None)",
|
||||
"docstring": "Generate a per-kind `mkdocs.{kind}.yml` configuration file.\n\nThe configuration is created by merging the shared ``mkdocs.common.yml``\ntemplate with the fragment contributed by the kind (``lib``, ``api``, or\n``wiki``). Both ``docs_dir`` and ``site_dir`` are written relative to the\nconfiguration file's directory: the kind's sources when expressed as a\nsibling path (for example ``lib``) and the per-kind site output (for\nexample ``../site/lib``).\n\nArgs:\n kind (str):\n Documentation kind, one of ``lib``, ``api``, or ``wiki``.\n\n kind_root (Path):\n Directory scoped to the kind (for example ``docs/lib``) that\n serves as the MkDocs ``docs_dir``.\n\n nav_block (list[dict[str, Any]]):\n Re-rooted navigation entries for the kind's site.\n\n out (Path):\n Destination path where the generated ``mkdocs.{kind}.yml`` file\n is written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n docs_dir (str):\n MkDocs ``docs_dir`` value, relative to the configuration\n file's directory.\n\n site_dir (str):\n MkDocs ``site_dir`` value, relative to the configuration\n file's directory.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template\n that replaces the built-in templates entirely.\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 theme_icon (dict[str, str] | None):\n Optional mapping of theme icon entries injected as\n ``theme.icon``."
|
||||
},
|
||||
"build_configs": {
|
||||
"name": "build_configs",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build_configs",
|
||||
"signature": "build_configs(yml_paths: Iterable[Path])",
|
||||
"docstring": "Build the MkDocs documentation site for every given configuration.\n\nEach configuration file is loaded and built in turn, producing the\nper-kind static sites (``site/lib``, ``site/api``, ``site/wiki``).\n\nArgs:\n yml_paths (Iterable[Path]):\n Configuration files to build, in order.\n\nRaises:\n click.ClickException:\n If a configuration file does not exist."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.serve",
|
||||
"signature": "serve(mkdocs_yml: Path)",
|
||||
"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": "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": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None)",
|
||||
"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": "load_module(path: str)",
|
||||
"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": "DocObject(name: str, kind: str, path: str, signature: str | None = None, docstring: str | None = None)",
|
||||
"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": null,
|
||||
"docstring": null
|
||||
},
|
||||
"kind": {
|
||||
"name": "kind",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.DocObject.kind",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.DocObject.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"signature": {
|
||||
"name": "signature",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.DocObject.signature",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.DocObject.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.commands.DocObject.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_member": {
|
||||
"name": "add_member",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.DocObject.add_member",
|
||||
"signature": "add_member(obj: DocObject)",
|
||||
"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": "get_member(name: str)",
|
||||
"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": "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": "build(mcp: bool, mkdocs: bool, api: bool, wiki: bool, refresh: bool, module_is_source: bool, module: str | None, openapi_spec: Path | None, project_name: str | None, site_name: str | None, docs_dir: Path, wiki_dir: Path, nav_file: Path, template: Path | None, out_dir: Path) -> None",
|
||||
"docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n - Configuration files are generated only when absent; an existing\n `docs/mkdocs.{kind}.yml` is used as-is. Pass `--refresh` to\n rebaseline it from the templates.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n refresh (bool):\n Regenerate ``docs/mkdocs.{kind}.yml`` from templates even when\n it already exists. By default, existing configs are used as-is.\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 lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\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 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": "serve(mcp: bool, mkdocs: bool, lib: bool, api: bool, wiki: bool, module: str | None, mkdocs_yml: Path, out_dir: Path) -> None",
|
||||
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing a site, or\n- An MCP server exposing structured documentation resources\n\nThe kind flags (`--lib`, `--api`, `--wiki`) select the generated\nper-kind config (`docs/mkdocs.{kind}.yml`); `--mkdocs` serves the config\npassed via `--mkdocs-yml`.\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site from ``--mkdocs-yml``.\n\n lib (bool):\n Serve the lib MkDocs site.\n\n api (bool):\n Serve the API MkDocs site.\n\n wiki (bool):\n Serve the wiki MkDocs 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": "tree(module: str, project_name: str | None) -> None",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"mcp_utils": {
|
||||
"name": "mcp_utils",
|
||||
"kind": "module",
|
||||
"path": "docforge.cli.mcp_utils",
|
||||
"signature": null,
|
||||
"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": {
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
"kind": "class",
|
||||
"path": "docforge.cli.mcp_utils.GriffeLoader",
|
||||
"signature": "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.mcp_utils.GriffeLoader.load_project",
|
||||
"signature": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None)",
|
||||
"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.mcp_utils.GriffeLoader.load_module",
|
||||
"signature": "load_module(path: str)",
|
||||
"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.mcp_utils.discover_module_paths",
|
||||
"signature": "discover_module_paths(module_name: str, project_root: Path | None = None)",
|
||||
"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.mcp_utils.MCPRenderer",
|
||||
"signature": null,
|
||||
"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.mcp_utils.MCPRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path)",
|
||||
"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.mcp_utils.MCPServer",
|
||||
"signature": "MCPServer(mcp_root: Path, name: str)",
|
||||
"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.mcp_utils.MCPServer.mcp_root",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"app": {
|
||||
"name": "app",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.mcp_utils.MCPServer.app",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"run": {
|
||||
"name": "run",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mcp_utils.MCPServer.run",
|
||||
"signature": "run(transport: Literal['stdio', 'sse', 'streamable-http'] = 'streamable-http')",
|
||||
"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.mcp_utils.generate_resources",
|
||||
"signature": "generate_resources(module: str, project_name: str | None, out_dir: Path) -> None",
|
||||
"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.mcp_utils.serve",
|
||||
"signature": "serve(module: str, mcp_root: Path) -> None",
|
||||
"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.mkdocs_utils",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A separate `mkdocs.{kind}.yml` configuration and build is emitted per\n enabled kind (lib, api, wiki), each scoped to its own `docs_dir` and\n written into its own `site_dir` (`site/lib`, `site/api`, `site/wiki`).\n - Navigation blocks are re-rooted per kind: the wiki navigation drops its\n leading `wiki/` scope and the resolved nav spec drops its `lib/` scope.\n\n---",
|
||||
"members": {
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
"kind": "class",
|
||||
"path": "docforge.cli.mkdocs_utils.GriffeLoader",
|
||||
"signature": "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.mkdocs_utils.GriffeLoader.load_project",
|
||||
"signature": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None)",
|
||||
"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.mkdocs_utils.GriffeLoader.load_module",
|
||||
"signature": "load_module(path: str)",
|
||||
"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.mkdocs_utils.discover_module_paths",
|
||||
"signature": "discover_module_paths(module_name: str, project_root: Path | None = None)",
|
||||
"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.mkdocs_utils.MkDocsNavEmitter",
|
||||
"signature": null,
|
||||
"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.mkdocs_utils.MkDocsNavEmitter.emit",
|
||||
"signature": "emit(nav: ResolvedNav)",
|
||||
"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.mkdocs_utils.build_wiki_nav",
|
||||
"signature": "build_wiki_nav(wiki_dir: Path)",
|
||||
"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.mkdocs_utils.load_nav_spec",
|
||||
"signature": "load_nav_spec(path: Path)",
|
||||
"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.mkdocs_utils.resolve_nav",
|
||||
"signature": "resolve_nav(spec: NavSpec, docs_root: Path)",
|
||||
"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.mkdocs_utils.MkDocsRenderer",
|
||||
"signature": null,
|
||||
"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.mkdocs_utils.MkDocsRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path, module_is_source: bool | None = None)",
|
||||
"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.mkdocs_utils.MkDocsRenderer.generate_readme",
|
||||
"signature": "generate_readme(project: Project, docs_dir: Path, module_is_source: bool | None = None, readme_dir: Path | None = None)",
|
||||
"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.mkdocs_utils.generate_sources",
|
||||
"signature": "generate_sources(module: str, docs_dir: Path, project_name: str | None = None, module_is_source: bool | None = None, readme_dir: Path | None = None) -> None",
|
||||
"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``."
|
||||
},
|
||||
"build_lib_nav": {
|
||||
"name": "build_lib_nav",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.build_lib_nav",
|
||||
"signature": "build_lib_nav(nav_file: Path, docs_root: Path) -> tuple[list[dict[str, Any]], dict[str, str] | None]",
|
||||
"docstring": "Build the re-rooted navigation block for a lib site.\n\nThe navigation specification is resolved against the shared documentation\nroot and every resulting path is re-rooted relative to the ``lib``\nsubdirectory by stripping its leading ``lib/`` scope component.\n\nArgs:\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n docs_root (Path):\n Shared documentation root containing the ``lib`` sources.\n\nReturns:\n tuple[list[dict[str, Any]], dict[str, str] | None]:\n The re-rooted navigation block and the optional theme icon\n mapping from the specification.\n\nRaises:\n click.FileError:\n If the navigation specification cannot be found."
|
||||
},
|
||||
"build_wiki_nav_block": {
|
||||
"name": "build_wiki_nav_block",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.build_wiki_nav_block",
|
||||
"signature": "build_wiki_nav_block(wiki_dir: Path) -> list[dict[str, Any]]",
|
||||
"docstring": "Build the re-rooted navigation block for a wiki site.\n\nThe wiki navigation derived from the wiki file structure is re-rooted\nrelative to the wiki directory itself by stripping the leading ``wiki/``\nscope component.\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 relative to the wiki directory.\n\nRaises:\n click.FileError:\n If the wiki directory does not exist."
|
||||
},
|
||||
"load_spec_icon": {
|
||||
"name": "load_spec_icon",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.load_spec_icon",
|
||||
"signature": "load_spec_icon(nav_file: Path) -> dict[str, str] | None",
|
||||
"docstring": "Load the theme icon mapping from a navigation specification.\n\nArgs:\n nav_file (Path):\n Path to the navigation specification file.\n\nReturns:\n dict[str, str] | None:\n The icon mapping, or ``None`` when the specification file is\n absent or cannot be parsed."
|
||||
},
|
||||
"generate_site_config": {
|
||||
"name": "generate_site_config",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.generate_site_config",
|
||||
"signature": "generate_site_config(kind: str, kind_root: Path, nav_block: list[dict[str, Any]], out: Path, site_name: str, docs_dir: str, site_dir: str, template: Path | None = None, site_description: str | None = None, site_author: str | None = None, theme_icon: dict[str, str] | None = None) -> None",
|
||||
"docstring": "Generate a per-kind `mkdocs.{kind}.yml` configuration file.\n\nThe configuration is created by merging the shared ``mkdocs.common.yml``\ntemplate with the fragment contributed by the kind (``lib``, ``api``, or\n``wiki``). Both ``docs_dir`` and ``site_dir`` are written relative to the\nconfiguration file's directory: the kind's sources when expressed as a\nsibling path (for example ``lib``) and the per-kind site output (for\nexample ``../site/lib``).\n\nArgs:\n kind (str):\n Documentation kind, one of ``lib``, ``api``, or ``wiki``.\n\n kind_root (Path):\n Directory scoped to the kind (for example ``docs/lib``) that\n serves as the MkDocs ``docs_dir``.\n\n nav_block (list[dict[str, Any]]):\n Re-rooted navigation entries for the kind's site.\n\n out (Path):\n Destination path where the generated ``mkdocs.{kind}.yml`` file\n is written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n docs_dir (str):\n MkDocs ``docs_dir`` value, relative to the configuration\n file's directory.\n\n site_dir (str):\n MkDocs ``site_dir`` value, relative to the configuration\n file's directory.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template\n that replaces the built-in templates entirely.\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 theme_icon (dict[str, str] | None):\n Optional mapping of theme icon entries injected as\n ``theme.icon``."
|
||||
},
|
||||
"build_configs": {
|
||||
"name": "build_configs",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.build_configs",
|
||||
"signature": "build_configs(yml_paths: Iterable[Path]) -> None",
|
||||
"docstring": "Build the MkDocs documentation site for every given configuration.\n\nEach configuration file is loaded and built in turn, producing the\nper-kind static sites (``site/lib``, ``site/api``, ``site/wiki``).\n\nArgs:\n yml_paths (Iterable[Path]):\n Configuration files to build, in order.\n\nRaises:\n click.ClickException:\n If a configuration file does not exist."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.serve",
|
||||
"signature": "serve(mkdocs_yml: Path) -> None",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
23
docs/mcp/modules/docforge.cli.main.json
Normal file
23
docs/mcp/modules/docforge.cli.main.json
Normal file
@@ -0,0 +1,23 @@
|
||||
{
|
||||
"module": "docforge.cli.main",
|
||||
"content": {
|
||||
"path": "docforge.cli.main",
|
||||
"docstring": "# Summary\n\nCommand-line entry point for the doc-forge CLI.\n\nThis module exposes the executable entry point that initializes the\nClick command group defined in `docforge.cli.commands`.",
|
||||
"objects": {
|
||||
"cli": {
|
||||
"name": "cli",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.main.cli",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"main": {
|
||||
"name": "main",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.main.main",
|
||||
"signature": "main() -> None",
|
||||
"docstring": "Run the doc-forge command-line interface.\n\nThis function initializes and executes the Click CLI application.\nIt is used as the console entry point when invoking `doc-forge`\nfrom the command line."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
106
docs/mcp/modules/docforge.cli.mcp_utils.json
Normal file
106
docs/mcp/modules/docforge.cli.mcp_utils.json
Normal file
@@ -0,0 +1,106 @@
|
||||
{
|
||||
"module": "docforge.cli.mcp_utils",
|
||||
"content": {
|
||||
"path": "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---",
|
||||
"objects": {
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
"kind": "class",
|
||||
"path": "docforge.cli.mcp_utils.GriffeLoader",
|
||||
"signature": "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.mcp_utils.GriffeLoader.load_project",
|
||||
"signature": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None)",
|
||||
"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.mcp_utils.GriffeLoader.load_module",
|
||||
"signature": "load_module(path: str)",
|
||||
"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.mcp_utils.discover_module_paths",
|
||||
"signature": "discover_module_paths(module_name: str, project_root: Path | None = None)",
|
||||
"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.mcp_utils.MCPRenderer",
|
||||
"signature": null,
|
||||
"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.mcp_utils.MCPRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path)",
|
||||
"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.mcp_utils.MCPServer",
|
||||
"signature": "MCPServer(mcp_root: Path, name: str)",
|
||||
"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.mcp_utils.MCPServer.mcp_root",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"app": {
|
||||
"name": "app",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.cli.mcp_utils.MCPServer.app",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"run": {
|
||||
"name": "run",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mcp_utils.MCPServer.run",
|
||||
"signature": "run(transport: Literal['stdio', 'sse', 'streamable-http'] = 'streamable-http')",
|
||||
"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.mcp_utils.generate_resources",
|
||||
"signature": "generate_resources(module: str, project_name: str | None, out_dir: Path) -> None",
|
||||
"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.mcp_utils.serve",
|
||||
"signature": "serve(module: str, mcp_root: Path) -> None",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
155
docs/mcp/modules/docforge.cli.mkdocs_utils.json
Normal file
155
docs/mcp/modules/docforge.cli.mkdocs_utils.json
Normal file
@@ -0,0 +1,155 @@
|
||||
{
|
||||
"module": "docforge.cli.mkdocs_utils",
|
||||
"content": {
|
||||
"path": "docforge.cli.mkdocs_utils",
|
||||
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A separate `mkdocs.{kind}.yml` configuration and build is emitted per\n enabled kind (lib, api, wiki), each scoped to its own `docs_dir` and\n written into its own `site_dir` (`site/lib`, `site/api`, `site/wiki`).\n - Navigation blocks are re-rooted per kind: the wiki navigation drops its\n leading `wiki/` scope and the resolved nav spec drops its `lib/` scope.\n\n---",
|
||||
"objects": {
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
"kind": "class",
|
||||
"path": "docforge.cli.mkdocs_utils.GriffeLoader",
|
||||
"signature": "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.mkdocs_utils.GriffeLoader.load_project",
|
||||
"signature": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None)",
|
||||
"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.mkdocs_utils.GriffeLoader.load_module",
|
||||
"signature": "load_module(path: str)",
|
||||
"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.mkdocs_utils.discover_module_paths",
|
||||
"signature": "discover_module_paths(module_name: str, project_root: Path | None = None)",
|
||||
"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.mkdocs_utils.MkDocsNavEmitter",
|
||||
"signature": null,
|
||||
"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.mkdocs_utils.MkDocsNavEmitter.emit",
|
||||
"signature": "emit(nav: ResolvedNav)",
|
||||
"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.mkdocs_utils.build_wiki_nav",
|
||||
"signature": "build_wiki_nav(wiki_dir: Path)",
|
||||
"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.mkdocs_utils.load_nav_spec",
|
||||
"signature": "load_nav_spec(path: Path)",
|
||||
"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.mkdocs_utils.resolve_nav",
|
||||
"signature": "resolve_nav(spec: NavSpec, docs_root: Path)",
|
||||
"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.mkdocs_utils.MkDocsRenderer",
|
||||
"signature": null,
|
||||
"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.mkdocs_utils.MkDocsRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path, module_is_source: bool | None = None)",
|
||||
"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.mkdocs_utils.MkDocsRenderer.generate_readme",
|
||||
"signature": "generate_readme(project: Project, docs_dir: Path, module_is_source: bool | None = None, readme_dir: Path | None = None)",
|
||||
"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.mkdocs_utils.generate_sources",
|
||||
"signature": "generate_sources(module: str, docs_dir: Path, project_name: str | None = None, module_is_source: bool | None = None, readme_dir: Path | None = None) -> None",
|
||||
"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``."
|
||||
},
|
||||
"build_lib_nav": {
|
||||
"name": "build_lib_nav",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.build_lib_nav",
|
||||
"signature": "build_lib_nav(nav_file: Path, docs_root: Path) -> tuple[list[dict[str, Any]], dict[str, str] | None]",
|
||||
"docstring": "Build the re-rooted navigation block for a lib site.\n\nThe navigation specification is resolved against the shared documentation\nroot and every resulting path is re-rooted relative to the ``lib``\nsubdirectory by stripping its leading ``lib/`` scope component.\n\nArgs:\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n docs_root (Path):\n Shared documentation root containing the ``lib`` sources.\n\nReturns:\n tuple[list[dict[str, Any]], dict[str, str] | None]:\n The re-rooted navigation block and the optional theme icon\n mapping from the specification.\n\nRaises:\n click.FileError:\n If the navigation specification cannot be found."
|
||||
},
|
||||
"build_wiki_nav_block": {
|
||||
"name": "build_wiki_nav_block",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.build_wiki_nav_block",
|
||||
"signature": "build_wiki_nav_block(wiki_dir: Path) -> list[dict[str, Any]]",
|
||||
"docstring": "Build the re-rooted navigation block for a wiki site.\n\nThe wiki navigation derived from the wiki file structure is re-rooted\nrelative to the wiki directory itself by stripping the leading ``wiki/``\nscope component.\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 relative to the wiki directory.\n\nRaises:\n click.FileError:\n If the wiki directory does not exist."
|
||||
},
|
||||
"load_spec_icon": {
|
||||
"name": "load_spec_icon",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.load_spec_icon",
|
||||
"signature": "load_spec_icon(nav_file: Path) -> dict[str, str] | None",
|
||||
"docstring": "Load the theme icon mapping from a navigation specification.\n\nArgs:\n nav_file (Path):\n Path to the navigation specification file.\n\nReturns:\n dict[str, str] | None:\n The icon mapping, or ``None`` when the specification file is\n absent or cannot be parsed."
|
||||
},
|
||||
"generate_site_config": {
|
||||
"name": "generate_site_config",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.generate_site_config",
|
||||
"signature": "generate_site_config(kind: str, kind_root: Path, nav_block: list[dict[str, Any]], out: Path, site_name: str, docs_dir: str, site_dir: str, template: Path | None = None, site_description: str | None = None, site_author: str | None = None, theme_icon: dict[str, str] | None = None) -> None",
|
||||
"docstring": "Generate a per-kind `mkdocs.{kind}.yml` configuration file.\n\nThe configuration is created by merging the shared ``mkdocs.common.yml``\ntemplate with the fragment contributed by the kind (``lib``, ``api``, or\n``wiki``). Both ``docs_dir`` and ``site_dir`` are written relative to the\nconfiguration file's directory: the kind's sources when expressed as a\nsibling path (for example ``lib``) and the per-kind site output (for\nexample ``../site/lib``).\n\nArgs:\n kind (str):\n Documentation kind, one of ``lib``, ``api``, or ``wiki``.\n\n kind_root (Path):\n Directory scoped to the kind (for example ``docs/lib``) that\n serves as the MkDocs ``docs_dir``.\n\n nav_block (list[dict[str, Any]]):\n Re-rooted navigation entries for the kind's site.\n\n out (Path):\n Destination path where the generated ``mkdocs.{kind}.yml`` file\n is written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n docs_dir (str):\n MkDocs ``docs_dir`` value, relative to the configuration\n file's directory.\n\n site_dir (str):\n MkDocs ``site_dir`` value, relative to the configuration\n file's directory.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template\n that replaces the built-in templates entirely.\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 theme_icon (dict[str, str] | None):\n Optional mapping of theme icon entries injected as\n ``theme.icon``."
|
||||
},
|
||||
"build_configs": {
|
||||
"name": "build_configs",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.build_configs",
|
||||
"signature": "build_configs(yml_paths: Iterable[Path]) -> None",
|
||||
"docstring": "Build the MkDocs documentation site for every given configuration.\n\nEach configuration file is loaded and built in turn, producing the\nper-kind static sites (``site/lib``, ``site/api``, ``site/wiki``).\n\nArgs:\n yml_paths (Iterable[Path]):\n Configuration files to build, in order.\n\nRaises:\n click.ClickException:\n If a configuration file does not exist."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.serve",
|
||||
"signature": "serve(mkdocs_yml: Path) -> None",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
2635
docs/mcp/modules/docforge.json
Normal file
2635
docs/mcp/modules/docforge.json
Normal file
File diff suppressed because one or more lines are too long
220
docs/mcp/modules/docforge.loaders.griffe_loader.json
Normal file
220
docs/mcp/modules/docforge.loaders.griffe_loader.json
Normal file
@@ -0,0 +1,220 @@
|
||||
{
|
||||
"module": "docforge.loaders.griffe_loader",
|
||||
"content": {
|
||||
"path": "docforge.loaders.griffe_loader",
|
||||
"docstring": "# Summary\n\nUtilities for loading and introspecting Python modules using Griffe.\n\nThis module provides the `GriffeLoader` class and helper utilities used to\ndiscover Python modules, introspect their structure, and convert the results\ninto doc-forge documentation models.\n\n---\n\nNotes:\n - All analysis is static; analyzed modules are never executed.\n - Private members (names starting with `_`) are skipped during conversion.\n - Imported aliases that cannot be resolved (stdlib/third-party names) are\n skipped; aliases that resolve within the documented project are kept.\n\n---",
|
||||
"objects": {
|
||||
"DocObject": {
|
||||
"name": "DocObject",
|
||||
"kind": "class",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject",
|
||||
"signature": "DocObject(name: str, kind: str, path: str, signature: str | None = None, docstring: str | None = None)",
|
||||
"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.loaders.griffe_loader.DocObject.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"kind": {
|
||||
"name": "kind",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject.kind",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"signature": {
|
||||
"name": "signature",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject.signature",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_member": {
|
||||
"name": "add_member",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject.add_member",
|
||||
"signature": "add_member(obj: DocObject)",
|
||||
"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.loaders.griffe_loader.DocObject.get_member",
|
||||
"signature": "get_member(name: str)",
|
||||
"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.loaders.griffe_loader.DocObject.get_all_members",
|
||||
"signature": "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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Module": {
|
||||
"name": "Module",
|
||||
"kind": "class",
|
||||
"path": "docforge.loaders.griffe_loader.Module",
|
||||
"signature": "Module(path: str, docstring: str | None = None)",
|
||||
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
|
||||
"members": {
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.Module.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.Module.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.Module.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_object": {
|
||||
"name": "add_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Module.add_object",
|
||||
"signature": "add_object(obj: DocObject)",
|
||||
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module."
|
||||
},
|
||||
"get_object": {
|
||||
"name": "get_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Module.get_object",
|
||||
"signature": "get_object(name: str)",
|
||||
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists."
|
||||
},
|
||||
"get_all_objects": {
|
||||
"name": "get_all_objects",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Module.get_all_objects",
|
||||
"signature": "get_all_objects()",
|
||||
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Project": {
|
||||
"name": "Project",
|
||||
"kind": "class",
|
||||
"path": "docforge.loaders.griffe_loader.Project",
|
||||
"signature": "Project(name: str)",
|
||||
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (dict[str, Module]):\n Mapping of module paths to `Module` instances.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.Project.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"modules": {
|
||||
"name": "modules",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.Project.modules",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_module": {
|
||||
"name": "add_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Project.add_module",
|
||||
"signature": "add_module(module: Module)",
|
||||
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
|
||||
},
|
||||
"get_module": {
|
||||
"name": "get_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Project.get_module",
|
||||
"signature": "get_module(path: str)",
|
||||
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project."
|
||||
},
|
||||
"get_all_modules": {
|
||||
"name": "get_all_modules",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Project.get_all_modules",
|
||||
"signature": "get_all_modules()",
|
||||
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
|
||||
},
|
||||
"get_module_list": {
|
||||
"name": "get_module_list",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Project.get_module_list",
|
||||
"signature": "get_module_list()",
|
||||
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project."
|
||||
}
|
||||
}
|
||||
},
|
||||
"logger": {
|
||||
"name": "logger",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.logger",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"discover_module_paths": {
|
||||
"name": "discover_module_paths",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.discover_module_paths",
|
||||
"signature": "discover_module_paths(module_name: str, project_root: Path | None = None) -> list[str]",
|
||||
"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."
|
||||
},
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
"kind": "class",
|
||||
"path": "docforge.loaders.griffe_loader.GriffeLoader",
|
||||
"signature": "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.loaders.griffe_loader.GriffeLoader.load_project",
|
||||
"signature": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None) -> 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.loaders.griffe_loader.GriffeLoader.load_module",
|
||||
"signature": "load_module(path: str) -> 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 ```"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
259
docs/mcp/modules/docforge.loaders.json
Normal file
259
docs/mcp/modules/docforge.loaders.json
Normal file
@@ -0,0 +1,259 @@
|
||||
{
|
||||
"module": "docforge.loaders",
|
||||
"content": {
|
||||
"path": "docforge.loaders",
|
||||
"docstring": "# Summary\n\nLoader layer for doc-forge.\n\nThe `docforge.loaders` package is responsible for discovering Python modules\nand extracting documentation data using static analysis.\n\n---\n\n# Overview\n\nThis layer converts Python source code into an intermediate documentation\nmodel used by doc-forge. It performs module discovery, introspection, and\ninitial filtering before the data is passed to the core documentation models.\n\nCore capabilities include:\n\n- **Module discovery** – Locate Python modules and packages within a project.\n- **Static introspection** – Parse docstrings, signatures, and object\n hierarchies using the `griffe` library without executing the code.\n- **Public API filtering** – Exclude private members (names prefixed with\n `_`) to produce clean public documentation structures.\n\n---",
|
||||
"objects": {
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
"kind": "class",
|
||||
"path": "docforge.loaders.GriffeLoader",
|
||||
"signature": "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.loaders.GriffeLoader.load_project",
|
||||
"signature": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None)",
|
||||
"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.loaders.GriffeLoader.load_module",
|
||||
"signature": "load_module(path: str)",
|
||||
"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.loaders.discover_module_paths",
|
||||
"signature": "discover_module_paths(module_name: str, project_root: Path | None = None)",
|
||||
"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."
|
||||
},
|
||||
"griffe_loader": {
|
||||
"name": "griffe_loader",
|
||||
"kind": "module",
|
||||
"path": "docforge.loaders.griffe_loader",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nUtilities for loading and introspecting Python modules using Griffe.\n\nThis module provides the `GriffeLoader` class and helper utilities used to\ndiscover Python modules, introspect their structure, and convert the results\ninto doc-forge documentation models.\n\n---\n\nNotes:\n - All analysis is static; analyzed modules are never executed.\n - Private members (names starting with `_`) are skipped during conversion.\n - Imported aliases that cannot be resolved (stdlib/third-party names) are\n skipped; aliases that resolve within the documented project are kept.\n\n---",
|
||||
"members": {
|
||||
"DocObject": {
|
||||
"name": "DocObject",
|
||||
"kind": "class",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject",
|
||||
"signature": "DocObject(name: str, kind: str, path: str, signature: str | None = None, docstring: str | None = None)",
|
||||
"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.loaders.griffe_loader.DocObject.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"kind": {
|
||||
"name": "kind",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject.kind",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"signature": {
|
||||
"name": "signature",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject.signature",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_member": {
|
||||
"name": "add_member",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.DocObject.add_member",
|
||||
"signature": "add_member(obj: DocObject)",
|
||||
"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.loaders.griffe_loader.DocObject.get_member",
|
||||
"signature": "get_member(name: str)",
|
||||
"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.loaders.griffe_loader.DocObject.get_all_members",
|
||||
"signature": "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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Module": {
|
||||
"name": "Module",
|
||||
"kind": "class",
|
||||
"path": "docforge.loaders.griffe_loader.Module",
|
||||
"signature": "Module(path: str, docstring: str | None = None)",
|
||||
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
|
||||
"members": {
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.Module.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.Module.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.Module.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_object": {
|
||||
"name": "add_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Module.add_object",
|
||||
"signature": "add_object(obj: DocObject)",
|
||||
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module."
|
||||
},
|
||||
"get_object": {
|
||||
"name": "get_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Module.get_object",
|
||||
"signature": "get_object(name: str)",
|
||||
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists."
|
||||
},
|
||||
"get_all_objects": {
|
||||
"name": "get_all_objects",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Module.get_all_objects",
|
||||
"signature": "get_all_objects()",
|
||||
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Project": {
|
||||
"name": "Project",
|
||||
"kind": "class",
|
||||
"path": "docforge.loaders.griffe_loader.Project",
|
||||
"signature": "Project(name: str)",
|
||||
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (dict[str, Module]):\n Mapping of module paths to `Module` instances.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.Project.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"modules": {
|
||||
"name": "modules",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.Project.modules",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_module": {
|
||||
"name": "add_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Project.add_module",
|
||||
"signature": "add_module(module: Module)",
|
||||
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
|
||||
},
|
||||
"get_module": {
|
||||
"name": "get_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Project.get_module",
|
||||
"signature": "get_module(path: str)",
|
||||
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project."
|
||||
},
|
||||
"get_all_modules": {
|
||||
"name": "get_all_modules",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Project.get_all_modules",
|
||||
"signature": "get_all_modules()",
|
||||
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
|
||||
},
|
||||
"get_module_list": {
|
||||
"name": "get_module_list",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.Project.get_module_list",
|
||||
"signature": "get_module_list()",
|
||||
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project."
|
||||
}
|
||||
}
|
||||
},
|
||||
"logger": {
|
||||
"name": "logger",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.loaders.griffe_loader.logger",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"discover_module_paths": {
|
||||
"name": "discover_module_paths",
|
||||
"kind": "function",
|
||||
"path": "docforge.loaders.griffe_loader.discover_module_paths",
|
||||
"signature": "discover_module_paths(module_name: str, project_root: Path | None = None) -> list[str]",
|
||||
"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."
|
||||
},
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
"kind": "class",
|
||||
"path": "docforge.loaders.griffe_loader.GriffeLoader",
|
||||
"signature": "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.loaders.griffe_loader.GriffeLoader.load_project",
|
||||
"signature": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None) -> 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.loaders.griffe_loader.GriffeLoader.load_module",
|
||||
"signature": "load_module(path: str) -> 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 ```"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
507
docs/mcp/modules/docforge.models.json
Normal file
507
docs/mcp/modules/docforge.models.json
Normal file
@@ -0,0 +1,507 @@
|
||||
{
|
||||
"module": "docforge.models",
|
||||
"content": {
|
||||
"path": "docforge.models",
|
||||
"docstring": "# Summary\n\nModel layer for doc-forge.\n\nThe `docforge.models` package defines the core data structures used to\nrepresent Python source code as a structured documentation model.\n\n---\n\n# Overview\n\nThe model layer forms the central intermediate representation used throughout\ndoc-forge. Python modules and objects discovered during introspection are\nconverted into a hierarchy of documentation models that can later be rendered\ninto different documentation formats.\n\nKey components:\n\n- **Project** – Root container representing an entire documented codebase.\n- **Module** – Representation of a Python module or package containing\n documented members.\n- **DocObject** – Recursive structure representing Python objects such as\n classes, functions, methods, and attributes.\n\nThese models are intentionally **renderer-agnostic**, allowing the same\ndocumentation structure to be transformed into multiple output formats\n(e.g., MkDocs, MCP, or other renderers).\n\n---",
|
||||
"objects": {
|
||||
"Project": {
|
||||
"name": "Project",
|
||||
"kind": "class",
|
||||
"path": "docforge.models.Project",
|
||||
"signature": "Project(name: str)",
|
||||
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (dict[str, Module]):\n Mapping of module paths to `Module` instances.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.Project.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"modules": {
|
||||
"name": "modules",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.Project.modules",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_module": {
|
||||
"name": "add_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.Project.add_module",
|
||||
"signature": "add_module(module: Module)",
|
||||
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
|
||||
},
|
||||
"get_module": {
|
||||
"name": "get_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.Project.get_module",
|
||||
"signature": "get_module(path: str)",
|
||||
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project."
|
||||
},
|
||||
"get_all_modules": {
|
||||
"name": "get_all_modules",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.Project.get_all_modules",
|
||||
"signature": "get_all_modules()",
|
||||
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
|
||||
},
|
||||
"get_module_list": {
|
||||
"name": "get_module_list",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.Project.get_module_list",
|
||||
"signature": "get_module_list()",
|
||||
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Module": {
|
||||
"name": "Module",
|
||||
"kind": "class",
|
||||
"path": "docforge.models.Module",
|
||||
"signature": "Module(path: str, docstring: str | None = None)",
|
||||
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
|
||||
"members": {
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.Module.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.Module.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.Module.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_object": {
|
||||
"name": "add_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.Module.add_object",
|
||||
"signature": "add_object(obj: DocObject)",
|
||||
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module."
|
||||
},
|
||||
"get_object": {
|
||||
"name": "get_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.Module.get_object",
|
||||
"signature": "get_object(name: str)",
|
||||
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists."
|
||||
},
|
||||
"get_all_objects": {
|
||||
"name": "get_all_objects",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.Module.get_all_objects",
|
||||
"signature": "get_all_objects()",
|
||||
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members."
|
||||
}
|
||||
}
|
||||
},
|
||||
"DocObject": {
|
||||
"name": "DocObject",
|
||||
"kind": "class",
|
||||
"path": "docforge.models.DocObject",
|
||||
"signature": "DocObject(name: str, kind: str, path: str, signature: str | None = None, docstring: str | None = None)",
|
||||
"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.models.DocObject.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"kind": {
|
||||
"name": "kind",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.DocObject.kind",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.DocObject.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"signature": {
|
||||
"name": "signature",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.DocObject.signature",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.DocObject.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.DocObject.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_member": {
|
||||
"name": "add_member",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.DocObject.add_member",
|
||||
"signature": "add_member(obj: DocObject)",
|
||||
"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.models.DocObject.get_member",
|
||||
"signature": "get_member(name: str)",
|
||||
"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.models.DocObject.get_all_members",
|
||||
"signature": "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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"module": {
|
||||
"name": "module",
|
||||
"kind": "module",
|
||||
"path": "docforge.models.module",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nDocumentation model representing a Python module or package.\n\nThis module defines the `Module` class used in the doc-forge documentation\nmodel. A `Module` acts as a container for top-level documented objects\n(classes, functions, variables, and other members) discovered during\nintrospection.\n\n---\n\nNotes:\n - Only public members are stored; private names are filtered by the loader.\n\n---",
|
||||
"members": {
|
||||
"DocObject": {
|
||||
"name": "DocObject",
|
||||
"kind": "class",
|
||||
"path": "docforge.models.module.DocObject",
|
||||
"signature": "DocObject(name: str, kind: str, path: str, signature: str | None = None, docstring: str | None = None)",
|
||||
"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.models.module.DocObject.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"kind": {
|
||||
"name": "kind",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.DocObject.kind",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.DocObject.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"signature": {
|
||||
"name": "signature",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.DocObject.signature",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.DocObject.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.DocObject.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_member": {
|
||||
"name": "add_member",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.module.DocObject.add_member",
|
||||
"signature": "add_member(obj: DocObject)",
|
||||
"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.models.module.DocObject.get_member",
|
||||
"signature": "get_member(name: str)",
|
||||
"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.models.module.DocObject.get_all_members",
|
||||
"signature": "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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Module": {
|
||||
"name": "Module",
|
||||
"kind": "class",
|
||||
"path": "docforge.models.module.Module",
|
||||
"signature": "Module(path: str, docstring: str | None = None)",
|
||||
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
|
||||
"members": {
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.Module.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.Module.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.Module.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_object": {
|
||||
"name": "add_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.module.Module.add_object",
|
||||
"signature": "add_object(obj: DocObject) -> None",
|
||||
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module."
|
||||
},
|
||||
"get_object": {
|
||||
"name": "get_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.module.Module.get_object",
|
||||
"signature": "get_object(name: str) -> DocObject",
|
||||
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists."
|
||||
},
|
||||
"get_all_objects": {
|
||||
"name": "get_all_objects",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.module.Module.get_all_objects",
|
||||
"signature": "get_all_objects() -> Iterable[DocObject]",
|
||||
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"object": {
|
||||
"name": "object",
|
||||
"kind": "module",
|
||||
"path": "docforge.models.object",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nDocumentation model representing individual Python objects.\n\nThis module defines the `DocObject` class, the fundamental recursive unit of\nthe doc-forge documentation model. Each `DocObject` represents a Python\nentity such as a class, function, method, or attribute, and may contain nested\nmembers that form a hierarchical documentation structure.\n\n---\n\nNotes:\n - `DocObject` instances form a tree mirroring the Python import hierarchy.\n - Objects are renderer-agnostic and may be consumed by any renderer.\n\n---",
|
||||
"members": {
|
||||
"DocObject": {
|
||||
"name": "DocObject",
|
||||
"kind": "class",
|
||||
"path": "docforge.models.object.DocObject",
|
||||
"signature": "DocObject(name: str, kind: str, path: str, signature: str | None = None, docstring: str | None = None)",
|
||||
"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.models.object.DocObject.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"kind": {
|
||||
"name": "kind",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.object.DocObject.kind",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.object.DocObject.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"signature": {
|
||||
"name": "signature",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.object.DocObject.signature",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.object.DocObject.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.object.DocObject.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_member": {
|
||||
"name": "add_member",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.object.DocObject.add_member",
|
||||
"signature": "add_member(obj: DocObject) -> None",
|
||||
"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.models.object.DocObject.get_member",
|
||||
"signature": "get_member(name: str) -> DocObject",
|
||||
"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.models.object.DocObject.get_all_members",
|
||||
"signature": "get_all_members() -> Iterable[DocObject]",
|
||||
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"project": {
|
||||
"name": "project",
|
||||
"kind": "module",
|
||||
"path": "docforge.models.project",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nDocumentation model representing a project.\n\nThis module defines the `Project` class, the top-level container used by\ndoc-forge to represent a documented codebase. A `Project` aggregates multiple\nmodules and provides access to them through a unified interface.\n\n---\n\nNotes:\n - Modules are keyed by their dotted import path.\n - Objects are renderer-agnostic; the same model feeds every renderer.\n\n---",
|
||||
"members": {
|
||||
"Module": {
|
||||
"name": "Module",
|
||||
"kind": "class",
|
||||
"path": "docforge.models.project.Module",
|
||||
"signature": "Module(path: str, docstring: str | None = None)",
|
||||
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
|
||||
"members": {
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.project.Module.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.project.Module.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.project.Module.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_object": {
|
||||
"name": "add_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Module.add_object",
|
||||
"signature": "add_object(obj: DocObject)",
|
||||
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module."
|
||||
},
|
||||
"get_object": {
|
||||
"name": "get_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Module.get_object",
|
||||
"signature": "get_object(name: str)",
|
||||
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists."
|
||||
},
|
||||
"get_all_objects": {
|
||||
"name": "get_all_objects",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Module.get_all_objects",
|
||||
"signature": "get_all_objects()",
|
||||
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Project": {
|
||||
"name": "Project",
|
||||
"kind": "class",
|
||||
"path": "docforge.models.project.Project",
|
||||
"signature": "Project(name: str)",
|
||||
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (dict[str, Module]):\n Mapping of module paths to `Module` instances.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.project.Project.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"modules": {
|
||||
"name": "modules",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.project.Project.modules",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_module": {
|
||||
"name": "add_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Project.add_module",
|
||||
"signature": "add_module(module: Module) -> None",
|
||||
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
|
||||
},
|
||||
"get_module": {
|
||||
"name": "get_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Project.get_module",
|
||||
"signature": "get_module(path: str) -> Module",
|
||||
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project."
|
||||
},
|
||||
"get_all_modules": {
|
||||
"name": "get_all_modules",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Project.get_all_modules",
|
||||
"signature": "get_all_modules() -> Iterable[Module]",
|
||||
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
|
||||
},
|
||||
"get_module_list": {
|
||||
"name": "get_module_list",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Project.get_module_list",
|
||||
"signature": "get_module_list() -> list[str]",
|
||||
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
132
docs/mcp/modules/docforge.models.module.json
Normal file
132
docs/mcp/modules/docforge.models.module.json
Normal file
@@ -0,0 +1,132 @@
|
||||
{
|
||||
"module": "docforge.models.module",
|
||||
"content": {
|
||||
"path": "docforge.models.module",
|
||||
"docstring": "# Summary\n\nDocumentation model representing a Python module or package.\n\nThis module defines the `Module` class used in the doc-forge documentation\nmodel. A `Module` acts as a container for top-level documented objects\n(classes, functions, variables, and other members) discovered during\nintrospection.\n\n---\n\nNotes:\n - Only public members are stored; private names are filtered by the loader.\n\n---",
|
||||
"objects": {
|
||||
"DocObject": {
|
||||
"name": "DocObject",
|
||||
"kind": "class",
|
||||
"path": "docforge.models.module.DocObject",
|
||||
"signature": "DocObject(name: str, kind: str, path: str, signature: str | None = None, docstring: str | None = None)",
|
||||
"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.models.module.DocObject.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"kind": {
|
||||
"name": "kind",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.DocObject.kind",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.DocObject.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"signature": {
|
||||
"name": "signature",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.DocObject.signature",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.DocObject.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.DocObject.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_member": {
|
||||
"name": "add_member",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.module.DocObject.add_member",
|
||||
"signature": "add_member(obj: DocObject)",
|
||||
"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.models.module.DocObject.get_member",
|
||||
"signature": "get_member(name: str)",
|
||||
"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.models.module.DocObject.get_all_members",
|
||||
"signature": "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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Module": {
|
||||
"name": "Module",
|
||||
"kind": "class",
|
||||
"path": "docforge.models.module.Module",
|
||||
"signature": "Module(path: str, docstring: str | None = None)",
|
||||
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
|
||||
"members": {
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.Module.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.Module.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.module.Module.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_object": {
|
||||
"name": "add_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.module.Module.add_object",
|
||||
"signature": "add_object(obj: DocObject) -> None",
|
||||
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module."
|
||||
},
|
||||
"get_object": {
|
||||
"name": "get_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.module.Module.get_object",
|
||||
"signature": "get_object(name: str) -> DocObject",
|
||||
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists."
|
||||
},
|
||||
"get_all_objects": {
|
||||
"name": "get_all_objects",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.module.Module.get_all_objects",
|
||||
"signature": "get_all_objects() -> Iterable[DocObject]",
|
||||
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
81
docs/mcp/modules/docforge.models.object.json
Normal file
81
docs/mcp/modules/docforge.models.object.json
Normal file
@@ -0,0 +1,81 @@
|
||||
{
|
||||
"module": "docforge.models.object",
|
||||
"content": {
|
||||
"path": "docforge.models.object",
|
||||
"docstring": "# Summary\n\nDocumentation model representing individual Python objects.\n\nThis module defines the `DocObject` class, the fundamental recursive unit of\nthe doc-forge documentation model. Each `DocObject` represents a Python\nentity such as a class, function, method, or attribute, and may contain nested\nmembers that form a hierarchical documentation structure.\n\n---\n\nNotes:\n - `DocObject` instances form a tree mirroring the Python import hierarchy.\n - Objects are renderer-agnostic and may be consumed by any renderer.\n\n---",
|
||||
"objects": {
|
||||
"DocObject": {
|
||||
"name": "DocObject",
|
||||
"kind": "class",
|
||||
"path": "docforge.models.object.DocObject",
|
||||
"signature": "DocObject(name: str, kind: str, path: str, signature: str | None = None, docstring: str | None = None)",
|
||||
"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.models.object.DocObject.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"kind": {
|
||||
"name": "kind",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.object.DocObject.kind",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.object.DocObject.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"signature": {
|
||||
"name": "signature",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.object.DocObject.signature",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.object.DocObject.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.object.DocObject.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_member": {
|
||||
"name": "add_member",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.object.DocObject.add_member",
|
||||
"signature": "add_member(obj: DocObject) -> None",
|
||||
"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.models.object.DocObject.get_member",
|
||||
"signature": "get_member(name: str) -> DocObject",
|
||||
"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.models.object.DocObject.get_all_members",
|
||||
"signature": "get_all_members() -> Iterable[DocObject]",
|
||||
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
111
docs/mcp/modules/docforge.models.project.json
Normal file
111
docs/mcp/modules/docforge.models.project.json
Normal file
@@ -0,0 +1,111 @@
|
||||
{
|
||||
"module": "docforge.models.project",
|
||||
"content": {
|
||||
"path": "docforge.models.project",
|
||||
"docstring": "# Summary\n\nDocumentation model representing a project.\n\nThis module defines the `Project` class, the top-level container used by\ndoc-forge to represent a documented codebase. A `Project` aggregates multiple\nmodules and provides access to them through a unified interface.\n\n---\n\nNotes:\n - Modules are keyed by their dotted import path.\n - Objects are renderer-agnostic; the same model feeds every renderer.\n\n---",
|
||||
"objects": {
|
||||
"Module": {
|
||||
"name": "Module",
|
||||
"kind": "class",
|
||||
"path": "docforge.models.project.Module",
|
||||
"signature": "Module(path: str, docstring: str | None = None)",
|
||||
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
|
||||
"members": {
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.project.Module.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.project.Module.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.project.Module.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_object": {
|
||||
"name": "add_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Module.add_object",
|
||||
"signature": "add_object(obj: DocObject)",
|
||||
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module."
|
||||
},
|
||||
"get_object": {
|
||||
"name": "get_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Module.get_object",
|
||||
"signature": "get_object(name: str)",
|
||||
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists."
|
||||
},
|
||||
"get_all_objects": {
|
||||
"name": "get_all_objects",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Module.get_all_objects",
|
||||
"signature": "get_all_objects()",
|
||||
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Project": {
|
||||
"name": "Project",
|
||||
"kind": "class",
|
||||
"path": "docforge.models.project.Project",
|
||||
"signature": "Project(name: str)",
|
||||
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (dict[str, Module]):\n Mapping of module paths to `Module` instances.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.project.Project.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"modules": {
|
||||
"name": "modules",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.models.project.Project.modules",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_module": {
|
||||
"name": "add_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Project.add_module",
|
||||
"signature": "add_module(module: Module) -> None",
|
||||
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
|
||||
},
|
||||
"get_module": {
|
||||
"name": "get_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Project.get_module",
|
||||
"signature": "get_module(path: str) -> Module",
|
||||
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project."
|
||||
},
|
||||
"get_all_modules": {
|
||||
"name": "get_all_modules",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Project.get_all_modules",
|
||||
"signature": "get_all_modules() -> Iterable[Module]",
|
||||
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
|
||||
},
|
||||
"get_module_list": {
|
||||
"name": "get_module_list",
|
||||
"kind": "function",
|
||||
"path": "docforge.models.project.Project.get_module_list",
|
||||
"signature": "get_module_list() -> list[str]",
|
||||
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
341
docs/mcp/modules/docforge.nav.json
Normal file
341
docs/mcp/modules/docforge.nav.json
Normal file
@@ -0,0 +1,341 @@
|
||||
{
|
||||
"module": "docforge.nav",
|
||||
"content": {
|
||||
"path": "docforge.nav",
|
||||
"docstring": "Navigation layer for doc-forge.\n\nThe ``docforge.nav`` package manages the relationship between the logical\ndocumentation structure defined by the user and the physical documentation\nfiles generated on disk.\n\n---\n\nWorkflow\n--------\n\n1. **Specification** – Users define navigation intent in ``docforge.nav.yml``.\n2. **Resolution** – ``resolve_nav`` expands patterns and matches them against\n generated Markdown files.\n3. **Emission** – ``MkDocsNavEmitter`` converts the resolved structure into\n the YAML navigation format required by ``mkdocs.yml``.\n\nThis layer separates documentation organization from the underlying source\ncode layout, enabling flexible grouping, ordering, and navigation structures\nindependent of module hierarchy.\n\n---",
|
||||
"objects": {
|
||||
"NavSpec": {
|
||||
"name": "NavSpec",
|
||||
"kind": "class",
|
||||
"path": "docforge.nav.NavSpec",
|
||||
"signature": "NavSpec(home: str | None, groups: dict[str, list[str]], icon: dict[str, str] | None = None)",
|
||||
"docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page (for example\n ``index.md``).\n groups: Mapping of navigation group titles to lists of file patterns\n or glob expressions.\n icon: Optional mapping of theme icon entries (for example\n ``{\"logo\": \"material/code-tags\"}``) injected into the MkDocs\n theme as ``theme.icon``.",
|
||||
"members": {
|
||||
"home": {
|
||||
"name": "home",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.NavSpec.home",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"groups": {
|
||||
"name": "groups",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.NavSpec.groups",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"icon": {
|
||||
"name": "icon",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.NavSpec.icon",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"load": {
|
||||
"name": "load",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.NavSpec.load",
|
||||
"signature": "load(path: Path)",
|
||||
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path (Path):\n Filesystem path to the navigation specification file.\n\nReturns:\n NavSpec:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification."
|
||||
},
|
||||
"all_patterns": {
|
||||
"name": "all_patterns",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.NavSpec.all_patterns",
|
||||
"signature": "all_patterns()",
|
||||
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n list[str]:\n A list containing the home document (if defined) and all\n group pattern entries."
|
||||
}
|
||||
}
|
||||
},
|
||||
"load_nav_spec": {
|
||||
"name": "load_nav_spec",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.load_nav_spec",
|
||||
"signature": "load_nav_spec(path: Path)",
|
||||
"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."
|
||||
},
|
||||
"ResolvedNav": {
|
||||
"name": "ResolvedNav",
|
||||
"kind": "class",
|
||||
"path": "docforge.nav.ResolvedNav",
|
||||
"signature": "ResolvedNav(home: str | None, groups: dict[str, list[Path]], docs_root: Path | None = None)",
|
||||
"docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page.\n groups: Mapping of navigation group titles to lists of resolved\n documentation file paths.",
|
||||
"members": {
|
||||
"home": {
|
||||
"name": "home",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.ResolvedNav.home",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"groups": {
|
||||
"name": "groups",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.ResolvedNav.groups",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"all_files": {
|
||||
"name": "all_files",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.ResolvedNav.all_files",
|
||||
"signature": "all_files()",
|
||||
"docstring": "Iterate over all files referenced by the navigation structure.\n\nYields:\n Path:\n A documentation file referenced by the navigation, including\n the home page when defined.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution."
|
||||
}
|
||||
}
|
||||
},
|
||||
"resolve_nav": {
|
||||
"name": "resolve_nav",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.resolve_nav",
|
||||
"signature": "resolve_nav(spec: NavSpec, docs_root: Path)",
|
||||
"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."
|
||||
},
|
||||
"MkDocsNavEmitter": {
|
||||
"name": "MkDocsNavEmitter",
|
||||
"kind": "class",
|
||||
"path": "docforge.nav.MkDocsNavEmitter",
|
||||
"signature": null,
|
||||
"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.nav.MkDocsNavEmitter.emit",
|
||||
"signature": "emit(nav: ResolvedNav)",
|
||||
"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.nav.build_wiki_nav",
|
||||
"signature": "build_wiki_nav(wiki_dir: Path)",
|
||||
"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."
|
||||
},
|
||||
"mkdocs": {
|
||||
"name": "mkdocs",
|
||||
"kind": "module",
|
||||
"path": "docforge.nav.mkdocs",
|
||||
"signature": null,
|
||||
"docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.\n\n---\n\nNotes:\n - The emitted structure is a list of dictionaries, one per top-level nav\n entry, matching the MkDocs ``nav`` YAML format.\n\n---",
|
||||
"members": {
|
||||
"ResolvedNav": {
|
||||
"name": "ResolvedNav",
|
||||
"kind": "class",
|
||||
"path": "docforge.nav.mkdocs.ResolvedNav",
|
||||
"signature": "ResolvedNav(home: str | None, groups: dict[str, list[Path]], docs_root: Path | None = None)",
|
||||
"docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page.\n groups: Mapping of navigation group titles to lists of resolved\n documentation file paths.",
|
||||
"members": {
|
||||
"home": {
|
||||
"name": "home",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.mkdocs.ResolvedNav.home",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"groups": {
|
||||
"name": "groups",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.mkdocs.ResolvedNav.groups",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"all_files": {
|
||||
"name": "all_files",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.mkdocs.ResolvedNav.all_files",
|
||||
"signature": "all_files()",
|
||||
"docstring": "Iterate over all files referenced by the navigation structure.\n\nYields:\n Path:\n A documentation file referenced by the navigation, including\n the home page when defined.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution."
|
||||
}
|
||||
}
|
||||
},
|
||||
"MkDocsNavEmitter": {
|
||||
"name": "MkDocsNavEmitter",
|
||||
"kind": "class",
|
||||
"path": "docforge.nav.mkdocs.MkDocsNavEmitter",
|
||||
"signature": null,
|
||||
"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.nav.mkdocs.MkDocsNavEmitter.emit",
|
||||
"signature": "emit(nav: ResolvedNav) -> list[dict[str, Any]]",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"resolver": {
|
||||
"name": "resolver",
|
||||
"kind": "module",
|
||||
"path": "docforge.nav.resolver",
|
||||
"signature": null,
|
||||
"docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.\n\n---\n\nNotes:\n - Glob resolution is recursive and returns paths in sorted order.\n - Unmatched patterns raise ``FileNotFoundError`` to fail fast on typos.\n\n---",
|
||||
"members": {
|
||||
"NavSpec": {
|
||||
"name": "NavSpec",
|
||||
"kind": "class",
|
||||
"path": "docforge.nav.resolver.NavSpec",
|
||||
"signature": "NavSpec(home: str | None, groups: dict[str, list[str]], icon: dict[str, str] | None = None)",
|
||||
"docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page (for example\n ``index.md``).\n groups: Mapping of navigation group titles to lists of file patterns\n or glob expressions.\n icon: Optional mapping of theme icon entries (for example\n ``{\"logo\": \"material/code-tags\"}``) injected into the MkDocs\n theme as ``theme.icon``.",
|
||||
"members": {
|
||||
"home": {
|
||||
"name": "home",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.resolver.NavSpec.home",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"groups": {
|
||||
"name": "groups",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.resolver.NavSpec.groups",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"icon": {
|
||||
"name": "icon",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.resolver.NavSpec.icon",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"load": {
|
||||
"name": "load",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.resolver.NavSpec.load",
|
||||
"signature": "load(path: Path)",
|
||||
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path (Path):\n Filesystem path to the navigation specification file.\n\nReturns:\n NavSpec:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification."
|
||||
},
|
||||
"all_patterns": {
|
||||
"name": "all_patterns",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.resolver.NavSpec.all_patterns",
|
||||
"signature": "all_patterns()",
|
||||
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n list[str]:\n A list containing the home document (if defined) and all\n group pattern entries."
|
||||
}
|
||||
}
|
||||
},
|
||||
"ResolvedNav": {
|
||||
"name": "ResolvedNav",
|
||||
"kind": "class",
|
||||
"path": "docforge.nav.resolver.ResolvedNav",
|
||||
"signature": "ResolvedNav(home: str | None, groups: dict[str, list[Path]], docs_root: Path | None = None)",
|
||||
"docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page.\n groups: Mapping of navigation group titles to lists of resolved\n documentation file paths.",
|
||||
"members": {
|
||||
"home": {
|
||||
"name": "home",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.resolver.ResolvedNav.home",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"groups": {
|
||||
"name": "groups",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.resolver.ResolvedNav.groups",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"all_files": {
|
||||
"name": "all_files",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.resolver.ResolvedNav.all_files",
|
||||
"signature": "all_files() -> Iterable[Path]",
|
||||
"docstring": "Iterate over all files referenced by the navigation structure.\n\nYields:\n Path:\n A documentation file referenced by the navigation, including\n the home page when defined.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution."
|
||||
}
|
||||
}
|
||||
},
|
||||
"resolve_nav": {
|
||||
"name": "resolve_nav",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.resolver.resolve_nav",
|
||||
"signature": "resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"spec": {
|
||||
"name": "spec",
|
||||
"kind": "module",
|
||||
"path": "docforge.nav.spec",
|
||||
"signature": null,
|
||||
"docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).\n\n---\n\nNotes:\n - The spec file supports an optional ``icon`` mapping for MkDocs theme\n customization.\n - All file references in ``groups`` are relative to the documentation root.\n\n---",
|
||||
"members": {
|
||||
"NavSpec": {
|
||||
"name": "NavSpec",
|
||||
"kind": "class",
|
||||
"path": "docforge.nav.spec.NavSpec",
|
||||
"signature": "NavSpec(home: str | None, groups: dict[str, list[str]], icon: dict[str, str] | None = None)",
|
||||
"docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page (for example\n ``index.md``).\n groups: Mapping of navigation group titles to lists of file patterns\n or glob expressions.\n icon: Optional mapping of theme icon entries (for example\n ``{\"logo\": \"material/code-tags\"}``) injected into the MkDocs\n theme as ``theme.icon``.",
|
||||
"members": {
|
||||
"home": {
|
||||
"name": "home",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.spec.NavSpec.home",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"groups": {
|
||||
"name": "groups",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.spec.NavSpec.groups",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"icon": {
|
||||
"name": "icon",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.spec.NavSpec.icon",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"load": {
|
||||
"name": "load",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.spec.NavSpec.load",
|
||||
"signature": "load(path: Path) -> NavSpec",
|
||||
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path (Path):\n Filesystem path to the navigation specification file.\n\nReturns:\n NavSpec:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification."
|
||||
},
|
||||
"all_patterns": {
|
||||
"name": "all_patterns",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.spec.NavSpec.all_patterns",
|
||||
"signature": "all_patterns() -> list[str]",
|
||||
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n list[str]:\n A list containing the home document (if defined) and all\n group pattern entries."
|
||||
}
|
||||
}
|
||||
},
|
||||
"load_nav_spec": {
|
||||
"name": "load_nav_spec",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.spec.load_nav_spec",
|
||||
"signature": "load_nav_spec(path: Path) -> NavSpec",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"wiki": {
|
||||
"name": "wiki",
|
||||
"kind": "module",
|
||||
"path": "docforge.nav.wiki",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nWiki navigation derivation.\n\nThis module provides ``build_wiki_nav``, which derives an MkDocs-ready\nnavigation block from the file structure of a hand-written wiki directory\n(typically ``docs/wiki``). wiki content is authored by hand and is never\nmodified by doc-forge; only the navigation layout is inferred.\n\n# Notes\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.",
|
||||
"members": {
|
||||
"build_wiki_nav": {
|
||||
"name": "build_wiki_nav",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.wiki.build_wiki_nav",
|
||||
"signature": "build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
55
docs/mcp/modules/docforge.nav.mkdocs.json
Normal file
55
docs/mcp/modules/docforge.nav.mkdocs.json
Normal file
@@ -0,0 +1,55 @@
|
||||
{
|
||||
"module": "docforge.nav.mkdocs",
|
||||
"content": {
|
||||
"path": "docforge.nav.mkdocs",
|
||||
"docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.\n\n---\n\nNotes:\n - The emitted structure is a list of dictionaries, one per top-level nav\n entry, matching the MkDocs ``nav`` YAML format.\n\n---",
|
||||
"objects": {
|
||||
"ResolvedNav": {
|
||||
"name": "ResolvedNav",
|
||||
"kind": "class",
|
||||
"path": "docforge.nav.mkdocs.ResolvedNav",
|
||||
"signature": "ResolvedNav(home: str | None, groups: dict[str, list[Path]], docs_root: Path | None = None)",
|
||||
"docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page.\n groups: Mapping of navigation group titles to lists of resolved\n documentation file paths.",
|
||||
"members": {
|
||||
"home": {
|
||||
"name": "home",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.mkdocs.ResolvedNav.home",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"groups": {
|
||||
"name": "groups",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.mkdocs.ResolvedNav.groups",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"all_files": {
|
||||
"name": "all_files",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.mkdocs.ResolvedNav.all_files",
|
||||
"signature": "all_files()",
|
||||
"docstring": "Iterate over all files referenced by the navigation structure.\n\nYields:\n Path:\n A documentation file referenced by the navigation, including\n the home page when defined.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution."
|
||||
}
|
||||
}
|
||||
},
|
||||
"MkDocsNavEmitter": {
|
||||
"name": "MkDocsNavEmitter",
|
||||
"kind": "class",
|
||||
"path": "docforge.nav.mkdocs.MkDocsNavEmitter",
|
||||
"signature": null,
|
||||
"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.nav.mkdocs.MkDocsNavEmitter.emit",
|
||||
"signature": "emit(nav: ResolvedNav) -> list[dict[str, Any]]",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
90
docs/mcp/modules/docforge.nav.resolver.json
Normal file
90
docs/mcp/modules/docforge.nav.resolver.json
Normal file
@@ -0,0 +1,90 @@
|
||||
{
|
||||
"module": "docforge.nav.resolver",
|
||||
"content": {
|
||||
"path": "docforge.nav.resolver",
|
||||
"docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.\n\n---\n\nNotes:\n - Glob resolution is recursive and returns paths in sorted order.\n - Unmatched patterns raise ``FileNotFoundError`` to fail fast on typos.\n\n---",
|
||||
"objects": {
|
||||
"NavSpec": {
|
||||
"name": "NavSpec",
|
||||
"kind": "class",
|
||||
"path": "docforge.nav.resolver.NavSpec",
|
||||
"signature": "NavSpec(home: str | None, groups: dict[str, list[str]], icon: dict[str, str] | None = None)",
|
||||
"docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page (for example\n ``index.md``).\n groups: Mapping of navigation group titles to lists of file patterns\n or glob expressions.\n icon: Optional mapping of theme icon entries (for example\n ``{\"logo\": \"material/code-tags\"}``) injected into the MkDocs\n theme as ``theme.icon``.",
|
||||
"members": {
|
||||
"home": {
|
||||
"name": "home",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.resolver.NavSpec.home",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"groups": {
|
||||
"name": "groups",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.resolver.NavSpec.groups",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"icon": {
|
||||
"name": "icon",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.resolver.NavSpec.icon",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"load": {
|
||||
"name": "load",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.resolver.NavSpec.load",
|
||||
"signature": "load(path: Path)",
|
||||
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path (Path):\n Filesystem path to the navigation specification file.\n\nReturns:\n NavSpec:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification."
|
||||
},
|
||||
"all_patterns": {
|
||||
"name": "all_patterns",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.resolver.NavSpec.all_patterns",
|
||||
"signature": "all_patterns()",
|
||||
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n list[str]:\n A list containing the home document (if defined) and all\n group pattern entries."
|
||||
}
|
||||
}
|
||||
},
|
||||
"ResolvedNav": {
|
||||
"name": "ResolvedNav",
|
||||
"kind": "class",
|
||||
"path": "docforge.nav.resolver.ResolvedNav",
|
||||
"signature": "ResolvedNav(home: str | None, groups: dict[str, list[Path]], docs_root: Path | None = None)",
|
||||
"docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page.\n groups: Mapping of navigation group titles to lists of resolved\n documentation file paths.",
|
||||
"members": {
|
||||
"home": {
|
||||
"name": "home",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.resolver.ResolvedNav.home",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"groups": {
|
||||
"name": "groups",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.resolver.ResolvedNav.groups",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"all_files": {
|
||||
"name": "all_files",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.resolver.ResolvedNav.all_files",
|
||||
"signature": "all_files() -> Iterable[Path]",
|
||||
"docstring": "Iterate over all files referenced by the navigation structure.\n\nYields:\n Path:\n A documentation file referenced by the navigation, including\n the home page when defined.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution."
|
||||
}
|
||||
}
|
||||
},
|
||||
"resolve_nav": {
|
||||
"name": "resolve_nav",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.resolver.resolve_nav",
|
||||
"signature": "resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
60
docs/mcp/modules/docforge.nav.spec.json
Normal file
60
docs/mcp/modules/docforge.nav.spec.json
Normal file
@@ -0,0 +1,60 @@
|
||||
{
|
||||
"module": "docforge.nav.spec",
|
||||
"content": {
|
||||
"path": "docforge.nav.spec",
|
||||
"docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).\n\n---\n\nNotes:\n - The spec file supports an optional ``icon`` mapping for MkDocs theme\n customization.\n - All file references in ``groups`` are relative to the documentation root.\n\n---",
|
||||
"objects": {
|
||||
"NavSpec": {
|
||||
"name": "NavSpec",
|
||||
"kind": "class",
|
||||
"path": "docforge.nav.spec.NavSpec",
|
||||
"signature": "NavSpec(home: str | None, groups: dict[str, list[str]], icon: dict[str, str] | None = None)",
|
||||
"docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page (for example\n ``index.md``).\n groups: Mapping of navigation group titles to lists of file patterns\n or glob expressions.\n icon: Optional mapping of theme icon entries (for example\n ``{\"logo\": \"material/code-tags\"}``) injected into the MkDocs\n theme as ``theme.icon``.",
|
||||
"members": {
|
||||
"home": {
|
||||
"name": "home",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.spec.NavSpec.home",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"groups": {
|
||||
"name": "groups",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.spec.NavSpec.groups",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"icon": {
|
||||
"name": "icon",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.nav.spec.NavSpec.icon",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"load": {
|
||||
"name": "load",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.spec.NavSpec.load",
|
||||
"signature": "load(path: Path) -> NavSpec",
|
||||
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path (Path):\n Filesystem path to the navigation specification file.\n\nReturns:\n NavSpec:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification."
|
||||
},
|
||||
"all_patterns": {
|
||||
"name": "all_patterns",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.spec.NavSpec.all_patterns",
|
||||
"signature": "all_patterns() -> list[str]",
|
||||
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n list[str]:\n A list containing the home document (if defined) and all\n group pattern entries."
|
||||
}
|
||||
}
|
||||
},
|
||||
"load_nav_spec": {
|
||||
"name": "load_nav_spec",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.spec.load_nav_spec",
|
||||
"signature": "load_nav_spec(path: Path) -> NavSpec",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
16
docs/mcp/modules/docforge.nav.wiki.json
Normal file
16
docs/mcp/modules/docforge.nav.wiki.json
Normal file
@@ -0,0 +1,16 @@
|
||||
{
|
||||
"module": "docforge.nav.wiki",
|
||||
"content": {
|
||||
"path": "docforge.nav.wiki",
|
||||
"docstring": "# Summary\n\nWiki navigation derivation.\n\nThis module provides ``build_wiki_nav``, which derives an MkDocs-ready\nnavigation block from the file structure of a hand-written wiki directory\n(typically ``docs/wiki``). wiki content is authored by hand and is never\nmodified by doc-forge; only the navigation layout is inferred.\n\n# Notes\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.",
|
||||
"objects": {
|
||||
"build_wiki_nav": {
|
||||
"name": "build_wiki_nav",
|
||||
"kind": "function",
|
||||
"path": "docforge.nav.wiki.build_wiki_nav",
|
||||
"signature": "build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
106
docs/mcp/modules/docforge.renderers.base.json
Normal file
106
docs/mcp/modules/docforge.renderers.base.json
Normal file
@@ -0,0 +1,106 @@
|
||||
{
|
||||
"module": "docforge.renderers.base",
|
||||
"content": {
|
||||
"path": "docforge.renderers.base",
|
||||
"docstring": "# Summary\n\nRenderer base interfaces and configuration models.\n\nThis module defines the base protocol and configuration container used by\ndoc-forge renderers. Concrete renderer implementations should implement the\n`DocRenderer` protocol.",
|
||||
"objects": {
|
||||
"Project": {
|
||||
"name": "Project",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.base.Project",
|
||||
"signature": "Project(name: str)",
|
||||
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (dict[str, Module]):\n Mapping of module paths to `Module` instances.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.base.Project.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"modules": {
|
||||
"name": "modules",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.base.Project.modules",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_module": {
|
||||
"name": "add_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.base.Project.add_module",
|
||||
"signature": "add_module(module: Module)",
|
||||
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
|
||||
},
|
||||
"get_module": {
|
||||
"name": "get_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.base.Project.get_module",
|
||||
"signature": "get_module(path: str)",
|
||||
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project."
|
||||
},
|
||||
"get_all_modules": {
|
||||
"name": "get_all_modules",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.base.Project.get_all_modules",
|
||||
"signature": "get_all_modules()",
|
||||
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
|
||||
},
|
||||
"get_module_list": {
|
||||
"name": "get_module_list",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.base.Project.get_module_list",
|
||||
"signature": "get_module_list()",
|
||||
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project."
|
||||
}
|
||||
}
|
||||
},
|
||||
"RendererConfig": {
|
||||
"name": "RendererConfig",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.base.RendererConfig",
|
||||
"signature": "RendererConfig(out_dir: Path, project: Project)",
|
||||
"docstring": "Configuration container for documentation renderers.\n\nA `RendererConfig` instance groups together the project model and the\noutput directory used during rendering.\n\nAttributes:\n out_dir (Path):\n Directory where generated documentation files will be written.\n\n project (Project):\n Documentation project model to be rendered.",
|
||||
"members": {
|
||||
"out_dir": {
|
||||
"name": "out_dir",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.base.RendererConfig.out_dir",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"project": {
|
||||
"name": "project",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.base.RendererConfig.project",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
}
|
||||
}
|
||||
},
|
||||
"DocRenderer": {
|
||||
"name": "DocRenderer",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.base.DocRenderer",
|
||||
"signature": null,
|
||||
"docstring": "Protocol defining the interface for documentation renderers.\n\nImplementations of this protocol are responsible for transforming a\n`Project` model into renderer-specific documentation sources.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.base.DocRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.base.DocRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path) -> None",
|
||||
"docstring": "Generate renderer-specific documentation sources.\n\nArgs:\n project (Project):\n Project model containing modules and documentation objects.\n\n out_dir (Path):\n Directory where generated documentation sources should be written."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
515
docs/mcp/modules/docforge.renderers.json
Normal file
515
docs/mcp/modules/docforge.renderers.json
Normal file
@@ -0,0 +1,515 @@
|
||||
{
|
||||
"module": "docforge.renderers",
|
||||
"content": {
|
||||
"path": "docforge.renderers",
|
||||
"docstring": "# Summary\n\nRenderers layer for doc-forge.\n\nThe `docforge.renderers` package transforms the internal documentation\nmodels into files formatted for specific documentation systems.\n\n---\n\n# Overview\n\nRenderers consume the doc-forge project model and generate output suitable\nfor documentation tools or machine interfaces.\n\nCurrent implementations:\n\n- **MkDocsRenderer** – Produces Markdown files compatible with MkDocs and\n the `mkdocstrings` plugin. It automatically handles package hierarchy\n and generates `index.md` files for packages.\n- **MCPRenderer** – Emits structured JSON resources designed for consumption\n by Model Context Protocol (MCP) clients.\n\n---\n\n# Extending\n\nNew renderers can be added by implementing the `DocRenderer` protocol\ndefined in `docforge.renderers.base`.\n\n---",
|
||||
"objects": {
|
||||
"MkDocsRenderer": {
|
||||
"name": "MkDocsRenderer",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.MkDocsRenderer",
|
||||
"signature": null,
|
||||
"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.renderers.MkDocsRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.MkDocsRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path, module_is_source: bool | None = None)",
|
||||
"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.renderers.MkDocsRenderer.generate_readme",
|
||||
"signature": "generate_readme(project: Project, docs_dir: Path, module_is_source: bool | None = None, readme_dir: Path | None = None)",
|
||||
"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`."
|
||||
}
|
||||
}
|
||||
},
|
||||
"MCPRenderer": {
|
||||
"name": "MCPRenderer",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.MCPRenderer",
|
||||
"signature": null,
|
||||
"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.renderers.MCPRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.MCPRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path)",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"base": {
|
||||
"name": "base",
|
||||
"kind": "module",
|
||||
"path": "docforge.renderers.base",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nRenderer base interfaces and configuration models.\n\nThis module defines the base protocol and configuration container used by\ndoc-forge renderers. Concrete renderer implementations should implement the\n`DocRenderer` protocol.",
|
||||
"members": {
|
||||
"Project": {
|
||||
"name": "Project",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.base.Project",
|
||||
"signature": "Project(name: str)",
|
||||
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (dict[str, Module]):\n Mapping of module paths to `Module` instances.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.base.Project.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"modules": {
|
||||
"name": "modules",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.base.Project.modules",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_module": {
|
||||
"name": "add_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.base.Project.add_module",
|
||||
"signature": "add_module(module: Module)",
|
||||
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
|
||||
},
|
||||
"get_module": {
|
||||
"name": "get_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.base.Project.get_module",
|
||||
"signature": "get_module(path: str)",
|
||||
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project."
|
||||
},
|
||||
"get_all_modules": {
|
||||
"name": "get_all_modules",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.base.Project.get_all_modules",
|
||||
"signature": "get_all_modules()",
|
||||
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
|
||||
},
|
||||
"get_module_list": {
|
||||
"name": "get_module_list",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.base.Project.get_module_list",
|
||||
"signature": "get_module_list()",
|
||||
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project."
|
||||
}
|
||||
}
|
||||
},
|
||||
"RendererConfig": {
|
||||
"name": "RendererConfig",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.base.RendererConfig",
|
||||
"signature": "RendererConfig(out_dir: Path, project: Project)",
|
||||
"docstring": "Configuration container for documentation renderers.\n\nA `RendererConfig` instance groups together the project model and the\noutput directory used during rendering.\n\nAttributes:\n out_dir (Path):\n Directory where generated documentation files will be written.\n\n project (Project):\n Documentation project model to be rendered.",
|
||||
"members": {
|
||||
"out_dir": {
|
||||
"name": "out_dir",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.base.RendererConfig.out_dir",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"project": {
|
||||
"name": "project",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.base.RendererConfig.project",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
}
|
||||
}
|
||||
},
|
||||
"DocRenderer": {
|
||||
"name": "DocRenderer",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.base.DocRenderer",
|
||||
"signature": null,
|
||||
"docstring": "Protocol defining the interface for documentation renderers.\n\nImplementations of this protocol are responsible for transforming a\n`Project` model into renderer-specific documentation sources.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.base.DocRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.base.DocRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path) -> None",
|
||||
"docstring": "Generate renderer-specific documentation sources.\n\nArgs:\n project (Project):\n Project model containing modules and documentation objects.\n\n out_dir (Path):\n Directory where generated documentation sources should be written."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"mcp_renderer": {
|
||||
"name": "mcp_renderer",
|
||||
"kind": "module",
|
||||
"path": "docforge.renderers.mcp_renderer",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nMCP renderer implementation.\n\nThis module defines the `MCPRenderer` class, which generates documentation\nresources compatible with the Model Context Protocol (MCP).",
|
||||
"members": {
|
||||
"DocObject": {
|
||||
"name": "DocObject",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject",
|
||||
"signature": "DocObject(name: str, kind: str, path: str, signature: str | None = None, docstring: str | None = None)",
|
||||
"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.renderers.mcp_renderer.DocObject.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"kind": {
|
||||
"name": "kind",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject.kind",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"signature": {
|
||||
"name": "signature",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject.signature",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_member": {
|
||||
"name": "add_member",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject.add_member",
|
||||
"signature": "add_member(obj: DocObject)",
|
||||
"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.renderers.mcp_renderer.DocObject.get_member",
|
||||
"signature": "get_member(name: str)",
|
||||
"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.renderers.mcp_renderer.DocObject.get_all_members",
|
||||
"signature": "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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Module": {
|
||||
"name": "Module",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mcp_renderer.Module",
|
||||
"signature": "Module(path: str, docstring: str | None = None)",
|
||||
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
|
||||
"members": {
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.Module.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.Module.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.Module.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_object": {
|
||||
"name": "add_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Module.add_object",
|
||||
"signature": "add_object(obj: DocObject)",
|
||||
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module."
|
||||
},
|
||||
"get_object": {
|
||||
"name": "get_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Module.get_object",
|
||||
"signature": "get_object(name: str)",
|
||||
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists."
|
||||
},
|
||||
"get_all_objects": {
|
||||
"name": "get_all_objects",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Module.get_all_objects",
|
||||
"signature": "get_all_objects()",
|
||||
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Project": {
|
||||
"name": "Project",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mcp_renderer.Project",
|
||||
"signature": "Project(name: str)",
|
||||
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (dict[str, Module]):\n Mapping of module paths to `Module` instances.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.Project.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"modules": {
|
||||
"name": "modules",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.Project.modules",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_module": {
|
||||
"name": "add_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Project.add_module",
|
||||
"signature": "add_module(module: Module)",
|
||||
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
|
||||
},
|
||||
"get_module": {
|
||||
"name": "get_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Project.get_module",
|
||||
"signature": "get_module(path: str)",
|
||||
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project."
|
||||
},
|
||||
"get_all_modules": {
|
||||
"name": "get_all_modules",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Project.get_all_modules",
|
||||
"signature": "get_all_modules()",
|
||||
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
|
||||
},
|
||||
"get_module_list": {
|
||||
"name": "get_module_list",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Project.get_module_list",
|
||||
"signature": "get_module_list()",
|
||||
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project."
|
||||
}
|
||||
}
|
||||
},
|
||||
"MCPRenderer": {
|
||||
"name": "MCPRenderer",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mcp_renderer.MCPRenderer",
|
||||
"signature": null,
|
||||
"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.renderers.mcp_renderer.MCPRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path) -> None",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"mkdocs_renderer": {
|
||||
"name": "mkdocs_renderer",
|
||||
"kind": "module",
|
||||
"path": "docforge.renderers.mkdocs_renderer",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nMkDocs renderer implementation.\n\nThis module defines the `MkDocsRenderer` class, which generates Markdown\ndocumentation sources compatible with MkDocs Material and the mkdocstrings\nplugin.\n\nThe renderer ensures a consistent documentation structure by:\n\n- Creating a root `index.md` if one does not exist\n- Generating package index pages automatically\n- Linking child modules within parent package pages\n- Optionally generating `README.md` from the root package docstring",
|
||||
"members": {
|
||||
"Module": {
|
||||
"name": "Module",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module",
|
||||
"signature": "Module(path: str, docstring: str | None = None)",
|
||||
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
|
||||
"members": {
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_object": {
|
||||
"name": "add_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module.add_object",
|
||||
"signature": "add_object(obj: DocObject)",
|
||||
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module."
|
||||
},
|
||||
"get_object": {
|
||||
"name": "get_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module.get_object",
|
||||
"signature": "get_object(name: str)",
|
||||
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists."
|
||||
},
|
||||
"get_all_objects": {
|
||||
"name": "get_all_objects",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module.get_all_objects",
|
||||
"signature": "get_all_objects()",
|
||||
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Project": {
|
||||
"name": "Project",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project",
|
||||
"signature": "Project(name: str)",
|
||||
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (dict[str, Module]):\n Mapping of module paths to `Module` instances.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"modules": {
|
||||
"name": "modules",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project.modules",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_module": {
|
||||
"name": "add_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project.add_module",
|
||||
"signature": "add_module(module: Module)",
|
||||
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
|
||||
},
|
||||
"get_module": {
|
||||
"name": "get_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project.get_module",
|
||||
"signature": "get_module(path: str)",
|
||||
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project."
|
||||
},
|
||||
"get_all_modules": {
|
||||
"name": "get_all_modules",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project.get_all_modules",
|
||||
"signature": "get_all_modules()",
|
||||
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
|
||||
},
|
||||
"get_module_list": {
|
||||
"name": "get_module_list",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project.get_module_list",
|
||||
"signature": "get_module_list()",
|
||||
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project."
|
||||
}
|
||||
}
|
||||
},
|
||||
"MkDocsRenderer": {
|
||||
"name": "MkDocsRenderer",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
|
||||
"signature": null,
|
||||
"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.renderers.mkdocs_renderer.MkDocsRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path, module_is_source: bool | None = None) -> None",
|
||||
"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.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme",
|
||||
"signature": "generate_readme(project: Project, docs_dir: Path, module_is_source: bool | None = None, readme_dir: Path | None = None) -> None",
|
||||
"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`."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
206
docs/mcp/modules/docforge.renderers.mcp_renderer.json
Normal file
206
docs/mcp/modules/docforge.renderers.mcp_renderer.json
Normal file
@@ -0,0 +1,206 @@
|
||||
{
|
||||
"module": "docforge.renderers.mcp_renderer",
|
||||
"content": {
|
||||
"path": "docforge.renderers.mcp_renderer",
|
||||
"docstring": "# Summary\n\nMCP renderer implementation.\n\nThis module defines the `MCPRenderer` class, which generates documentation\nresources compatible with the Model Context Protocol (MCP).",
|
||||
"objects": {
|
||||
"DocObject": {
|
||||
"name": "DocObject",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject",
|
||||
"signature": "DocObject(name: str, kind: str, path: str, signature: str | None = None, docstring: str | None = None)",
|
||||
"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.renderers.mcp_renderer.DocObject.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"kind": {
|
||||
"name": "kind",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject.kind",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"signature": {
|
||||
"name": "signature",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject.signature",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_member": {
|
||||
"name": "add_member",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.DocObject.add_member",
|
||||
"signature": "add_member(obj: DocObject)",
|
||||
"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.renderers.mcp_renderer.DocObject.get_member",
|
||||
"signature": "get_member(name: str)",
|
||||
"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.renderers.mcp_renderer.DocObject.get_all_members",
|
||||
"signature": "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."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Module": {
|
||||
"name": "Module",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mcp_renderer.Module",
|
||||
"signature": "Module(path: str, docstring: str | None = None)",
|
||||
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
|
||||
"members": {
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.Module.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.Module.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.Module.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_object": {
|
||||
"name": "add_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Module.add_object",
|
||||
"signature": "add_object(obj: DocObject)",
|
||||
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module."
|
||||
},
|
||||
"get_object": {
|
||||
"name": "get_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Module.get_object",
|
||||
"signature": "get_object(name: str)",
|
||||
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists."
|
||||
},
|
||||
"get_all_objects": {
|
||||
"name": "get_all_objects",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Module.get_all_objects",
|
||||
"signature": "get_all_objects()",
|
||||
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Project": {
|
||||
"name": "Project",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mcp_renderer.Project",
|
||||
"signature": "Project(name: str)",
|
||||
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (dict[str, Module]):\n Mapping of module paths to `Module` instances.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.Project.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"modules": {
|
||||
"name": "modules",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mcp_renderer.Project.modules",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_module": {
|
||||
"name": "add_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Project.add_module",
|
||||
"signature": "add_module(module: Module)",
|
||||
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
|
||||
},
|
||||
"get_module": {
|
||||
"name": "get_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Project.get_module",
|
||||
"signature": "get_module(path: str)",
|
||||
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project."
|
||||
},
|
||||
"get_all_modules": {
|
||||
"name": "get_all_modules",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Project.get_all_modules",
|
||||
"signature": "get_all_modules()",
|
||||
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
|
||||
},
|
||||
"get_module_list": {
|
||||
"name": "get_module_list",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.Project.get_module_list",
|
||||
"signature": "get_module_list()",
|
||||
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project."
|
||||
}
|
||||
}
|
||||
},
|
||||
"MCPRenderer": {
|
||||
"name": "MCPRenderer",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mcp_renderer.MCPRenderer",
|
||||
"signature": null,
|
||||
"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.renderers.mcp_renderer.MCPRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path) -> None",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
141
docs/mcp/modules/docforge.renderers.mkdocs_renderer.json
Normal file
141
docs/mcp/modules/docforge.renderers.mkdocs_renderer.json
Normal file
@@ -0,0 +1,141 @@
|
||||
{
|
||||
"module": "docforge.renderers.mkdocs_renderer",
|
||||
"content": {
|
||||
"path": "docforge.renderers.mkdocs_renderer",
|
||||
"docstring": "# Summary\n\nMkDocs renderer implementation.\n\nThis module defines the `MkDocsRenderer` class, which generates Markdown\ndocumentation sources compatible with MkDocs Material and the mkdocstrings\nplugin.\n\nThe renderer ensures a consistent documentation structure by:\n\n- Creating a root `index.md` if one does not exist\n- Generating package index pages automatically\n- Linking child modules within parent package pages\n- Optionally generating `README.md` from the root package docstring",
|
||||
"objects": {
|
||||
"Module": {
|
||||
"name": "Module",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module",
|
||||
"signature": "Module(path: str, docstring: str | None = None)",
|
||||
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
|
||||
"members": {
|
||||
"path": {
|
||||
"name": "path",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module.path",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"docstring": {
|
||||
"name": "docstring",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module.docstring",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"members": {
|
||||
"name": "members",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module.members",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_object": {
|
||||
"name": "add_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module.add_object",
|
||||
"signature": "add_object(obj: DocObject)",
|
||||
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module."
|
||||
},
|
||||
"get_object": {
|
||||
"name": "get_object",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module.get_object",
|
||||
"signature": "get_object(name: str)",
|
||||
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists."
|
||||
},
|
||||
"get_all_objects": {
|
||||
"name": "get_all_objects",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Module.get_all_objects",
|
||||
"signature": "get_all_objects()",
|
||||
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Project": {
|
||||
"name": "Project",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project",
|
||||
"signature": "Project(name: str)",
|
||||
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (dict[str, Module]):\n Mapping of module paths to `Module` instances.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"modules": {
|
||||
"name": "modules",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project.modules",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"add_module": {
|
||||
"name": "add_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project.add_module",
|
||||
"signature": "add_module(module: Module)",
|
||||
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
|
||||
},
|
||||
"get_module": {
|
||||
"name": "get_module",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project.get_module",
|
||||
"signature": "get_module(path: str)",
|
||||
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project."
|
||||
},
|
||||
"get_all_modules": {
|
||||
"name": "get_all_modules",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project.get_all_modules",
|
||||
"signature": "get_all_modules()",
|
||||
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
|
||||
},
|
||||
"get_module_list": {
|
||||
"name": "get_module_list",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Project.get_module_list",
|
||||
"signature": "get_module_list()",
|
||||
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project."
|
||||
}
|
||||
}
|
||||
},
|
||||
"MkDocsRenderer": {
|
||||
"name": "MkDocsRenderer",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
|
||||
"signature": null,
|
||||
"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.renderers.mkdocs_renderer.MkDocsRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
|
||||
"signature": "generate_sources(project: Project, out_dir: Path, module_is_source: bool | None = None) -> None",
|
||||
"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.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme",
|
||||
"signature": "generate_readme(project: Project, docs_dir: Path, module_is_source: bool | None = None, readme_dir: Path | None = None) -> None",
|
||||
"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`."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
78
docs/mcp/modules/docforge.servers.json
Normal file
78
docs/mcp/modules/docforge.servers.json
Normal file
@@ -0,0 +1,78 @@
|
||||
{
|
||||
"module": "docforge.servers",
|
||||
"content": {
|
||||
"path": "docforge.servers",
|
||||
"docstring": "# Summary\n\nServer layer for doc-forge.\n\nThis module exposes server implementations used to provide live access\nto generated documentation resources. Currently, it includes the MCP\ndocumentation server.\n\n---",
|
||||
"objects": {
|
||||
"MCPServer": {
|
||||
"name": "MCPServer",
|
||||
"kind": "class",
|
||||
"path": "docforge.servers.MCPServer",
|
||||
"signature": "MCPServer(mcp_root: Path, name: str)",
|
||||
"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.servers.MCPServer.mcp_root",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"app": {
|
||||
"name": "app",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.servers.MCPServer.app",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"run": {
|
||||
"name": "run",
|
||||
"kind": "function",
|
||||
"path": "docforge.servers.MCPServer.run",
|
||||
"signature": "run(transport: Literal['stdio', 'sse', 'streamable-http'] = 'streamable-http')",
|
||||
"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`."
|
||||
}
|
||||
}
|
||||
},
|
||||
"mcp_server": {
|
||||
"name": "mcp_server",
|
||||
"kind": "module",
|
||||
"path": "docforge.servers.mcp_server",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nMCP server implementation.\n\nThis module defines the `MCPServer` class, which serves pre-generated\ndocumentation bundles through the Model Context Protocol (MCP).\n\n---\n\nNotes:\n - The served bundle is generated offline by `MCPRenderer`.\n - Missing resources are reported as structured error dictionaries rather\n than raising exceptions.\n - The server exposes read-only resources and a single health-check tool.\n\n---",
|
||||
"members": {
|
||||
"MCPServer": {
|
||||
"name": "MCPServer",
|
||||
"kind": "class",
|
||||
"path": "docforge.servers.mcp_server.MCPServer",
|
||||
"signature": "MCPServer(mcp_root: Path, name: str)",
|
||||
"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.servers.mcp_server.MCPServer.mcp_root",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"app": {
|
||||
"name": "app",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.servers.mcp_server.MCPServer.app",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"run": {
|
||||
"name": "run",
|
||||
"kind": "function",
|
||||
"path": "docforge.servers.mcp_server.MCPServer.run",
|
||||
"signature": "run(transport: Literal['stdio', 'sse', 'streamable-http'] = 'streamable-http') -> None",
|
||||
"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`."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
39
docs/mcp/modules/docforge.servers.mcp_server.json
Normal file
39
docs/mcp/modules/docforge.servers.mcp_server.json
Normal file
@@ -0,0 +1,39 @@
|
||||
{
|
||||
"module": "docforge.servers.mcp_server",
|
||||
"content": {
|
||||
"path": "docforge.servers.mcp_server",
|
||||
"docstring": "# Summary\n\nMCP server implementation.\n\nThis module defines the `MCPServer` class, which serves pre-generated\ndocumentation bundles through the Model Context Protocol (MCP).\n\n---\n\nNotes:\n - The served bundle is generated offline by `MCPRenderer`.\n - Missing resources are reported as structured error dictionaries rather\n than raising exceptions.\n - The server exposes read-only resources and a single health-check tool.\n\n---",
|
||||
"objects": {
|
||||
"MCPServer": {
|
||||
"name": "MCPServer",
|
||||
"kind": "class",
|
||||
"path": "docforge.servers.mcp_server.MCPServer",
|
||||
"signature": "MCPServer(mcp_root: Path, name: str)",
|
||||
"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.servers.mcp_server.MCPServer.mcp_root",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"app": {
|
||||
"name": "app",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.servers.mcp_server.MCPServer.app",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"run": {
|
||||
"name": "run",
|
||||
"kind": "function",
|
||||
"path": "docforge.servers.mcp_server.MCPServer.run",
|
||||
"signature": "run(transport: Literal['stdio', 'sse', 'streamable-http'] = 'streamable-http') -> None",
|
||||
"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`."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
98
docs/mcp/nav.json
Normal file
98
docs/mcp/nav.json
Normal file
@@ -0,0 +1,98 @@
|
||||
[
|
||||
{
|
||||
"module": "docforge",
|
||||
"resource": "docs://modules/docforge"
|
||||
},
|
||||
{
|
||||
"module": "docforge.cli",
|
||||
"resource": "docs://modules/docforge.cli"
|
||||
},
|
||||
{
|
||||
"module": "docforge.cli.api_utils",
|
||||
"resource": "docs://modules/docforge.cli.api_utils"
|
||||
},
|
||||
{
|
||||
"module": "docforge.cli.commands",
|
||||
"resource": "docs://modules/docforge.cli.commands"
|
||||
},
|
||||
{
|
||||
"module": "docforge.cli.main",
|
||||
"resource": "docs://modules/docforge.cli.main"
|
||||
},
|
||||
{
|
||||
"module": "docforge.cli.mcp_utils",
|
||||
"resource": "docs://modules/docforge.cli.mcp_utils"
|
||||
},
|
||||
{
|
||||
"module": "docforge.cli.mkdocs_utils",
|
||||
"resource": "docs://modules/docforge.cli.mkdocs_utils"
|
||||
},
|
||||
{
|
||||
"module": "docforge.loaders",
|
||||
"resource": "docs://modules/docforge.loaders"
|
||||
},
|
||||
{
|
||||
"module": "docforge.loaders.griffe_loader",
|
||||
"resource": "docs://modules/docforge.loaders.griffe_loader"
|
||||
},
|
||||
{
|
||||
"module": "docforge.models",
|
||||
"resource": "docs://modules/docforge.models"
|
||||
},
|
||||
{
|
||||
"module": "docforge.models.module",
|
||||
"resource": "docs://modules/docforge.models.module"
|
||||
},
|
||||
{
|
||||
"module": "docforge.models.object",
|
||||
"resource": "docs://modules/docforge.models.object"
|
||||
},
|
||||
{
|
||||
"module": "docforge.models.project",
|
||||
"resource": "docs://modules/docforge.models.project"
|
||||
},
|
||||
{
|
||||
"module": "docforge.nav",
|
||||
"resource": "docs://modules/docforge.nav"
|
||||
},
|
||||
{
|
||||
"module": "docforge.nav.mkdocs",
|
||||
"resource": "docs://modules/docforge.nav.mkdocs"
|
||||
},
|
||||
{
|
||||
"module": "docforge.nav.resolver",
|
||||
"resource": "docs://modules/docforge.nav.resolver"
|
||||
},
|
||||
{
|
||||
"module": "docforge.nav.spec",
|
||||
"resource": "docs://modules/docforge.nav.spec"
|
||||
},
|
||||
{
|
||||
"module": "docforge.nav.wiki",
|
||||
"resource": "docs://modules/docforge.nav.wiki"
|
||||
},
|
||||
{
|
||||
"module": "docforge.renderers",
|
||||
"resource": "docs://modules/docforge.renderers"
|
||||
},
|
||||
{
|
||||
"module": "docforge.renderers.base",
|
||||
"resource": "docs://modules/docforge.renderers.base"
|
||||
},
|
||||
{
|
||||
"module": "docforge.renderers.mcp_renderer",
|
||||
"resource": "docs://modules/docforge.renderers.mcp_renderer"
|
||||
},
|
||||
{
|
||||
"module": "docforge.renderers.mkdocs_renderer",
|
||||
"resource": "docs://modules/docforge.renderers.mkdocs_renderer"
|
||||
},
|
||||
{
|
||||
"module": "docforge.servers",
|
||||
"resource": "docs://modules/docforge.servers"
|
||||
},
|
||||
{
|
||||
"module": "docforge.servers.mcp_server",
|
||||
"resource": "docs://modules/docforge.servers.mcp_server"
|
||||
}
|
||||
]
|
||||
98
docs/mkdocs.lib.yml
Normal file
98
docs/mkdocs.lib.yml
Normal file
@@ -0,0 +1,98 @@
|
||||
theme:
|
||||
name: material
|
||||
palette:
|
||||
- scheme: slate
|
||||
primary: deep purple
|
||||
accent: cyan
|
||||
font:
|
||||
text: Inter
|
||||
code: JetBrains Mono
|
||||
features:
|
||||
- navigation.sections
|
||||
- navigation.expand
|
||||
- navigation.top
|
||||
- navigation.instant
|
||||
- navigation.tracking
|
||||
- navigation.indexes
|
||||
- content.code.copy
|
||||
- content.code.annotate
|
||||
- content.tabs.link
|
||||
- content.action.edit
|
||||
- search.highlight
|
||||
- search.share
|
||||
- search.suggest
|
||||
icon:
|
||||
logo: material/file-document-multiple
|
||||
repo: fontawesome/brands/github
|
||||
markdown_extensions:
|
||||
- pymdownx.superfences
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.snippets
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
- pymdownx.highlight:
|
||||
linenums: true
|
||||
anchor_linenums: true
|
||||
line_spans: __span
|
||||
pygments_lang_class: true
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- tables
|
||||
- footnotes
|
||||
- pymdownx.caret
|
||||
- pymdownx.tilde
|
||||
- pymdownx.mark
|
||||
extra_css:
|
||||
- https://unpkg.com/dracula-prism/dist/css/dracula-prism.css
|
||||
plugins:
|
||||
- search
|
||||
- mkdocstrings:
|
||||
handlers:
|
||||
python:
|
||||
paths:
|
||||
- ..
|
||||
options:
|
||||
docstring_style: google
|
||||
show_source: false
|
||||
show_signature_annotations: true
|
||||
separate_signature: true
|
||||
merge_init_into_class: true
|
||||
inherited_members: true
|
||||
annotations_path: brief
|
||||
show_root_heading: true
|
||||
group_by_category: true
|
||||
show_category_heading: true
|
||||
show_object_full_path: false
|
||||
show_symbol_type_heading: true
|
||||
site_name: docforge
|
||||
docs_dir: lib
|
||||
site_dir: ../site/lib
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Loaders:
|
||||
- loaders/index.md
|
||||
- loaders/griffe_loader.md
|
||||
- Models:
|
||||
- models/index.md
|
||||
- models/module.md
|
||||
- models/object.md
|
||||
- models/project.md
|
||||
- Navigation:
|
||||
- nav/index.md
|
||||
- nav/spec.md
|
||||
- nav/resolver.md
|
||||
- nav/mkdocs.md
|
||||
- Renderers:
|
||||
- renderers/index.md
|
||||
- renderers/base.md
|
||||
- renderers/mkdocs_renderer.md
|
||||
- renderers/mcp_renderer.md
|
||||
- CLI:
|
||||
- cli/index.md
|
||||
- cli/main.md
|
||||
- cli/commands.md
|
||||
- cli/api_utils.md
|
||||
- cli/mcp_utils.md
|
||||
- cli/mkdocs_utils.md
|
||||
73
docs/mkdocs.wiki.yml
Normal file
73
docs/mkdocs.wiki.yml
Normal file
@@ -0,0 +1,73 @@
|
||||
theme:
|
||||
name: material
|
||||
palette:
|
||||
scheme: slate
|
||||
primary: blue grey
|
||||
accent: teal
|
||||
font:
|
||||
text: Roboto
|
||||
code: JetBrains Mono
|
||||
features:
|
||||
- navigation.sections
|
||||
- navigation.expand
|
||||
- navigation.top
|
||||
- navigation.instant
|
||||
- navigation.tracking
|
||||
- navigation.indexes
|
||||
- content.code.copy
|
||||
- content.code.annotate
|
||||
- content.tabs.link
|
||||
- content.action.edit
|
||||
- search.highlight
|
||||
- search.share
|
||||
- search.suggest
|
||||
- navigation.tabs
|
||||
- toc.integrate
|
||||
- header.autohide
|
||||
- announce.dismiss
|
||||
- footer.social
|
||||
- content.code.select
|
||||
- content.code.line_numbers
|
||||
- content.tooltips
|
||||
icon:
|
||||
logo: material/file-document-multiple
|
||||
repo: fontawesome/brands/github
|
||||
markdown_extensions:
|
||||
- pymdownx.superfences
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.snippets
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
- pymdownx.highlight:
|
||||
linenums: true
|
||||
anchor_linenums: true
|
||||
line_spans: __span
|
||||
pygments_lang_class: true
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- tables
|
||||
- footnotes
|
||||
- pymdownx.caret
|
||||
- pymdownx.tilde
|
||||
- pymdownx.mark
|
||||
extra_css:
|
||||
- https://unpkg.com/dracula-prism/dist/css/dracula-prism.css
|
||||
plugins:
|
||||
- search
|
||||
site_name: doc-forge
|
||||
docs_dir: wiki
|
||||
site_dir: ../site/wiki
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Overview: 01_overview.md
|
||||
- Components: 02_components.md
|
||||
- Conventions: 03_conventions.md
|
||||
- Iterative Workflow: 04_iterative_workflow.md
|
||||
- Development:
|
||||
- Environment: 05_development/01_environment.md
|
||||
- Quality Gates: 05_development/02_quality_gates.md
|
||||
- GSDFC Guide: 05_development/03_gsdfc_guide.md
|
||||
- MCP Guide: 05_development/04_mcp_guide.md
|
||||
- MkDocs Configs: 05_development/05_mkdocs_configs.md
|
||||
43
docs/wiki/01_overview.md
Normal file
43
docs/wiki/01_overview.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Library Overview
|
||||
|
||||
`docforge` turns GSDFC-compliant Python docstrings into maintainable reference
|
||||
documentation. It never edits source docstrings; it reads them, renders them,
|
||||
and assembles documentation sites from all available material.
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Which Build Should You Use?
|
||||
|
||||
| Kind | Source | Output |
|
||||
|-----------|----------------------------|---------------------------------|
|
||||
| `lib` | GSDFC docstrings | `docs/lib/**` rendered markdown |
|
||||
| `api` | OpenAPI JSON spec | `docs/api/**` rendered markdown |
|
||||
| `wiki` | Hand-written markdown | `docs/wiki/**` (unchanged) |
|
||||
| `mcp` | GSDFC docstrings + renderers | `docs/mcp/**` structured JSON |
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
Each enabled site kind produces its own MkDocs configuration and build:
|
||||
|
||||
1. `--mkdocs` (lib) writes `docs/mkdocs.lib.yml` and builds `site/lib/`.
|
||||
2. `--api` writes `docs/mkdocs.api.yml` and builds `site/api/`.
|
||||
3. `--wiki` writes `docs/mkdocs.wiki.yml` and builds `site/wiki/`.
|
||||
|
||||
Every site is self-contained (own theme assets and search index) with
|
||||
navigation derived or scoped to that kind. Hand-written wiki content is never
|
||||
overwritten or regenerated — only its navigation is derived automatically.
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Lifecycle Rules
|
||||
|
||||
`docs/mcp/**` is a self-contained, machine-readable reference generated from
|
||||
docforge's own GSDFC docstrings. `doc-forge serve --mcp --module docforge`
|
||||
serves it over MCP. See the [MCP Guide](05_development/04_mcp_guide.md).
|
||||
|
||||
---
|
||||
|
||||
## ➡️ Read Next
|
||||
- [02 – Components](02_components.md) · [03 – Conventions](03_conventions.md)
|
||||
55
docs/wiki/02_components.md
Normal file
55
docs/wiki/02_components.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# Components
|
||||
|
||||
`docforge` is split into four horizontal layers. Everything flows top to
|
||||
bottom through the CLI.
|
||||
|
||||
---
|
||||
|
||||
## 1. Loaders & Models
|
||||
|
||||
The `docforge/loaders` package wraps `griffe` to extract modules, functions,
|
||||
classes, and Google-style docstring sections. Loaded data is normalized into
|
||||
the object model under `docforge/models` (`Project`, `Module`, `DocObject`).
|
||||
|
||||
---
|
||||
|
||||
## 2. Navigation
|
||||
|
||||
`docforge/nav` parses `docforge.nav.yml` specs (`NavSpec`, `Resolver`, and the
|
||||
MkDocs nav emitter) and, since the wiki kind, derives wiki navigation from the
|
||||
file structure via `build_wiki_nav`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Renderers
|
||||
|
||||
`docforge/renderers` turn model data into artifacts:
|
||||
|
||||
- `MkDocsRenderer` → `docs/lib/**` reference markdown
|
||||
- `MCPRenderer` → `docs/mcp/**` structured documentation
|
||||
|
||||
---
|
||||
|
||||
## 4. Servers
|
||||
|
||||
`docforge/servers` serves generated artifacts over live protocols:
|
||||
|
||||
- `MCPServer` → serves a pre-generated `docs/mcp/**` bundle through MCP
|
||||
resources (`docs://index`, `docs://nav`, `docs://modules/{module}`)
|
||||
|
||||
---
|
||||
|
||||
## 5. CLI
|
||||
|
||||
`docforge/cli` wires it all together:
|
||||
|
||||
- `commands.py` — the `build` command and its `--mkdocs` / `--api` / `--wiki`
|
||||
/ `--mcp` modes
|
||||
- `mkdocs_utils.py` — per-kind config generation (`docs/mkdocs.{lib,api,wiki}.yml`)
|
||||
with navigation re-rooted to each kind's `docs_dir`
|
||||
- `api_utils.py` — OpenAPI loading and API docs generation
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
- [01 – Overview](01_overview.md) · [03 – Conventions](03_conventions.md)
|
||||
58
docs/wiki/03_conventions.md
Normal file
58
docs/wiki/03_conventions.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# Conventions
|
||||
|
||||
---
|
||||
|
||||
## GSDFC docstrings
|
||||
|
||||
All documented source uses the Google-Styled Doc-Forge Convention (GSDFC):
|
||||
`Args:`, `Returns:`, `Raises:`, and `Attributes:` sections with properly typed
|
||||
signatures.
|
||||
|
||||
The authoritative GSDFC specification lives in the `docforge/__init__.py`
|
||||
package docstring, which is exported verbatim into
|
||||
`docs/mcp/modules/docforge.json`, so the MCP bundle is self-documenting.
|
||||
|
||||
Key rules:
|
||||
|
||||
1. Use parenthesized types in prose entries (`name (Type):`) that match the
|
||||
signature types.
|
||||
2. Use `# Summary`, `# Examples`, and `# Notes` sections at module level.
|
||||
3. Use `Args:`, `Returns:`, `Raises:`, `Yields:`, `Notes:`, and `Example:`
|
||||
sections at function and method level.
|
||||
4. Always update the matching `.pyi` stub alongside the `.py` implementation.
|
||||
5. Every distributable package ships a `py.typed` marker so type checkers
|
||||
consume the authored signatures instead of `Any`.
|
||||
|
||||
---
|
||||
|
||||
## `.pyi` stubs and `py.typed`
|
||||
|
||||
Every module ships a matching `.pyi` stub kept in sync with the `.py`
|
||||
implementation. When signatures change, update both files. Packages expose a
|
||||
`py.typed` marker so consumers and type checkers use the authored signatures.
|
||||
|
||||
---
|
||||
|
||||
## Wiki pages
|
||||
|
||||
1. Hand-written markdown lives in `docs/wiki/**` and is never generated.
|
||||
2. File names use a numeric prefix: `01_overview.md`, `02_components.md`.
|
||||
3. Nested directories become nested navigation groups:
|
||||
`05_development/01_environment.md` → group *Development*.
|
||||
4. `index.md` is the site `Home` at the root, and a section root inside a
|
||||
directory.
|
||||
5. Navigation labels are derived by stripping the numeric prefix and applying
|
||||
title case on the remaining words.
|
||||
|
||||
---
|
||||
|
||||
## Templates
|
||||
|
||||
MkDocs config fragments live in `docforge/templates`. The `mkdocs.wiki.yml`
|
||||
fragment carries only the `search` plugin, since wiki pages contain no
|
||||
mkdocstrings directives.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
- [02 – Components](02_components.md) · [04 – Iterative Workflow](04_iterative_workflow.md)
|
||||
61
docs/wiki/04_iterative_workflow.md
Normal file
61
docs/wiki/04_iterative_workflow.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# Iterative Workflow
|
||||
|
||||
A docs build runs through the CLI in a single pass.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Build commands
|
||||
|
||||
```bash
|
||||
# Library reference only
|
||||
doc-forge build --mkdocs --module docforge
|
||||
|
||||
# Wiki + library (each an independent MkDocs build)
|
||||
doc-forge build --wiki --mkdocs --module docforge
|
||||
|
||||
# Wiki only — no module required
|
||||
doc-forge build --wiki --site-name docforge
|
||||
|
||||
# MCP structured bundle
|
||||
doc-forge build --mcp --module docforge
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 What a build does
|
||||
|
||||
1. Validates the requested modes (`--mkdocs`, `--api`, `--wiki`, `--mcp`).
|
||||
2. Generates library sources under `docs/lib/**` with `MkDocsRenderer`.
|
||||
3. Generates API sources under `docs/api/**` when `--api` is given.
|
||||
4. Derives the wiki navigation from `docs/wiki/**`.
|
||||
5. Writes one MkDocs config per site kind (`docs/mkdocs.{lib,api,wiki}.yml`),
|
||||
re-rooting navigation paths to each kind's `docs_dir`.
|
||||
6. Runs `mkdocs build` once per config, emitting self-contained sites
|
||||
`site/lib/`, `site/api/`, and `site/wiki/`.
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Explore the sites
|
||||
|
||||
```bash
|
||||
doc-forge build --wiki --mkdocs --module docforge
|
||||
doc-forge serve --wiki # serves site preview from docs/mkdocs.wiki.yml
|
||||
doc-forge serve --lib
|
||||
doc-forge serve --api
|
||||
# or target any config directly:
|
||||
doc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Serve the MCP bundle
|
||||
|
||||
```bash
|
||||
doc-forge build --mcp --module docforge
|
||||
doc-forge serve --mcp --module docforge
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
- [03 – Conventions](03_conventions.md) · [01 – Environment](05_development/01_environment.md)
|
||||
30
docs/wiki/05_development/01_environment.md
Normal file
30
docs/wiki/05_development/01_environment.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# Environment Setup
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Create the environment
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
.venv\Scripts\activate
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
Requires Python 3.10+ (per `pyproject.toml`).
|
||||
|
||||
---
|
||||
|
||||
## 📦 Dependencies
|
||||
|
||||
Development extras include:
|
||||
|
||||
- `pytest`, `pytest-cov` — test suite and coverage
|
||||
- `ruff` — lint and format checking
|
||||
- `black` — auto-formatting
|
||||
- `mypy` — strict typing checks
|
||||
- `pydoclint` — docstring ↔ signature consistency checks
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
- [04 – Iterative Workflow](../04_iterative_workflow.md) · [02 – Quality Gates](02_quality_gates.md)
|
||||
34
docs/wiki/05_development/02_quality_gates.md
Normal file
34
docs/wiki/05_development/02_quality_gates.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Quality Gates
|
||||
|
||||
Run all checks before pushing:
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Commands
|
||||
|
||||
```bash
|
||||
.venv\Scripts\python.exe -m pytest
|
||||
.venv\Scripts\python.exe -m ruff check docforge tests
|
||||
.venv\Scripts\python.exe -m black --check docforge tests
|
||||
.venv\Scripts\python.exe -m mypy docforge
|
||||
.venv\Scripts\pydoclint.exe docforge
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 Test layout
|
||||
|
||||
| Path | Covers |
|
||||
|--------------------------|------------------------------------|
|
||||
| `tests/nav/` | Nav spec, resolver, wiki nav |
|
||||
| `tests/cli/` | Build command flows and modes |
|
||||
| `tests/renderers/` | MkDocs / MCP rendering |
|
||||
|
||||
CLI tests use the `cli_runner` fixture with `mock_mkdocs_build` and
|
||||
`mock_mkdocs_load_config` so they exercise the full flow without invoking a
|
||||
real MkDocs build.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
- [01 – Environment](01_environment.md) · [03 – GSDFC Guide](03_gsdfc_guide.md)
|
||||
129
docs/wiki/05_development/03_gsdfc_guide.md
Normal file
129
docs/wiki/05_development/03_gsdfc_guide.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# GSDFC Docstring Guide
|
||||
|
||||
This page is the practical companion to the authoritative GSDFC specification
|
||||
in the `docforge/__init__.py` package docstring. It describes how to write
|
||||
docstrings that render correctly in MkDocs and stay machine-parseable by
|
||||
doc-forge, MkDocs, and MCP clients.
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Overview
|
||||
|
||||
- Docstrings are the single source of truth.
|
||||
- `doc-forge` compiles docstrings but never rewrites them.
|
||||
- Every public symbol should have a complete, accurate docstring.
|
||||
- Type hints live in signatures; prose entries repeat the type in
|
||||
parentheses and must match the signature.
|
||||
|
||||
---
|
||||
|
||||
## 📦 Module docstrings
|
||||
|
||||
Modules use Markdown headings and `---` separators.
|
||||
|
||||
Recommended sections:
|
||||
|
||||
- `# Summary` — what the subsystem does
|
||||
- `# Examples` — a representative usage snippet
|
||||
- `# Notes` — guarantees, lifecycle, and thread-safety notes
|
||||
|
||||
---
|
||||
|
||||
## 📦 Class docstrings
|
||||
|
||||
Recommended sections, in order:
|
||||
|
||||
- summary line describing responsibility
|
||||
- `Attributes:` — instance attributes with `name (Type):` entries
|
||||
- `Notes:` — grouped subsections such as **Guarantees**, **Lifecycle**
|
||||
- `Example:` — indented `python` code block
|
||||
|
||||
---
|
||||
|
||||
## 📦 Function and method docstrings
|
||||
|
||||
Recommended section order:
|
||||
|
||||
1. `Args:`
|
||||
2. `Returns:`
|
||||
3. `Raises:`
|
||||
4. `Yields:`
|
||||
5. `Notes:`
|
||||
6. `Example:`
|
||||
|
||||
Formatting rules:
|
||||
|
||||
- `Args:` entries are `name (Type):` followed by an indented description.
|
||||
- `Returns:` entries are `Type:` followed by an indented description.
|
||||
- `Raises:` entries are `ExceptionType:` followed by an indented condition.
|
||||
- `Yields:` replaces `Returns:` for generators.
|
||||
- Summaries are written in the imperative mood.
|
||||
- Fenced `python` blocks are allowed inside `Example:` sections, indented
|
||||
four spaces.
|
||||
|
||||
---
|
||||
|
||||
## 📦 Property docstrings
|
||||
|
||||
Properties document their return values with a `Returns:` section and, when
|
||||
meaningful, an `Example:`.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Example
|
||||
|
||||
```python
|
||||
def process(foo: Foo, multiplier: int) -> int:
|
||||
"""Process a Foo instance.
|
||||
|
||||
Args:
|
||||
foo (Foo):
|
||||
Foo instance to process.
|
||||
|
||||
multiplier (int):
|
||||
Value used to scale foo.
|
||||
|
||||
Returns:
|
||||
int:
|
||||
Processed result.
|
||||
|
||||
Raises:
|
||||
ValueError:
|
||||
If multiplier is negative.
|
||||
|
||||
Example:
|
||||
Process foo:
|
||||
|
||||
```python
|
||||
foo = Foo("example", value=10)
|
||||
result = process(foo, multiplier=2)
|
||||
print(result)
|
||||
```
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Keeping stubs in sync
|
||||
|
||||
Every `.py` module ships a matching `.pyi` stub. When a signature or a public
|
||||
symbol changes, update both files. Signature annotations in the stub must
|
||||
match the implementation.
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Enforcement
|
||||
|
||||
`pydoclint` (Google style) runs in CI and verifies that `Args:`/`Returns:`
|
||||
sections match function signatures, including types.
|
||||
|
||||
- `allow-init-docstring = true` — `__init__` docstrings are allowed.
|
||||
- `skip-checking-raises = true` — `Raises:` sections are descriptive and are
|
||||
not required to map to literal `raise` statements.
|
||||
- `check-class-attributes = false` — `Attributes:` sections document instance
|
||||
attributes without class-level annotations.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
- [02 – Quality Gates](02_quality_gates.md) · [04 – MCP Guide](04_mcp_guide.md)
|
||||
62
docs/wiki/05_development/04_mcp_guide.md
Normal file
62
docs/wiki/05_development/04_mcp_guide.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# MCP Guide
|
||||
|
||||
Doc-forge can export a machine-readable **MCP bundle** from a project's
|
||||
GSDFC docstrings and serve that bundle over the Model Context Protocol (MCP).
|
||||
The bundle is self-contained: readers can derive the full API reference —
|
||||
signatures, docstrings, and structure — for the documented project.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Building the bundle
|
||||
|
||||
```bash
|
||||
doc-forge build --mcp --module docforge
|
||||
```
|
||||
|
||||
This writes structured JSON into `docs/mcp/`:
|
||||
|
||||
- `index.json` — project metadata and module count
|
||||
- `nav.json` — module list with `docs://modules/{module}` resource URIs
|
||||
- `modules/{dotted.path}.json` — per-module serialized documentation
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Serving the bundle
|
||||
|
||||
```bash
|
||||
doc-forge serve --mcp --module docforge
|
||||
```
|
||||
|
||||
The `MCPServer` (in `docforge/servers/mcp_server.py`) exposes:
|
||||
|
||||
| Resource | Description |
|
||||
|----------------------|-----------------------------------|
|
||||
| `docs://index` | Project metadata |
|
||||
| `docs://nav` | Navigation structure |
|
||||
| `docs://modules/{module}` | Individual module documentation |
|
||||
|
||||
The server also registers a single diagnostic tool, `ping`, and is read-only.
|
||||
Missing resources are returned as structured error dictionaries rather than
|
||||
exceptions. The default transport is `streamable-http`; `stdio` and `sse` are
|
||||
supported via `MCPServer.run`.
|
||||
|
||||
---
|
||||
|
||||
## 📦 Bundle contents
|
||||
|
||||
Each module resource contains:
|
||||
|
||||
- `path` — dotted module path
|
||||
- `docstring` — the raw GSDFC module docstring
|
||||
- `objects` — a recursive mapping of public symbols with `name`, `kind`,
|
||||
`path`, `signature`, and `docstring`, plus nested `members`
|
||||
|
||||
Because the bundle is generated from docstrings, the quality of the bundle
|
||||
equals the quality of the project's GSDFC docstrings. For docforge itself,
|
||||
the GSDFC specification is carried in `modules/docforge.json` via the
|
||||
`docforge/__init__.py` package docstring, making the bundle self-documenting.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
- [03 – GSDFC Guide](03_gsdfc_guide.md) · [05 – MkDocs Configs](05_mkdocs_configs.md)
|
||||
59
docs/wiki/05_development/05_mkdocs_configs.md
Normal file
59
docs/wiki/05_development/05_mkdocs_configs.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# MkDocs Configuration Model
|
||||
|
||||
Each documentation kind (lib, api, wiki) is built by its own MkDocs site. A
|
||||
repo that documents kind `{kind}` carries a config at `docs/mkdocs.{kind}.yml`
|
||||
that sets `docs_dir` to the kind's source directory and `site_dir` to
|
||||
`../site/{kind}`.
|
||||
|
||||
---
|
||||
|
||||
## 📄 File wins
|
||||
|
||||
`docs/mkdocs.{kind}.yml` is a repo-owned file, not a build byproduct:
|
||||
|
||||
- **Absent** — `doc-forge build --{kind}` materializes a copy from the
|
||||
packaged templates (see below) and then builds `site/{kind}`.
|
||||
- **Present** — the build uses the file verbatim. Edits to the theme, palette,
|
||||
plugins, markdown extensions, nav, or `site_dir` are respected as-is.
|
||||
- **`--refresh`** — force-regenerates the file from the templates,
|
||||
replacing any local changes.
|
||||
|
||||
Because a present file is never rewritten, rerunning a build is a no-op for
|
||||
versioned configs: the working tree stays clean.
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Templates
|
||||
|
||||
The built-in defaults live in `docforge/templates/`:
|
||||
|
||||
| File | Role |
|
||||
|-----------------------|-----------------------------------------------|
|
||||
| `mkdocs.common.yml` | Shared theme + markdown extensions |
|
||||
| `mkdocs.lib.yml` | `mkdocstrings` handler for library reference |
|
||||
| `mkdocs.api.yml` | Swagger/OpenAPI plugins and API-side features |
|
||||
| `mkdocs.wiki.yml` | Wiki look: horizontal `navigation.tabs` header, blue grey/teal palette, Roboto |
|
||||
|
||||
A per-kind config is generated by deep-merging the common template with the
|
||||
kind fragment, then filling in generation-time values (`site_name`,
|
||||
`docs_dir`, `site_dir`, `nav`, API `site_description`/`site_author`, and the
|
||||
theme `icon` from `docforge.nav.yml`). Pass `--template <path>` to replace the
|
||||
built-in templates entirely.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Supported layouts
|
||||
|
||||
- **Per-kind config** — the standard layout; each kind builds to
|
||||
`site/{kind}` and is served under `/<repo>/{kind}/`.
|
||||
- **Legacy root config** — a repo with a single kind may instead author root
|
||||
`mkdocs.yml` (for example mongo-ops, whose wiki uses `docs_dir: docs/wiki`).
|
||||
doc-forge never reads or writes root `mkdocs.yml`; the docs service maps the
|
||||
kind to the root `site/` dir in this case.
|
||||
|
||||
Commit `docs/mkdocs.{kind}.yml` so served docs are reproducible from source.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
- [04 – MCP Guide](04_mcp_guide.md)
|
||||
325
docs/wiki/index.md
Normal file
325
docs/wiki/index.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# 🧩 docforge — Docstring-Driven Documentation Forge
|
||||
|
||||
`docforge` is an internal documentation tool that generates reference documentation from Google-Styled Doc-Forge Convention (GSDFC) docstrings and assembles it into per-kind MkDocs sites, alongside hand-written wiki pages and OpenAPI-based API docs.
|
||||
|
||||
> **Doc model:** this wiki is written for humans — how‑to guides, examples,
|
||||
> and testing recipes. The authoritative API contracts live in the code
|
||||
> (docstrings) and the machine‑readable bundle under `docs/mcp/`.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Key Features
|
||||
|
||||
- 🧪 GSDFC docstring extraction via Griffe
|
||||
- 🧭 Auto-derived navigation for hand-written wiki pages
|
||||
- 🗂 Independent MkDocs builds per kind (lib, api, wiki) into `site/{kind}`
|
||||
- 🔌 Material MkDocs theming out of the box
|
||||
- 📦 MCP structured documentation resources
|
||||
|
||||
---
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
```bash
|
||||
# Internal PyPI (TBD)
|
||||
pip install docforge
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 Documentation Structure
|
||||
|
||||
| Section | Description |
|
||||
|----------------------------------------------| -------------------------------------------------- |
|
||||
| [Overview](01_overview.md) | What docforge is and how it fits the pipeline |
|
||||
| [Components](02_components.md) | Loaders, models, nav, renderers, CLI, servers |
|
||||
| [Conventions](03_conventions.md) | GSDFC, `.pyi` stubs, and template conventions |
|
||||
| [Iterative Workflow](04_iterative_workflow.md) | How a docs build runs end to end |
|
||||
| [Environment](05_development/01_environment.md) | Environment setup |
|
||||
| [Quality Gates](05_development/02_quality_gates.md) | Test layout and quality checks |
|
||||
| [GSDFC Guide](05_development/03_gsdfc_guide.md) | How to write GSDFC-conformant docstrings |
|
||||
| [MCP Guide](05_development/04_mcp_guide.md) | Building, serving, and consuming the MCP bundle |
|
||||
| [MkDocs Configs](05_development/05_mkdocs_configs.md) | MkDocs config generation and templates |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Resources
|
||||
|
||||
- **Source Code:** the `doc-forge` repository
|
||||
- **MCP Bundle:** generated by `doc-forge build --mcp --module docforge` into `docs/mcp/`
|
||||
- **Wiki Kind:** hand-written content lives in `docs/wiki/`; use the prompt in the
|
||||
wiki-related resource below
|
||||
````markdown
|
||||
# AGENTS.md — Wiki Authoring Guide (Aetoskia)
|
||||
|
||||
This file instructs AI agents how to create, extend, and maintain the wiki
|
||||
(`docs/wiki/**`) for any Aetoskia repository.
|
||||
|
||||
> **Workflow:** this prompt covers **phase 2 only**. Phase 1 — writing GSDFC docstrings
|
||||
> (plus `.pyi` stubs and `py.typed`) — is done by the agent using the doc-forge MCP
|
||||
> bundle: `doc://modules/docforge` carries the full GSDFC spec. Write the wiki only
|
||||
> after docstrings exist and `doc-forge build --mcp --module <pkg>` produced the
|
||||
> repo's own bundle.
|
||||
|
||||
---
|
||||
|
||||
## 1. Doc model — know the two sources of truth
|
||||
|
||||
Every repo keeps two distinct kinds of documentation that must **not** bleed
|
||||
into each other:
|
||||
|
||||
| Kind | Source | Where | Audience |
|
||||
|-------------------|-----------------------|------------------------------------------|------------------------------------|
|
||||
| **Wiki** | Hand-written markdown | `docs/wiki/**` | Humans (how-to, examples, testing) |
|
||||
| **API reference** | Docstrings (GSDFC) | Generated → `docs/lib/**`, `docs/mcp/**` | Consumers (exact contracts) |
|
||||
|
||||
Rules:
|
||||
|
||||
- The wiki is written **for humans** — how-to guides, recipes, and testing
|
||||
patterns. It is never generated.
|
||||
- API contracts (signatures, parameter types, exact behavior) live in the
|
||||
docstrings and the machine-readable bundle under `docs/mcp/`. **Never**
|
||||
duplicate full API documentation in the wiki — link to the lib site instead.
|
||||
- If a page starts to drift into contract territory, cut it down to usage and
|
||||
point at `docs/lib/`.
|
||||
- This doc model is stated on every index page as a blockquote; keep it there:
|
||||
> **Doc model:** this wiki is written for humans — how‑to guides, examples,
|
||||
> and testing recipes. The authoritative API contracts live in the code
|
||||
> (docstrings) and the machine‑readable bundle under `docs/mcp/`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Directory layout & file naming
|
||||
|
||||
```
|
||||
docs/wiki/
|
||||
├── index.md # site Home
|
||||
├── 01_overview.md
|
||||
├── 02_components.md
|
||||
├── 03_use_cases/ # nested directory → nav group
|
||||
│ ├── 01_basic_crud.md
|
||||
│ ├── 02_custom_repo.md
|
||||
│ └── ...
|
||||
├── 04_best_practices.md
|
||||
├── 06_error_handling.md
|
||||
└── 07_testing_example.md
|
||||
```
|
||||
|
||||
- Location: `docs/wiki/` (hand-written only).
|
||||
- File names: `NN_snake_case_name.md` with a **zero-padded two-digit** numeric
|
||||
prefix. e.g. `01_overview.md`, `03_use_cases/07_caching.md`.
|
||||
- Top-level pages use `NN_name.md` directly. High-volume sections get their own
|
||||
directory, e.g. `03_use_cases/NN_name.md` (nav group "Use Cases").
|
||||
- **No frontmatter.** Every file opens directly with an H1 `# Title`.
|
||||
- Navigation labels are short human titles set explicitly in
|
||||
`docs/mkdocs.wiki.yml` (title case) — often **shorter** than the page H1.
|
||||
Example: nav label `Basic CRUD` vs page H1 `Use Case 1: Basic FastAPI CRUD API`.
|
||||
Never use the raw filename slug as the label.
|
||||
- Renumbering: prefixes order pages. When inserting a page, pick the next
|
||||
number in the relevant group (subgroup numbers stay grouped).
|
||||
|
||||
---
|
||||
|
||||
## 3. Navigation — `docs/mkdocs.wiki.yml` is the source of truth
|
||||
|
||||
Every wiki page **must** be wired into the nav defined in
|
||||
`docs/mkdocs.wiki.yml`. If a page is not in the nav, it is orphaned.
|
||||
|
||||
- The `nav:` block mirrors the directory tree; directories become nested
|
||||
groups.
|
||||
- When a section has many pages, group them **by theme** into nested
|
||||
subgroups. mongo-ops groups its use cases into:
|
||||
`Getting Started`, `Data & Queries`, `Caching`, `Population`,
|
||||
`Advanced Usage`.
|
||||
- Keep `index.md`'s **Documentation Structure** table in sync with the nav —
|
||||
it is the human-facing version of the same TOC. Every nav entry needs a row
|
||||
(or nested bullet group) there.
|
||||
- Nav label = human title (title case), not the filename slug.
|
||||
|
||||
---
|
||||
|
||||
## 4. Page anatomy
|
||||
|
||||
### 4.1 `index.md` (Home)
|
||||
|
||||
```
|
||||
# 🧩 <package> — <slogan>
|
||||
<one-paragraph pitch>
|
||||
|
||||
> **Doc model:** … (see §1)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Key Features (bullet list, emoji per feature)
|
||||
## 📦 Installation (code blocks: internal PyPI, extras, local source)
|
||||
## 📁 Documentation Structure (table = TOC, mirrors nav exactly)
|
||||
## 🔗 Related Resources (bullets: source repo, internal PyPI, CI)
|
||||
---
|
||||
© Aetoskia Internal — `<package>` <version>
|
||||
```
|
||||
|
||||
### 4.2 Overview page (`01_*`)
|
||||
|
||||
- Opens with `# Library Overview`, one sentence about what the library does,
|
||||
then a line stating the page builds the mental model.
|
||||
- Sections: `## 🏗️ Architecture` (ASCII diagram + numbered layer list),
|
||||
`## 🔄 Lifecycle Rules` (table: step / call / why),
|
||||
`## 🧭 Which … Should You Use?` (decision table).
|
||||
- Ends with `## ➡️ Read Next` (cross-links to the next pages to read).
|
||||
|
||||
### 4.3 Components page (`02_*`)
|
||||
|
||||
- Validated reference for the public API surface — describes what each
|
||||
component is for and how the pieces wire together. Keep it usage-level;
|
||||
exact signatures belong in `docs/lib/`.
|
||||
- Anatomy: numbered sections, one per component (`## 1. MongoConnectionManager`,
|
||||
`## 2. BaseDocument`, …), with `### 8.1`-style sub-numbering for related
|
||||
types under a component (e.g. the cache layer's backend / stats / config /
|
||||
in-memory / redis implementations). Ends with `## Related`.
|
||||
|
||||
### 4.4 Use-case page (the most common)
|
||||
|
||||
Standard anatomy, in this order:
|
||||
|
||||
```
|
||||
# Use Case N: <Human Title>
|
||||
|
||||
**Scenario:** <one sentence: the problem this recipe solves>
|
||||
|
||||
---
|
||||
|
||||
## 📦 What's New? (table: Component | Description — new API used here)
|
||||
## 🚀 Example (languaged code block, complete runnable-looking snippet)
|
||||
## 💡 Tips (bullets: gotchas, ordering, common mistakes)
|
||||
## Related (§5)
|
||||
```
|
||||
|
||||
### 4.5 Deep-dive / worked-example page
|
||||
|
||||
For intricate flows (population shapes, cache round-trips), use numbered
|
||||
depth-first sections and comparison tables:
|
||||
|
||||
```
|
||||
## 1. <Write path> (### 1a., ### 1b., … per sub-case)
|
||||
## 2. <Read path>
|
||||
## 3. <Round trip / tricky bit>
|
||||
## 4. When to use which (comparison table)
|
||||
## Related
|
||||
```
|
||||
|
||||
### 4.6 Best Practices page (`04_*`)
|
||||
|
||||
- Flat themed `##` sections (e.g. Layering, Lifecycle, Data & Performance,
|
||||
Transactions & Errors, Testing), each a short list of numbered conventions.
|
||||
- Pure prose — no large code blocks.
|
||||
|
||||
### 4.7 Error Handling (`06_*`) / Testing pages
|
||||
|
||||
- **Error Handling:** an exceptions table (`Exception | Source | Meaning / fix`),
|
||||
a `> ` note on which failures are by design, a `## 🚀 FastAPI Mapping Example`
|
||||
code block, then `## 💡 Tips` bullets, then `## Related`.
|
||||
- **Testing example (`07_*`):** `## 🚀 Mock-Based Quickstart` (focused code
|
||||
block), `## 💡 Notes` tip list, `## Related`.
|
||||
|
||||
Common to all pages: no frontmatter, `---` between every major section, and a
|
||||
`## Related` (or variant) footer as the **last** section.
|
||||
|
||||
---
|
||||
|
||||
## 5. The `## Related` footer
|
||||
|
||||
Every page ends with a cross-link footer. Rules:
|
||||
|
||||
- Always the **last** section, always preceded by a `---`.
|
||||
- Standard heading: `## Related` (no emoji).
|
||||
- One bullet line; links separated by ` · ` (middle dot plus spaces).
|
||||
- Link label format: `[NN – Title](relative_path)` — en-dash, page number, title.
|
||||
- Paths are **relative**: same directory → `02_custom_repo.md`; parent →
|
||||
`../01_overview.md`; child → `03_use_cases/01_basic_crud.md`.
|
||||
- Link order follows nav order (each `Related` points to related next/sibling
|
||||
pages, plus the overview/components anchor).
|
||||
|
||||
Examples (from mongo-ops):
|
||||
|
||||
```
|
||||
## Related
|
||||
- [02 – Custom repository](02_custom_repo.md) · [04 – Pagination](04_pagination.md) · [Overview](../01_overview.md)
|
||||
```
|
||||
|
||||
Variants:
|
||||
|
||||
- `## ➡️ Read Next` — used on the overview page (linear reading order).
|
||||
- `## 🔗 Related Resources` — only on `index.md`, one bullet per external resource.
|
||||
|
||||
---
|
||||
|
||||
## 6. Tone & formatting rules
|
||||
|
||||
- **Written for humans**: short sentences, concrete examples, plain words.
|
||||
- Emoji-prefixed H2 headings for recognizable section types
|
||||
(`📦 What's New?`, `🚀 Example`, `💡 Tips`, `🚀 Key Features`).
|
||||
- `---` horizontal rule between every major section.
|
||||
- Code blocks always declare a language (```python, ```bash, etc.).
|
||||
- Use tables for comparisons and structured decisions; bullets for lists;
|
||||
ASCII diagrams for architecture.
|
||||
- Bold key terms inline. Use `inline code` for symbols/APIs.
|
||||
- Keep pages focused: one recipe/purpose per page. If a page balloons past
|
||||
~10 KB, split it (add a numbered deep-dive page instead).
|
||||
- Match tone of existing pages in the repo before writing new ones.
|
||||
- Ground every `## 🚀 Example`, `💡 Tips`, and `📦 What's New?` row in the
|
||||
library's actual source, tests, and its `docs/mcp` bundle — never invent
|
||||
APIs or behavior. Signatures and exceptions come from the code; gotchas
|
||||
come from the tests.
|
||||
|
||||
---
|
||||
|
||||
## 7. Build & verify workflow
|
||||
|
||||
After creating or editing wiki pages:
|
||||
|
||||
```bash
|
||||
# 1. Build the wiki (from the repo root)
|
||||
doc-forge build --wiki # wiki only
|
||||
doc-forge build --wiki --mkdocs --module <pkg> # wiki + lib together
|
||||
|
||||
# 2. Preview locally
|
||||
doc-forge serve --wiki
|
||||
|
||||
# 3. Collect into the hub (run from the docs/ service repo)
|
||||
python collect.py # copies site, regenerates index + nginx.conf
|
||||
python collect.py --dry-run # preview without writing
|
||||
```
|
||||
|
||||
Verification checklist:
|
||||
|
||||
- `doc-forge build --wiki` completes with no warnings about missing files.
|
||||
- Every new page is present in `docs/mkdocs.wiki.yml` **and** in the index
|
||||
Documentation Structure table.
|
||||
- Every page ends with a `## Related` block and no dead links (paths resolve).
|
||||
- After `collect.py`: the hub card links to both `/wiki/` and `/lib/` and the
|
||||
pages render (spot-check with the served site).
|
||||
- If code/docstrings changed (no change when wiki-only), run the repo gates:
|
||||
`black`, `ruff`, `mypy`, `pytest`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Before/after checklist
|
||||
|
||||
**Before creating a page:**
|
||||
|
||||
- [ ] Confirm it is genuinely wiki material (how-to) and not API contract.
|
||||
- [ ] Find the right filename (`NN_snake_case.md`) and directory for its theme.
|
||||
- [ ] Outline the sections per §4 anatomy that fits the content.
|
||||
|
||||
**After creating/editing a page:**
|
||||
|
||||
- [ ] Page wired into `docs/mkdocs.wiki.yml` nav (themed subgroup if needed).
|
||||
- [ ] `index.md` Documentation Structure table updated.
|
||||
- [ ] `## Related` footer present, relative links, nav order.
|
||||
- [ ] `---` separators consistent; no frontmatter; emoji headings where apt.
|
||||
- [ ] Build passes; collect run; hub shows `/wiki/` + `/lib/` links.
|
||||
- [ ] No orphaned files, no dead links.
|
||||
````
|
||||
---
|
||||
|
||||
© Aetoskia Internal — `docforge` 1.0
|
||||
Reference in New Issue
Block a user