From 4ec67c86c655366ce9e180a3df5a9ccbb46b3c24 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Tue, 15 Sep 2026 16:53:08 +0530 Subject: [PATCH] fix(loaders): render clean signatures, drop unresolvable aliases from models - Stringify Object.signature() instead of str()-ing the bound method, which produced "" reprs - Skip alias members that cannot resolve (stdlib/third-party imports) while preserving resolvable package re-exports; return None for empty signatures (classes without __init__ args) - Add MCP renderer regression tests for signature cleanliness, alias filtering, and package re-export preservation --- docforge/loaders/griffe_loader.py | 52 +- docs/lib/docforge/cli/api_utils.md | 3 - docs/lib/docforge/cli/commands.md | 3 - docs/lib/docforge/cli/index.md | 8 - docs/lib/docforge/cli/main.md | 3 - docs/lib/docforge/cli/mcp_utils.md | 3 - docs/lib/docforge/cli/mkdocs_utils.md | 3 - docs/lib/docforge/index.md | 9 - docs/lib/docforge/loaders/griffe_loader.md | 3 - docs/lib/docforge/loaders/index.md | 4 - docs/lib/docforge/models/index.md | 6 - docs/lib/docforge/models/module.md | 3 - docs/lib/docforge/models/object.md | 3 - docs/lib/docforge/models/project.md | 3 - docs/lib/docforge/nav/index.md | 7 - docs/lib/docforge/nav/mkdocs.md | 3 - docs/lib/docforge/nav/resolver.md | 3 - docs/lib/docforge/nav/spec.md | 3 - docs/lib/docforge/nav/wiki.md | 3 - docs/lib/docforge/renderers/base.md | 3 - docs/lib/docforge/renderers/index.md | 6 - docs/lib/docforge/renderers/mcp_renderer.md | 3 - .../lib/docforge/renderers/mkdocs_renderer.md | 3 - docs/lib/docforge/servers/index.md | 4 - docs/lib/docforge/servers/mcp_server.md | 3 - docs/lib/index.md | 1 - docs/mcp/modules/docforge.cli.api_utils.json | 43 +- docs/mcp/modules/docforge.cli.commands.json | 246 +--- docs/mcp/modules/docforge.cli.json | 422 ++----- docs/mcp/modules/docforge.cli.main.json | 4 +- docs/mcp/modules/docforge.cli.mcp_utils.json | 40 +- .../modules/docforge.cli.mkdocs_utils.json | 89 +- docs/mcp/modules/docforge.json | 1057 +++++------------ .../docforge.loaders.griffe_loader.json | 100 +- docs/mcp/modules/docforge.loaders.json | 108 +- docs/mcp/modules/docforge.models.json | 129 +- docs/mcp/modules/docforge.models.module.json | 35 +- docs/mcp/modules/docforge.models.object.json | 15 +- docs/mcp/modules/docforge.models.project.json | 31 +- docs/mcp/modules/docforge.nav.json | 154 +-- docs/mcp/modules/docforge.nav.mkdocs.json | 26 +- docs/mcp/modules/docforge.nav.resolver.json | 39 +- docs/mcp/modules/docforge.nav.spec.json | 29 +- docs/mcp/modules/docforge.nav.wiki.json | 30 +- docs/mcp/modules/docforge.renderers.base.json | 34 +- docs/mcp/modules/docforge.renderers.json | 162 +-- .../docforge.renderers.mcp_renderer.json | 73 +- .../docforge.renderers.mkdocs_renderer.json | 41 +- docs/mcp/modules/docforge.servers.json | 54 +- .../modules/docforge.servers.mcp_server.json | 46 +- tests/renderers/mcp/test_mcp_signatures.py | 73 ++ 51 files changed, 941 insertions(+), 2287 deletions(-) delete mode 100644 docs/lib/docforge/cli/api_utils.md delete mode 100644 docs/lib/docforge/cli/commands.md delete mode 100644 docs/lib/docforge/cli/index.md delete mode 100644 docs/lib/docforge/cli/main.md delete mode 100644 docs/lib/docforge/cli/mcp_utils.md delete mode 100644 docs/lib/docforge/cli/mkdocs_utils.md delete mode 100644 docs/lib/docforge/index.md delete mode 100644 docs/lib/docforge/loaders/griffe_loader.md delete mode 100644 docs/lib/docforge/loaders/index.md delete mode 100644 docs/lib/docforge/models/index.md delete mode 100644 docs/lib/docforge/models/module.md delete mode 100644 docs/lib/docforge/models/object.md delete mode 100644 docs/lib/docforge/models/project.md delete mode 100644 docs/lib/docforge/nav/index.md delete mode 100644 docs/lib/docforge/nav/mkdocs.md delete mode 100644 docs/lib/docforge/nav/resolver.md delete mode 100644 docs/lib/docforge/nav/spec.md delete mode 100644 docs/lib/docforge/nav/wiki.md delete mode 100644 docs/lib/docforge/renderers/base.md delete mode 100644 docs/lib/docforge/renderers/index.md delete mode 100644 docs/lib/docforge/renderers/mcp_renderer.md delete mode 100644 docs/lib/docforge/renderers/mkdocs_renderer.md delete mode 100644 docs/lib/docforge/servers/index.md delete mode 100644 docs/lib/docforge/servers/mcp_server.md create mode 100644 tests/renderers/mcp/test_mcp_signatures.py diff --git a/docforge/loaders/griffe_loader.py b/docforge/loaders/griffe_loader.py index 43fa841..a682d2b 100644 --- a/docforge/loaders/griffe_loader.py +++ b/docforge/loaders/griffe_loader.py @@ -12,6 +12,8 @@ into doc-forge documentation models. Notes: - All analysis is static; analyzed modules are never executed. - Private members (names starting with `_`) are skipped during conversion. + - Imported aliases that cannot be resolved (stdlib/third-party names) are + skipped; aliases that resolve within the documented project are kept. --- """ @@ -232,6 +234,8 @@ class GriffeLoader: for name, member in obj.members.items(): if name.startswith("_"): continue + if not self._is_resolvable_alias(member): + continue module.add_object(self._convert_object(member)) @@ -268,6 +272,8 @@ class GriffeLoader: for name, member in obj.members.items(): if name.startswith("_"): continue + if not self._is_resolvable_alias(member): + continue doc_obj.add_member(self._convert_object(member)) except AliasResolutionError: pass @@ -299,17 +305,53 @@ class GriffeLoader: """ Safely extract the signature of a Griffe object. + Griffe exposes signatures as callables (``Object.signature``); the + method is invoked and stringified to produce a clean, stable signature. + Aliases that point outside the loaded project fail resolution and are + reported as `None`. + Args: obj (Object): Griffe object to inspect. Returns: str | None: - String representation of the object's signature if available, otherwise `None`. + Clean string representation of the object's signature if + available, otherwise `None`. """ try: - if hasattr(obj, "signature") and obj.signature: - return str(obj.signature) - except AliasResolutionError: + signature = getattr(obj, "signature", None) + if signature is None: + return None + if callable(signature): + signature = signature() + if not signature: + return None + return str(signature).strip() or None + except Exception: return None - return None + + def _is_resolvable_alias(self, obj: Object) -> bool: + """ + Report whether an object is a resolvable part of the documented API. + + Aliases that cannot be resolved (stdlib or third-party imports) are + treated as noise and excluded from the model. Non-alias objects are + always resolvable. + + Args: + obj (Object): + Griffe object to test. + + Returns: + bool: + True if the object should be kept, False if it is an + unresolvable alias. + """ + if obj.kind.value != "alias": + return True + try: + _ = obj.canonical_path + except AliasResolutionError: + return False + return True diff --git a/docs/lib/docforge/cli/api_utils.md b/docs/lib/docforge/cli/api_utils.md deleted file mode 100644 index 62040b8..0000000 --- a/docs/lib/docforge/cli/api_utils.md +++ /dev/null @@ -1,3 +0,0 @@ -# Api Utils - -::: docforge.cli.api_utils diff --git a/docs/lib/docforge/cli/commands.md b/docs/lib/docforge/cli/commands.md deleted file mode 100644 index 75f0d75..0000000 --- a/docs/lib/docforge/cli/commands.md +++ /dev/null @@ -1,3 +0,0 @@ -# Commands - -::: docforge.cli.commands diff --git a/docs/lib/docforge/cli/index.md b/docs/lib/docforge/cli/index.md deleted file mode 100644 index 314c649..0000000 --- a/docs/lib/docforge/cli/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# Cli - -::: docforge.cli -- [Api Utils](api_utils.md) -- [Commands](commands.md) -- [Main](main.md) -- [Mcp Utils](mcp_utils.md) -- [Mkdocs Utils](mkdocs_utils.md) diff --git a/docs/lib/docforge/cli/main.md b/docs/lib/docforge/cli/main.md deleted file mode 100644 index b22fa07..0000000 --- a/docs/lib/docforge/cli/main.md +++ /dev/null @@ -1,3 +0,0 @@ -# Main - -::: docforge.cli.main diff --git a/docs/lib/docforge/cli/mcp_utils.md b/docs/lib/docforge/cli/mcp_utils.md deleted file mode 100644 index 7987ffd..0000000 --- a/docs/lib/docforge/cli/mcp_utils.md +++ /dev/null @@ -1,3 +0,0 @@ -# Mcp Utils - -::: docforge.cli.mcp_utils diff --git a/docs/lib/docforge/cli/mkdocs_utils.md b/docs/lib/docforge/cli/mkdocs_utils.md deleted file mode 100644 index 2f2d3d9..0000000 --- a/docs/lib/docforge/cli/mkdocs_utils.md +++ /dev/null @@ -1,3 +0,0 @@ -# Mkdocs Utils - -::: docforge.cli.mkdocs_utils diff --git a/docs/lib/docforge/index.md b/docs/lib/docforge/index.md deleted file mode 100644 index d6800dc..0000000 --- a/docs/lib/docforge/index.md +++ /dev/null @@ -1,9 +0,0 @@ -# Docforge - -::: docforge -- [Cli](cli/) -- [Loaders](loaders/) -- [Models](models/) -- [Nav](nav/) -- [Renderers](renderers/) -- [Servers](servers/) diff --git a/docs/lib/docforge/loaders/griffe_loader.md b/docs/lib/docforge/loaders/griffe_loader.md deleted file mode 100644 index 21d8766..0000000 --- a/docs/lib/docforge/loaders/griffe_loader.md +++ /dev/null @@ -1,3 +0,0 @@ -# Griffe Loader - -::: docforge.loaders.griffe_loader diff --git a/docs/lib/docforge/loaders/index.md b/docs/lib/docforge/loaders/index.md deleted file mode 100644 index 2cbb874..0000000 --- a/docs/lib/docforge/loaders/index.md +++ /dev/null @@ -1,4 +0,0 @@ -# Loaders - -::: docforge.loaders -- [Griffe Loader](griffe_loader.md) diff --git a/docs/lib/docforge/models/index.md b/docs/lib/docforge/models/index.md deleted file mode 100644 index f16cc48..0000000 --- a/docs/lib/docforge/models/index.md +++ /dev/null @@ -1,6 +0,0 @@ -# Models - -::: docforge.models -- [Module](module.md) -- [Object](object.md) -- [Project](project.md) diff --git a/docs/lib/docforge/models/module.md b/docs/lib/docforge/models/module.md deleted file mode 100644 index 945994c..0000000 --- a/docs/lib/docforge/models/module.md +++ /dev/null @@ -1,3 +0,0 @@ -# Module - -::: docforge.models.module diff --git a/docs/lib/docforge/models/object.md b/docs/lib/docforge/models/object.md deleted file mode 100644 index 8e9a603..0000000 --- a/docs/lib/docforge/models/object.md +++ /dev/null @@ -1,3 +0,0 @@ -# Object - -::: docforge.models.object diff --git a/docs/lib/docforge/models/project.md b/docs/lib/docforge/models/project.md deleted file mode 100644 index 64db98e..0000000 --- a/docs/lib/docforge/models/project.md +++ /dev/null @@ -1,3 +0,0 @@ -# Project - -::: docforge.models.project diff --git a/docs/lib/docforge/nav/index.md b/docs/lib/docforge/nav/index.md deleted file mode 100644 index 1740108..0000000 --- a/docs/lib/docforge/nav/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# Nav - -::: docforge.nav -- [Mkdocs](mkdocs.md) -- [Resolver](resolver.md) -- [Spec](spec.md) -- [Wiki](wiki.md) diff --git a/docs/lib/docforge/nav/mkdocs.md b/docs/lib/docforge/nav/mkdocs.md deleted file mode 100644 index b783fec..0000000 --- a/docs/lib/docforge/nav/mkdocs.md +++ /dev/null @@ -1,3 +0,0 @@ -# Mkdocs - -::: docforge.nav.mkdocs diff --git a/docs/lib/docforge/nav/resolver.md b/docs/lib/docforge/nav/resolver.md deleted file mode 100644 index 4f30dc2..0000000 --- a/docs/lib/docforge/nav/resolver.md +++ /dev/null @@ -1,3 +0,0 @@ -# Resolver - -::: docforge.nav.resolver diff --git a/docs/lib/docforge/nav/spec.md b/docs/lib/docforge/nav/spec.md deleted file mode 100644 index 924864b..0000000 --- a/docs/lib/docforge/nav/spec.md +++ /dev/null @@ -1,3 +0,0 @@ -# Spec - -::: docforge.nav.spec diff --git a/docs/lib/docforge/nav/wiki.md b/docs/lib/docforge/nav/wiki.md deleted file mode 100644 index c60c750..0000000 --- a/docs/lib/docforge/nav/wiki.md +++ /dev/null @@ -1,3 +0,0 @@ -# Wiki - -::: docforge.nav.wiki diff --git a/docs/lib/docforge/renderers/base.md b/docs/lib/docforge/renderers/base.md deleted file mode 100644 index 196d183..0000000 --- a/docs/lib/docforge/renderers/base.md +++ /dev/null @@ -1,3 +0,0 @@ -# Base - -::: docforge.renderers.base diff --git a/docs/lib/docforge/renderers/index.md b/docs/lib/docforge/renderers/index.md deleted file mode 100644 index 28d61c4..0000000 --- a/docs/lib/docforge/renderers/index.md +++ /dev/null @@ -1,6 +0,0 @@ -# Renderers - -::: docforge.renderers -- [Base](base.md) -- [Mcp Renderer](mcp_renderer.md) -- [Mkdocs Renderer](mkdocs_renderer.md) diff --git a/docs/lib/docforge/renderers/mcp_renderer.md b/docs/lib/docforge/renderers/mcp_renderer.md deleted file mode 100644 index 02f97d1..0000000 --- a/docs/lib/docforge/renderers/mcp_renderer.md +++ /dev/null @@ -1,3 +0,0 @@ -# Mcp Renderer - -::: docforge.renderers.mcp_renderer diff --git a/docs/lib/docforge/renderers/mkdocs_renderer.md b/docs/lib/docforge/renderers/mkdocs_renderer.md deleted file mode 100644 index f60486e..0000000 --- a/docs/lib/docforge/renderers/mkdocs_renderer.md +++ /dev/null @@ -1,3 +0,0 @@ -# Mkdocs Renderer - -::: docforge.renderers.mkdocs_renderer diff --git a/docs/lib/docforge/servers/index.md b/docs/lib/docforge/servers/index.md deleted file mode 100644 index 22e4b69..0000000 --- a/docs/lib/docforge/servers/index.md +++ /dev/null @@ -1,4 +0,0 @@ -# Servers - -::: docforge.servers -- [Mcp Server](mcp_server.md) diff --git a/docs/lib/docforge/servers/mcp_server.md b/docs/lib/docforge/servers/mcp_server.md deleted file mode 100644 index 0f20e6b..0000000 --- a/docs/lib/docforge/servers/mcp_server.md +++ /dev/null @@ -1,3 +0,0 @@ -# Mcp Server - -::: docforge.servers.mcp_server diff --git a/docs/lib/index.md b/docs/lib/index.md index fd38149..96e8919 100644 --- a/docs/lib/index.md +++ b/docs/lib/index.md @@ -1,4 +1,3 @@ # docforge ::: docforge -- [Docforge](docforge/) diff --git a/docs/mcp/modules/docforge.cli.api_utils.json b/docs/mcp/modules/docforge.cli.api_utils.json index 1fc4060..ae164da 100644 --- a/docs/mcp/modules/docforge.cli.api_utils.json +++ b/docs/mcp/modules/docforge.cli.api_utils.json @@ -4,34 +4,6 @@ "path": "docforge.cli.api_utils", "docstring": "# Summary\n\nUtilities for building API documentation from an OpenAPI specification.", "objects": { - "json": { - "name": "json", - "kind": "alias", - "path": "docforge.cli.api_utils.json", - "signature": "", - "docstring": null - }, - "dataclass": { - "name": "dataclass", - "kind": "alias", - "path": "docforge.cli.api_utils.dataclass", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.api_utils.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.api_utils.click", - "signature": "", - "docstring": null - }, "SWAGGER_SPEC_FILENAME": { "name": "SWAGGER_SPEC_FILENAME", "kind": "attribute", @@ -43,7 +15,7 @@ "name": "OpenAPIMetadata", "kind": "class", "path": "docforge.cli.api_utils.OpenAPIMetadata", - "signature": "", + "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": { @@ -73,29 +45,22 @@ "name": "load_openapi_spec", "kind": "function", "path": "docforge.cli.api_utils.load_openapi_spec", - "signature": "", + "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": "", + "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": "", + "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." - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.api_utils.Any", - "signature": "", - "docstring": null } } } diff --git a/docs/mcp/modules/docforge.cli.commands.json b/docs/mcp/modules/docforge.cli.commands.json index 79af154..2d73bff 100644 --- a/docs/mcp/modules/docforge.cli.commands.json +++ b/docs/mcp/modules/docforge.cli.commands.json @@ -4,95 +4,46 @@ "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": { - "os": { - "name": "os", - "kind": "alias", - "path": "docforge.cli.commands.os", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.commands.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.commands.click", - "signature": "", - "docstring": null - }, "api_utils": { "name": "api_utils", "kind": "module", "path": "docforge.cli.commands.api_utils", - "signature": "", + "signature": null, "docstring": "# Summary\n\nUtilities for building API documentation from an OpenAPI specification.", "members": { - "json": { - "name": "json", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.json", - "signature": "", - "docstring": null - }, - "dataclass": { - "name": "dataclass", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.dataclass", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.click", - "signature": "", - "docstring": null - }, "SWAGGER_SPEC_FILENAME": { "name": "SWAGGER_SPEC_FILENAME", "kind": "attribute", "path": "docforge.cli.commands.api_utils.SWAGGER_SPEC_FILENAME", - "signature": "", + "signature": null, "docstring": null }, "OpenAPIMetadata": { "name": "OpenAPIMetadata", "kind": "class", "path": "docforge.cli.commands.api_utils.OpenAPIMetadata", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "site_description": { "name": "site_description", "kind": "attribute", "path": "docforge.cli.commands.api_utils.OpenAPIMetadata.site_description", - "signature": "", + "signature": null, "docstring": null }, "site_author": { "name": "site_author", "kind": "attribute", "path": "docforge.cli.commands.api_utils.OpenAPIMetadata.site_author", - "signature": "", + "signature": null, "docstring": null } } @@ -101,29 +52,22 @@ "name": "load_openapi_spec", "kind": "function", "path": "docforge.cli.commands.api_utils.load_openapi_spec", - "signature": "", + "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": "", + "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": "", + "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." - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.Any", - "signature": "", - "docstring": null } } }, @@ -131,42 +75,28 @@ "name": "mcp_utils", "kind": "module", "path": "docforge.cli.commands.mcp_utils", - "signature": "", + "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.commands.mcp_utils.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.commands.mcp_utils.click", - "signature": "", - "docstring": null - }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.commands.mcp_utils.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -175,28 +105,28 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.cli.commands.mcp_utils.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources", - "signature": "", + "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." } } @@ -205,28 +135,28 @@ "name": "MCPServer", "kind": "class", "path": "docforge.cli.commands.mcp_utils.MCPServer", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "app": { "name": "app", "kind": "attribute", "path": "docforge.cli.commands.mcp_utils.MCPServer.app", - "signature": "", + "signature": null, "docstring": null }, "run": { "name": "run", "kind": "function", "path": "docforge.cli.commands.mcp_utils.MCPServer.run", - "signature": "", + "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`." } } @@ -235,14 +165,14 @@ "name": "generate_resources", "kind": "function", "path": "docforge.cli.commands.mcp_utils.generate_resources", - "signature": "", + "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": "", + "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." } } @@ -251,77 +181,28 @@ "name": "mkdocs_utils", "kind": "module", "path": "docforge.cli.commands.mkdocs_utils", - "signature": "", + "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.Iterable", - "signature": "", - "docstring": null - }, - "resources": { - "name": "resources", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.resources", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.Any", - "signature": "", - "docstring": null - }, - "cast": { - "name": "cast", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.cast", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.click", - "signature": "", - "docstring": null - }, - "yaml": { - "name": "yaml", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.yaml", - "signature": "", - "docstring": null - }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -330,21 +211,21 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -353,49 +234,49 @@ "name": "build_wiki_nav", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.build_wiki_nav", - "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", - "signature": "", + "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": "", + "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`." } } @@ -404,49 +285,49 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_sources", - "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -455,21 +336,21 @@ "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.commands.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -478,70 +359,70 @@ "name": "DocObject", "kind": "class", "path": "docforge.cli.commands.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.cli.commands.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.cli.commands.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.cli.commands.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.cli.commands.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.cli.commands.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.cli.commands.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -557,29 +438,22 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", + "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": "", + "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": "", + "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." - }, - "Group": { - "name": "Group", - "kind": "alias", - "path": "docforge.cli.commands.Group", - "signature": "", - "docstring": null } } } diff --git a/docs/mcp/modules/docforge.cli.json b/docs/mcp/modules/docforge.cli.json index be6964a..b1b7190 100644 --- a/docs/mcp/modules/docforge.cli.json +++ b/docs/mcp/modules/docforge.cli.json @@ -15,14 +15,14 @@ "name": "cli", "kind": "attribute", "path": "docforge.cli.main.cli", - "signature": "", + "signature": null, "docstring": null }, "main": { "name": "main", "kind": "function", "path": "docforge.cli.main.main", - "signature": "", + "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." } } @@ -34,34 +34,6 @@ "signature": null, "docstring": "# Summary\n\nUtilities for building API documentation from an OpenAPI specification.", "members": { - "json": { - "name": "json", - "kind": "alias", - "path": "docforge.cli.api_utils.json", - "signature": "", - "docstring": null - }, - "dataclass": { - "name": "dataclass", - "kind": "alias", - "path": "docforge.cli.api_utils.dataclass", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.api_utils.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.api_utils.click", - "signature": "", - "docstring": null - }, "SWAGGER_SPEC_FILENAME": { "name": "SWAGGER_SPEC_FILENAME", "kind": "attribute", @@ -73,7 +45,7 @@ "name": "OpenAPIMetadata", "kind": "class", "path": "docforge.cli.api_utils.OpenAPIMetadata", - "signature": "", + "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": { @@ -103,29 +75,22 @@ "name": "load_openapi_spec", "kind": "function", "path": "docforge.cli.api_utils.load_openapi_spec", - "signature": "", + "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": "", + "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": "", + "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." - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.api_utils.Any", - "signature": "", - "docstring": null } } }, @@ -136,95 +101,46 @@ "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": { - "os": { - "name": "os", - "kind": "alias", - "path": "docforge.cli.commands.os", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.commands.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.commands.click", - "signature": "", - "docstring": null - }, "api_utils": { "name": "api_utils", "kind": "module", "path": "docforge.cli.commands.api_utils", - "signature": "", + "signature": null, "docstring": "# Summary\n\nUtilities for building API documentation from an OpenAPI specification.", "members": { - "json": { - "name": "json", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.json", - "signature": "", - "docstring": null - }, - "dataclass": { - "name": "dataclass", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.dataclass", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.click", - "signature": "", - "docstring": null - }, "SWAGGER_SPEC_FILENAME": { "name": "SWAGGER_SPEC_FILENAME", "kind": "attribute", "path": "docforge.cli.commands.api_utils.SWAGGER_SPEC_FILENAME", - "signature": "", + "signature": null, "docstring": null }, "OpenAPIMetadata": { "name": "OpenAPIMetadata", "kind": "class", "path": "docforge.cli.commands.api_utils.OpenAPIMetadata", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "site_description": { "name": "site_description", "kind": "attribute", "path": "docforge.cli.commands.api_utils.OpenAPIMetadata.site_description", - "signature": "", + "signature": null, "docstring": null }, "site_author": { "name": "site_author", "kind": "attribute", "path": "docforge.cli.commands.api_utils.OpenAPIMetadata.site_author", - "signature": "", + "signature": null, "docstring": null } } @@ -233,29 +149,22 @@ "name": "load_openapi_spec", "kind": "function", "path": "docforge.cli.commands.api_utils.load_openapi_spec", - "signature": "", + "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": "", + "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": "", + "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." - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.Any", - "signature": "", - "docstring": null } } }, @@ -263,42 +172,28 @@ "name": "mcp_utils", "kind": "module", "path": "docforge.cli.commands.mcp_utils", - "signature": "", + "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.commands.mcp_utils.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.commands.mcp_utils.click", - "signature": "", - "docstring": null - }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.commands.mcp_utils.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -307,28 +202,28 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.cli.commands.mcp_utils.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources", - "signature": "", + "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." } } @@ -337,28 +232,28 @@ "name": "MCPServer", "kind": "class", "path": "docforge.cli.commands.mcp_utils.MCPServer", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "app": { "name": "app", "kind": "attribute", "path": "docforge.cli.commands.mcp_utils.MCPServer.app", - "signature": "", + "signature": null, "docstring": null }, "run": { "name": "run", "kind": "function", "path": "docforge.cli.commands.mcp_utils.MCPServer.run", - "signature": "", + "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`." } } @@ -367,14 +262,14 @@ "name": "generate_resources", "kind": "function", "path": "docforge.cli.commands.mcp_utils.generate_resources", - "signature": "", + "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": "", + "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." } } @@ -383,77 +278,28 @@ "name": "mkdocs_utils", "kind": "module", "path": "docforge.cli.commands.mkdocs_utils", - "signature": "", + "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.Iterable", - "signature": "", - "docstring": null - }, - "resources": { - "name": "resources", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.resources", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.Any", - "signature": "", - "docstring": null - }, - "cast": { - "name": "cast", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.cast", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.click", - "signature": "", - "docstring": null - }, - "yaml": { - "name": "yaml", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.yaml", - "signature": "", - "docstring": null - }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -462,21 +308,21 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -485,49 +331,49 @@ "name": "build_wiki_nav", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.build_wiki_nav", - "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", - "signature": "", + "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": "", + "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`." } } @@ -536,49 +382,49 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_sources", - "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -587,21 +433,21 @@ "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.commands.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -610,70 +456,70 @@ "name": "DocObject", "kind": "class", "path": "docforge.cli.commands.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.cli.commands.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.cli.commands.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.cli.commands.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.cli.commands.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.cli.commands.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.cli.commands.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -689,29 +535,22 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", + "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": "", + "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": "", + "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." - }, - "Group": { - "name": "Group", - "kind": "alias", - "path": "docforge.cli.commands.Group", - "signature": "", - "docstring": null } } }, @@ -722,39 +561,25 @@ "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.mcp_utils.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.mcp_utils.click", - "signature": "", - "docstring": null - }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.mcp_utils.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -763,28 +588,28 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.cli.mcp_utils.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources", - "signature": "", + "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." } } @@ -793,28 +618,28 @@ "name": "MCPServer", "kind": "class", "path": "docforge.cli.mcp_utils.MCPServer", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "app": { "name": "app", "kind": "attribute", "path": "docforge.cli.mcp_utils.MCPServer.app", - "signature": "", + "signature": null, "docstring": null }, "run": { "name": "run", "kind": "function", "path": "docforge.cli.mcp_utils.MCPServer.run", - "signature": "", + "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`." } } @@ -823,14 +648,14 @@ "name": "generate_resources", "kind": "function", "path": "docforge.cli.mcp_utils.generate_resources", - "signature": "", + "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": "", + "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." } } @@ -842,74 +667,25 @@ "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.Iterable", - "signature": "", - "docstring": null - }, - "resources": { - "name": "resources", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.resources", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.Any", - "signature": "", - "docstring": null - }, - "cast": { - "name": "cast", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.cast", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.click", - "signature": "", - "docstring": null - }, - "yaml": { - "name": "yaml", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.yaml", - "signature": "", - "docstring": null - }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.mkdocs_utils.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -918,21 +694,21 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.cli.mkdocs_utils.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -941,49 +717,49 @@ "name": "build_wiki_nav", "kind": "function", "path": "docforge.cli.mkdocs_utils.build_wiki_nav", - "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", - "signature": "", + "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": "", + "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`." } } @@ -992,49 +768,49 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_sources", - "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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." } } diff --git a/docs/mcp/modules/docforge.cli.main.json b/docs/mcp/modules/docforge.cli.main.json index 0d98853..244177c 100644 --- a/docs/mcp/modules/docforge.cli.main.json +++ b/docs/mcp/modules/docforge.cli.main.json @@ -8,14 +8,14 @@ "name": "cli", "kind": "attribute", "path": "docforge.cli.main.cli", - "signature": "", + "signature": null, "docstring": null }, "main": { "name": "main", "kind": "function", "path": "docforge.cli.main.main", - "signature": "", + "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." } } diff --git a/docs/mcp/modules/docforge.cli.mcp_utils.json b/docs/mcp/modules/docforge.cli.mcp_utils.json index cb43910..f60ac5e 100644 --- a/docs/mcp/modules/docforge.cli.mcp_utils.json +++ b/docs/mcp/modules/docforge.cli.mcp_utils.json @@ -4,39 +4,25 @@ "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.mcp_utils.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.mcp_utils.click", - "signature": "", - "docstring": null - }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.mcp_utils.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -45,28 +31,28 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.cli.mcp_utils.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources", - "signature": "", + "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." } } @@ -75,28 +61,28 @@ "name": "MCPServer", "kind": "class", "path": "docforge.cli.mcp_utils.MCPServer", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "app": { "name": "app", "kind": "attribute", "path": "docforge.cli.mcp_utils.MCPServer.app", - "signature": "", + "signature": null, "docstring": null }, "run": { "name": "run", "kind": "function", "path": "docforge.cli.mcp_utils.MCPServer.run", - "signature": "", + "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`." } } @@ -105,14 +91,14 @@ "name": "generate_resources", "kind": "function", "path": "docforge.cli.mcp_utils.generate_resources", - "signature": "", + "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": "", + "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." } } diff --git a/docs/mcp/modules/docforge.cli.mkdocs_utils.json b/docs/mcp/modules/docforge.cli.mkdocs_utils.json index d655729..21b100a 100644 --- a/docs/mcp/modules/docforge.cli.mkdocs_utils.json +++ b/docs/mcp/modules/docforge.cli.mkdocs_utils.json @@ -4,74 +4,25 @@ "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.Iterable", - "signature": "", - "docstring": null - }, - "resources": { - "name": "resources", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.resources", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.Any", - "signature": "", - "docstring": null - }, - "cast": { - "name": "cast", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.cast", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.click", - "signature": "", - "docstring": null - }, - "yaml": { - "name": "yaml", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.yaml", - "signature": "", - "docstring": null - }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.mkdocs_utils.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -80,21 +31,21 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.cli.mkdocs_utils.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -103,49 +54,49 @@ "name": "build_wiki_nav", "kind": "function", "path": "docforge.cli.mkdocs_utils.build_wiki_nav", - "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", - "signature": "", + "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": "", + "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`." } } @@ -154,49 +105,49 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_sources", - "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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." } } diff --git a/docs/mcp/modules/docforge.json b/docs/mcp/modules/docforge.json index 99ac7a0..a963a48 100644 --- a/docs/mcp/modules/docforge.json +++ b/docs/mcp/modules/docforge.json @@ -8,21 +8,21 @@ "name": "GriffeLoader", "kind": "class", "path": "docforge.GriffeLoader", - "signature": "", + "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.GriffeLoader.load_project", - "signature": "", + "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.GriffeLoader.load_module", - "signature": "", + "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 ```" } } @@ -31,35 +31,35 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.discover_module_paths", - "signature": "", + "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." }, "MkDocsRenderer": { "name": "MkDocsRenderer", "kind": "class", "path": "docforge.MkDocsRenderer", - "signature": "", + "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.MkDocsRenderer.name", - "signature": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.MkDocsRenderer.generate_sources", - "signature": "", + "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.MkDocsRenderer.generate_readme", - "signature": "", + "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`." } } @@ -68,21 +68,21 @@ "name": "MCPRenderer", "kind": "class", "path": "docforge.MCPRenderer", - "signature": "", + "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.MCPRenderer.name", - "signature": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.MCPRenderer.generate_sources", - "signature": "", + "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." } } @@ -91,21 +91,21 @@ "name": "main", "kind": "module", "path": "docforge.main", - "signature": "", + "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.main.cli", - "signature": "", + "signature": null, "docstring": null }, "main": { "name": "main", "kind": "function", "path": "docforge.main.main", - "signature": "", + "signature": "main()", "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." } } @@ -128,14 +128,14 @@ "name": "cli", "kind": "attribute", "path": "docforge.cli.main.cli", - "signature": "", + "signature": null, "docstring": null }, "main": { "name": "main", "kind": "function", "path": "docforge.cli.main.main", - "signature": "", + "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." } } @@ -147,34 +147,6 @@ "signature": null, "docstring": "# Summary\n\nUtilities for building API documentation from an OpenAPI specification.", "members": { - "json": { - "name": "json", - "kind": "alias", - "path": "docforge.cli.api_utils.json", - "signature": "", - "docstring": null - }, - "dataclass": { - "name": "dataclass", - "kind": "alias", - "path": "docforge.cli.api_utils.dataclass", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.api_utils.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.api_utils.click", - "signature": "", - "docstring": null - }, "SWAGGER_SPEC_FILENAME": { "name": "SWAGGER_SPEC_FILENAME", "kind": "attribute", @@ -186,7 +158,7 @@ "name": "OpenAPIMetadata", "kind": "class", "path": "docforge.cli.api_utils.OpenAPIMetadata", - "signature": "", + "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": { @@ -216,29 +188,22 @@ "name": "load_openapi_spec", "kind": "function", "path": "docforge.cli.api_utils.load_openapi_spec", - "signature": "", + "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": "", + "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": "", + "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." - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.api_utils.Any", - "signature": "", - "docstring": null } } }, @@ -249,95 +214,46 @@ "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": { - "os": { - "name": "os", - "kind": "alias", - "path": "docforge.cli.commands.os", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.commands.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.commands.click", - "signature": "", - "docstring": null - }, "api_utils": { "name": "api_utils", "kind": "module", "path": "docforge.cli.commands.api_utils", - "signature": "", + "signature": null, "docstring": "# Summary\n\nUtilities for building API documentation from an OpenAPI specification.", "members": { - "json": { - "name": "json", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.json", - "signature": "", - "docstring": null - }, - "dataclass": { - "name": "dataclass", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.dataclass", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.click", - "signature": "", - "docstring": null - }, "SWAGGER_SPEC_FILENAME": { "name": "SWAGGER_SPEC_FILENAME", "kind": "attribute", "path": "docforge.cli.commands.api_utils.SWAGGER_SPEC_FILENAME", - "signature": "", + "signature": null, "docstring": null }, "OpenAPIMetadata": { "name": "OpenAPIMetadata", "kind": "class", "path": "docforge.cli.commands.api_utils.OpenAPIMetadata", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "site_description": { "name": "site_description", "kind": "attribute", "path": "docforge.cli.commands.api_utils.OpenAPIMetadata.site_description", - "signature": "", + "signature": null, "docstring": null }, "site_author": { "name": "site_author", "kind": "attribute", "path": "docforge.cli.commands.api_utils.OpenAPIMetadata.site_author", - "signature": "", + "signature": null, "docstring": null } } @@ -346,29 +262,22 @@ "name": "load_openapi_spec", "kind": "function", "path": "docforge.cli.commands.api_utils.load_openapi_spec", - "signature": "", + "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": "", + "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": "", + "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." - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.commands.api_utils.Any", - "signature": "", - "docstring": null } } }, @@ -376,42 +285,28 @@ "name": "mcp_utils", "kind": "module", "path": "docforge.cli.commands.mcp_utils", - "signature": "", + "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.commands.mcp_utils.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.commands.mcp_utils.click", - "signature": "", - "docstring": null - }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.commands.mcp_utils.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -420,28 +315,28 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.cli.commands.mcp_utils.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources", - "signature": "", + "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." } } @@ -450,28 +345,28 @@ "name": "MCPServer", "kind": "class", "path": "docforge.cli.commands.mcp_utils.MCPServer", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "app": { "name": "app", "kind": "attribute", "path": "docforge.cli.commands.mcp_utils.MCPServer.app", - "signature": "", + "signature": null, "docstring": null }, "run": { "name": "run", "kind": "function", "path": "docforge.cli.commands.mcp_utils.MCPServer.run", - "signature": "", + "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`." } } @@ -480,14 +375,14 @@ "name": "generate_resources", "kind": "function", "path": "docforge.cli.commands.mcp_utils.generate_resources", - "signature": "", + "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": "", + "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." } } @@ -496,77 +391,28 @@ "name": "mkdocs_utils", "kind": "module", "path": "docforge.cli.commands.mkdocs_utils", - "signature": "", + "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.Iterable", - "signature": "", - "docstring": null - }, - "resources": { - "name": "resources", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.resources", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.Any", - "signature": "", - "docstring": null - }, - "cast": { - "name": "cast", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.cast", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.click", - "signature": "", - "docstring": null - }, - "yaml": { - "name": "yaml", - "kind": "alias", - "path": "docforge.cli.commands.mkdocs_utils.yaml", - "signature": "", - "docstring": null - }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -575,21 +421,21 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -598,49 +444,49 @@ "name": "build_wiki_nav", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.build_wiki_nav", - "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", - "signature": "", + "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": "", + "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`." } } @@ -649,49 +495,49 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_sources", - "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -700,21 +546,21 @@ "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.commands.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -723,70 +569,70 @@ "name": "DocObject", "kind": "class", "path": "docforge.cli.commands.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.cli.commands.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.cli.commands.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.cli.commands.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.cli.commands.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.cli.commands.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.cli.commands.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -802,29 +648,22 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", + "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": "", + "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": "", + "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." - }, - "Group": { - "name": "Group", - "kind": "alias", - "path": "docforge.cli.commands.Group", - "signature": "", - "docstring": null } } }, @@ -835,39 +674,25 @@ "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.mcp_utils.Path", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.mcp_utils.click", - "signature": "", - "docstring": null - }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.mcp_utils.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -876,28 +701,28 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.cli.mcp_utils.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources", - "signature": "", + "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." } } @@ -906,28 +731,28 @@ "name": "MCPServer", "kind": "class", "path": "docforge.cli.mcp_utils.MCPServer", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "app": { "name": "app", "kind": "attribute", "path": "docforge.cli.mcp_utils.MCPServer.app", - "signature": "", + "signature": null, "docstring": null }, "run": { "name": "run", "kind": "function", "path": "docforge.cli.mcp_utils.MCPServer.run", - "signature": "", + "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`." } } @@ -936,14 +761,14 @@ "name": "generate_resources", "kind": "function", "path": "docforge.cli.mcp_utils.generate_resources", - "signature": "", + "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": "", + "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." } } @@ -955,74 +780,25 @@ "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.Iterable", - "signature": "", - "docstring": null - }, - "resources": { - "name": "resources", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.resources", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.Any", - "signature": "", - "docstring": null - }, - "cast": { - "name": "cast", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.cast", - "signature": "", - "docstring": null - }, - "click": { - "name": "click", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.click", - "signature": "", - "docstring": null - }, - "yaml": { - "name": "yaml", - "kind": "alias", - "path": "docforge.cli.mkdocs_utils.yaml", - "signature": "", - "docstring": null - }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.mkdocs_utils.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -1031,21 +807,21 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.cli.mkdocs_utils.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -1054,49 +830,49 @@ "name": "build_wiki_nav", "kind": "function", "path": "docforge.cli.mkdocs_utils.build_wiki_nav", - "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", - "signature": "", + "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": "", + "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`." } } @@ -1105,49 +881,49 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_sources", - "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -1165,21 +941,21 @@ "name": "GriffeLoader", "kind": "class", "path": "docforge.loaders.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -1188,7 +964,7 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.loaders.discover_module_paths", - "signature": "", + "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": { @@ -1196,118 +972,76 @@ "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\n---", + "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": { - "logging": { - "name": "logging", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.logging", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.Path", - "signature": "", - "docstring": null - }, - "AliasResolutionError": { - "name": "AliasResolutionError", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.AliasResolutionError", - "signature": "", - "docstring": null - }, - "LinesCollection": { - "name": "LinesCollection", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.LinesCollection", - "signature": "", - "docstring": null - }, - "ModulesCollection": { - "name": "ModulesCollection", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.ModulesCollection", - "signature": "", - "docstring": null - }, - "Object": { - "name": "Object", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.Object", - "signature": "", - "docstring": null - }, "DocObject": { "name": "DocObject", "kind": "class", "path": "docforge.loaders.griffe_loader.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -1316,49 +1050,49 @@ "name": "Module", "kind": "class", "path": "docforge.loaders.griffe_loader.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.loaders.griffe_loader.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.loaders.griffe_loader.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.loaders.griffe_loader.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -1367,49 +1101,49 @@ "name": "Project", "kind": "class", "path": "docforge.loaders.griffe_loader.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.loaders.griffe_loader.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.loaders.griffe_loader.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -1425,28 +1159,28 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.loaders.griffe_loader.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "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": "", + "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 ```" } } @@ -1466,49 +1200,49 @@ "name": "Project", "kind": "class", "path": "docforge.models.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.models.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.models.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -1517,49 +1251,49 @@ "name": "Module", "kind": "class", "path": "docforge.models.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.models.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.models.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.models.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -1568,70 +1302,70 @@ "name": "DocObject", "kind": "class", "path": "docforge.models.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.models.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.models.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.models.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.models.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.models.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.models.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -1643,81 +1377,74 @@ "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.models.module.Iterable", - "signature": "", - "docstring": null - }, "DocObject": { "name": "DocObject", "kind": "class", "path": "docforge.models.module.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.models.module.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.models.module.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.models.module.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.models.module.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.models.module.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.models.module.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -1726,7 +1453,7 @@ "name": "Module", "kind": "class", "path": "docforge.models.module.Module", - "signature": "", + "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": { @@ -1754,21 +1481,21 @@ "name": "add_object", "kind": "function", "path": "docforge.models.module.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -1782,18 +1509,11 @@ "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.models.object.Iterable", - "signature": "", - "docstring": null - }, "DocObject": { "name": "DocObject", "kind": "class", "path": "docforge.models.object.DocObject", - "signature": "", + "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": { @@ -1842,21 +1562,21 @@ "name": "add_member", "kind": "function", "path": "docforge.models.object.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -1870,60 +1590,53 @@ "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.models.project.Iterable", - "signature": "", - "docstring": null - }, "Module": { "name": "Module", "kind": "class", "path": "docforge.models.project.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.models.project.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.models.project.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.models.project.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -1932,7 +1645,7 @@ "name": "Project", "kind": "class", "path": "docforge.models.project.Project", - "signature": "", + "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": { @@ -1953,28 +1666,28 @@ "name": "add_module", "kind": "function", "path": "docforge.models.project.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -1994,42 +1707,42 @@ "name": "NavSpec", "kind": "class", "path": "docforge.nav.NavSpec", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "groups": { "name": "groups", "kind": "attribute", "path": "docforge.nav.NavSpec.groups", - "signature": "", + "signature": null, "docstring": null }, "icon": { "name": "icon", "kind": "attribute", "path": "docforge.nav.NavSpec.icon", - "signature": "", + "signature": null, "docstring": null }, "load": { "name": "load", "kind": "function", "path": "docforge.nav.NavSpec.load", - "signature": "", + "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": "", + "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." } } @@ -2038,35 +1751,35 @@ "name": "load_nav_spec", "kind": "function", "path": "docforge.nav.load_nav_spec", - "signature": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "groups": { "name": "groups", "kind": "attribute", "path": "docforge.nav.ResolvedNav.groups", - "signature": "", + "signature": null, "docstring": null }, "all_files": { "name": "all_files", "kind": "function", "path": "docforge.nav.ResolvedNav.all_files", - "signature": "", + "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." } } @@ -2075,21 +1788,21 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolve_nav", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -2098,7 +1811,7 @@ "name": "build_wiki_nav", "kind": "function", "path": "docforge.nav.build_wiki_nav", - "signature": "", + "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": { @@ -2108,46 +1821,32 @@ "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.nav.mkdocs.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.nav.mkdocs.Any", - "signature": "", - "docstring": null - }, "ResolvedNav": { "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.mkdocs.ResolvedNav", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "groups": { "name": "groups", "kind": "attribute", "path": "docforge.nav.mkdocs.ResolvedNav.groups", - "signature": "", + "signature": null, "docstring": null }, "all_files": { "name": "all_files", "kind": "function", "path": "docforge.nav.mkdocs.ResolvedNav.all_files", - "signature": "", + "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." } } @@ -2156,14 +1855,14 @@ "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.nav.mkdocs.MkDocsNavEmitter", - "signature": "", + "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": "", + "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." } } @@ -2177,67 +1876,46 @@ "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": { - "glob": { - "name": "glob", - "kind": "alias", - "path": "docforge.nav.resolver.glob", - "signature": "", - "docstring": null - }, - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.nav.resolver.Iterable", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.nav.resolver.Path", - "signature": "", - "docstring": null - }, "NavSpec": { "name": "NavSpec", "kind": "class", "path": "docforge.nav.resolver.NavSpec", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "groups": { "name": "groups", "kind": "attribute", "path": "docforge.nav.resolver.NavSpec.groups", - "signature": "", + "signature": null, "docstring": null }, "icon": { "name": "icon", "kind": "attribute", "path": "docforge.nav.resolver.NavSpec.icon", - "signature": "", + "signature": null, "docstring": null }, "load": { "name": "load", "kind": "function", "path": "docforge.nav.resolver.NavSpec.load", - "signature": "", + "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": "", + "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." } } @@ -2246,7 +1924,7 @@ "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.resolver.ResolvedNav", - "signature": "", + "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": { @@ -2267,7 +1945,7 @@ "name": "all_files", "kind": "function", "path": "docforge.nav.resolver.ResolvedNav.all_files", - "signature": "", + "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." } } @@ -2276,7 +1954,7 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolver.resolve_nav", - "signature": "", + "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." } } @@ -2288,32 +1966,11 @@ "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": { - "annotations": { - "name": "annotations", - "kind": "alias", - "path": "docforge.nav.spec.annotations", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.nav.spec.Path", - "signature": "", - "docstring": null - }, - "yaml": { - "name": "yaml", - "kind": "alias", - "path": "docforge.nav.spec.yaml", - "signature": "", - "docstring": null - }, "NavSpec": { "name": "NavSpec", "kind": "class", "path": "docforge.nav.spec.NavSpec", - "signature": "", + "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": { @@ -2341,14 +1998,14 @@ "name": "load", "kind": "function", "path": "docforge.nav.spec.NavSpec.load", - "signature": "", + "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": "", + "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." } } @@ -2357,7 +2014,7 @@ "name": "load_nav_spec", "kind": "function", "path": "docforge.nav.spec.load_nav_spec", - "signature": "", + "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." } } @@ -2369,39 +2026,11 @@ "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": { - "re": { - "name": "re", - "kind": "alias", - "path": "docforge.nav.wiki.re", - "signature": "", - "docstring": null - }, - "Callable": { - "name": "Callable", - "kind": "alias", - "path": "docforge.nav.wiki.Callable", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.nav.wiki.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.nav.wiki.Any", - "signature": "", - "docstring": null - }, "build_wiki_nav": { "name": "build_wiki_nav", "kind": "function", "path": "docforge.nav.wiki.build_wiki_nav", - "signature": "", + "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." } } @@ -2419,28 +2048,28 @@ "name": "MkDocsRenderer", "kind": "class", "path": "docforge.renderers.MkDocsRenderer", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.renderers.MkDocsRenderer.generate_sources", - "signature": "", + "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": "", + "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`." } } @@ -2449,21 +2078,21 @@ "name": "MCPRenderer", "kind": "class", "path": "docforge.renderers.MCPRenderer", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.renderers.MCPRenderer.generate_sources", - "signature": "", + "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." } } @@ -2475,67 +2104,53 @@ "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.renderers.base.Path", - "signature": "", - "docstring": null - }, - "Protocol": { - "name": "Protocol", - "kind": "alias", - "path": "docforge.renderers.base.Protocol", - "signature": "", - "docstring": null - }, "Project": { "name": "Project", "kind": "class", "path": "docforge.renderers.base.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.renderers.base.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.renderers.base.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -2544,7 +2159,7 @@ "name": "RendererConfig", "kind": "class", "path": "docforge.renderers.base.RendererConfig", - "signature": "", + "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": { @@ -2567,7 +2182,7 @@ "name": "DocRenderer", "kind": "class", "path": "docforge.renderers.base.DocRenderer", - "signature": "", + "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": { @@ -2581,7 +2196,7 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.base.DocRenderer.generate_sources", - "signature": "", + "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." } } @@ -2595,88 +2210,74 @@ "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": { - "json": { - "name": "json", - "kind": "alias", - "path": "docforge.renderers.mcp_renderer.json", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.renderers.mcp_renderer.Path", - "signature": "", - "docstring": null - }, "DocObject": { "name": "DocObject", "kind": "class", "path": "docforge.renderers.mcp_renderer.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -2685,49 +2286,49 @@ "name": "Module", "kind": "class", "path": "docforge.renderers.mcp_renderer.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.renderers.mcp_renderer.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -2736,49 +2337,49 @@ "name": "Project", "kind": "class", "path": "docforge.renderers.mcp_renderer.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -2787,7 +2388,7 @@ "name": "MCPRenderer", "kind": "class", "path": "docforge.renderers.mcp_renderer.MCPRenderer", - "signature": "", + "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": { @@ -2801,17 +2402,10 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources", - "signature": "", + "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." } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.renderers.mcp_renderer.Any", - "signature": "", - "docstring": null } } }, @@ -2822,60 +2416,53 @@ "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.renderers.mkdocs_renderer.Path", - "signature": "", - "docstring": null - }, "Module": { "name": "Module", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.renderers.mkdocs_renderer.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.renderers.mkdocs_renderer.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -2884,49 +2471,49 @@ "name": "Project", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.renderers.mkdocs_renderer.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -2935,7 +2522,7 @@ "name": "MkDocsRenderer", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", - "signature": "", + "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": { @@ -2949,14 +2536,14 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", - "signature": "", + "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": "", + "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`." } } @@ -2976,28 +2563,28 @@ "name": "MCPServer", "kind": "class", "path": "docforge.servers.MCPServer", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "app": { "name": "app", "kind": "attribute", "path": "docforge.servers.MCPServer.app", - "signature": "", + "signature": null, "docstring": null }, "run": { "name": "run", "kind": "function", "path": "docforge.servers.MCPServer.run", - "signature": "", + "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`." } } @@ -3009,53 +2596,11 @@ "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": { - "annotations": { - "name": "annotations", - "kind": "alias", - "path": "docforge.servers.mcp_server.annotations", - "signature": "", - "docstring": null - }, - "json": { - "name": "json", - "kind": "alias", - "path": "docforge.servers.mcp_server.json", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.servers.mcp_server.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.servers.mcp_server.Any", - "signature": "", - "docstring": null - }, - "Literal": { - "name": "Literal", - "kind": "alias", - "path": "docforge.servers.mcp_server.Literal", - "signature": "", - "docstring": null - }, - "FastMCP": { - "name": "FastMCP", - "kind": "alias", - "path": "docforge.servers.mcp_server.FastMCP", - "signature": "", - "docstring": null - }, "MCPServer": { "name": "MCPServer", "kind": "class", "path": "docforge.servers.mcp_server.MCPServer", - "signature": "", + "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": { @@ -3076,7 +2621,7 @@ "name": "run", "kind": "function", "path": "docforge.servers.mcp_server.MCPServer.run", - "signature": "", + "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`." } } diff --git a/docs/mcp/modules/docforge.loaders.griffe_loader.json b/docs/mcp/modules/docforge.loaders.griffe_loader.json index 82f2bd7..ab2f26e 100644 --- a/docs/mcp/modules/docforge.loaders.griffe_loader.json +++ b/docs/mcp/modules/docforge.loaders.griffe_loader.json @@ -2,118 +2,76 @@ "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\n---", + "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": { - "logging": { - "name": "logging", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.logging", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.Path", - "signature": "", - "docstring": null - }, - "AliasResolutionError": { - "name": "AliasResolutionError", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.AliasResolutionError", - "signature": "", - "docstring": null - }, - "LinesCollection": { - "name": "LinesCollection", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.LinesCollection", - "signature": "", - "docstring": null - }, - "ModulesCollection": { - "name": "ModulesCollection", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.ModulesCollection", - "signature": "", - "docstring": null - }, - "Object": { - "name": "Object", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.Object", - "signature": "", - "docstring": null - }, "DocObject": { "name": "DocObject", "kind": "class", "path": "docforge.loaders.griffe_loader.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -122,49 +80,49 @@ "name": "Module", "kind": "class", "path": "docforge.loaders.griffe_loader.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.loaders.griffe_loader.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.loaders.griffe_loader.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.loaders.griffe_loader.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -173,49 +131,49 @@ "name": "Project", "kind": "class", "path": "docforge.loaders.griffe_loader.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.loaders.griffe_loader.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.loaders.griffe_loader.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -231,28 +189,28 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.loaders.griffe_loader.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "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": "", + "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 ```" } } diff --git a/docs/mcp/modules/docforge.loaders.json b/docs/mcp/modules/docforge.loaders.json index ade3960..93a695a 100644 --- a/docs/mcp/modules/docforge.loaders.json +++ b/docs/mcp/modules/docforge.loaders.json @@ -8,21 +8,21 @@ "name": "GriffeLoader", "kind": "class", "path": "docforge.loaders.GriffeLoader", - "signature": "", + "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": "", + "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": "", + "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 ```" } } @@ -31,7 +31,7 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.loaders.discover_module_paths", - "signature": "", + "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": { @@ -39,118 +39,76 @@ "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\n---", + "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": { - "logging": { - "name": "logging", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.logging", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.Path", - "signature": "", - "docstring": null - }, - "AliasResolutionError": { - "name": "AliasResolutionError", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.AliasResolutionError", - "signature": "", - "docstring": null - }, - "LinesCollection": { - "name": "LinesCollection", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.LinesCollection", - "signature": "", - "docstring": null - }, - "ModulesCollection": { - "name": "ModulesCollection", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.ModulesCollection", - "signature": "", - "docstring": null - }, - "Object": { - "name": "Object", - "kind": "alias", - "path": "docforge.loaders.griffe_loader.Object", - "signature": "", - "docstring": null - }, "DocObject": { "name": "DocObject", "kind": "class", "path": "docforge.loaders.griffe_loader.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.loaders.griffe_loader.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -159,49 +117,49 @@ "name": "Module", "kind": "class", "path": "docforge.loaders.griffe_loader.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.loaders.griffe_loader.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.loaders.griffe_loader.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.loaders.griffe_loader.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -210,49 +168,49 @@ "name": "Project", "kind": "class", "path": "docforge.loaders.griffe_loader.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.loaders.griffe_loader.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.loaders.griffe_loader.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -268,28 +226,28 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.loaders.griffe_loader.discover_module_paths", - "signature": "", + "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": "", + "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": "", + "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": "", + "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 ```" } } diff --git a/docs/mcp/modules/docforge.models.json b/docs/mcp/modules/docforge.models.json index a167787..5f5dab0 100644 --- a/docs/mcp/modules/docforge.models.json +++ b/docs/mcp/modules/docforge.models.json @@ -8,49 +8,49 @@ "name": "Project", "kind": "class", "path": "docforge.models.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.models.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.models.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -59,49 +59,49 @@ "name": "Module", "kind": "class", "path": "docforge.models.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.models.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.models.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.models.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -110,70 +110,70 @@ "name": "DocObject", "kind": "class", "path": "docforge.models.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.models.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.models.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.models.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.models.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.models.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.models.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -185,81 +185,74 @@ "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.models.module.Iterable", - "signature": "", - "docstring": null - }, "DocObject": { "name": "DocObject", "kind": "class", "path": "docforge.models.module.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.models.module.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.models.module.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.models.module.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.models.module.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.models.module.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.models.module.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -268,7 +261,7 @@ "name": "Module", "kind": "class", "path": "docforge.models.module.Module", - "signature": "", + "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": { @@ -296,21 +289,21 @@ "name": "add_object", "kind": "function", "path": "docforge.models.module.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -324,18 +317,11 @@ "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.models.object.Iterable", - "signature": "", - "docstring": null - }, "DocObject": { "name": "DocObject", "kind": "class", "path": "docforge.models.object.DocObject", - "signature": "", + "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": { @@ -384,21 +370,21 @@ "name": "add_member", "kind": "function", "path": "docforge.models.object.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -412,60 +398,53 @@ "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.models.project.Iterable", - "signature": "", - "docstring": null - }, "Module": { "name": "Module", "kind": "class", "path": "docforge.models.project.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.models.project.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.models.project.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.models.project.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -474,7 +453,7 @@ "name": "Project", "kind": "class", "path": "docforge.models.project.Project", - "signature": "", + "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": { @@ -495,28 +474,28 @@ "name": "add_module", "kind": "function", "path": "docforge.models.project.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } diff --git a/docs/mcp/modules/docforge.models.module.json b/docs/mcp/modules/docforge.models.module.json index 12cc47e..927669e 100644 --- a/docs/mcp/modules/docforge.models.module.json +++ b/docs/mcp/modules/docforge.models.module.json @@ -4,81 +4,74 @@ "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.models.module.Iterable", - "signature": "", - "docstring": null - }, "DocObject": { "name": "DocObject", "kind": "class", "path": "docforge.models.module.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.models.module.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.models.module.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.models.module.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.models.module.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.models.module.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.models.module.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -87,7 +80,7 @@ "name": "Module", "kind": "class", "path": "docforge.models.module.Module", - "signature": "", + "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": { @@ -115,21 +108,21 @@ "name": "add_object", "kind": "function", "path": "docforge.models.module.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } diff --git a/docs/mcp/modules/docforge.models.object.json b/docs/mcp/modules/docforge.models.object.json index ff22ae4..4b6c72e 100644 --- a/docs/mcp/modules/docforge.models.object.json +++ b/docs/mcp/modules/docforge.models.object.json @@ -4,18 +4,11 @@ "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.models.object.Iterable", - "signature": "", - "docstring": null - }, "DocObject": { "name": "DocObject", "kind": "class", "path": "docforge.models.object.DocObject", - "signature": "", + "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": { @@ -64,21 +57,21 @@ "name": "add_member", "kind": "function", "path": "docforge.models.object.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } diff --git a/docs/mcp/modules/docforge.models.project.json b/docs/mcp/modules/docforge.models.project.json index 5ae72c9..b0c9f06 100644 --- a/docs/mcp/modules/docforge.models.project.json +++ b/docs/mcp/modules/docforge.models.project.json @@ -4,60 +4,53 @@ "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": { - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.models.project.Iterable", - "signature": "", - "docstring": null - }, "Module": { "name": "Module", "kind": "class", "path": "docforge.models.project.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.models.project.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.models.project.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.models.project.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -66,7 +59,7 @@ "name": "Project", "kind": "class", "path": "docforge.models.project.Project", - "signature": "", + "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": { @@ -87,28 +80,28 @@ "name": "add_module", "kind": "function", "path": "docforge.models.project.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } diff --git a/docs/mcp/modules/docforge.nav.json b/docs/mcp/modules/docforge.nav.json index 6cd1fae..3568800 100644 --- a/docs/mcp/modules/docforge.nav.json +++ b/docs/mcp/modules/docforge.nav.json @@ -8,42 +8,42 @@ "name": "NavSpec", "kind": "class", "path": "docforge.nav.NavSpec", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "groups": { "name": "groups", "kind": "attribute", "path": "docforge.nav.NavSpec.groups", - "signature": "", + "signature": null, "docstring": null }, "icon": { "name": "icon", "kind": "attribute", "path": "docforge.nav.NavSpec.icon", - "signature": "", + "signature": null, "docstring": null }, "load": { "name": "load", "kind": "function", "path": "docforge.nav.NavSpec.load", - "signature": "", + "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": "", + "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." } } @@ -52,35 +52,35 @@ "name": "load_nav_spec", "kind": "function", "path": "docforge.nav.load_nav_spec", - "signature": "", + "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": "", + "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": "", + "signature": null, "docstring": null }, "groups": { "name": "groups", "kind": "attribute", "path": "docforge.nav.ResolvedNav.groups", - "signature": "", + "signature": null, "docstring": null }, "all_files": { "name": "all_files", "kind": "function", "path": "docforge.nav.ResolvedNav.all_files", - "signature": "", + "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." } } @@ -89,21 +89,21 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolve_nav", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -112,7 +112,7 @@ "name": "build_wiki_nav", "kind": "function", "path": "docforge.nav.build_wiki_nav", - "signature": "", + "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": { @@ -122,46 +122,32 @@ "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.nav.mkdocs.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.nav.mkdocs.Any", - "signature": "", - "docstring": null - }, "ResolvedNav": { "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.mkdocs.ResolvedNav", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "groups": { "name": "groups", "kind": "attribute", "path": "docforge.nav.mkdocs.ResolvedNav.groups", - "signature": "", + "signature": null, "docstring": null }, "all_files": { "name": "all_files", "kind": "function", "path": "docforge.nav.mkdocs.ResolvedNav.all_files", - "signature": "", + "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." } } @@ -170,14 +156,14 @@ "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.nav.mkdocs.MkDocsNavEmitter", - "signature": "", + "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": "", + "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." } } @@ -191,67 +177,46 @@ "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": { - "glob": { - "name": "glob", - "kind": "alias", - "path": "docforge.nav.resolver.glob", - "signature": "", - "docstring": null - }, - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.nav.resolver.Iterable", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.nav.resolver.Path", - "signature": "", - "docstring": null - }, "NavSpec": { "name": "NavSpec", "kind": "class", "path": "docforge.nav.resolver.NavSpec", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "groups": { "name": "groups", "kind": "attribute", "path": "docforge.nav.resolver.NavSpec.groups", - "signature": "", + "signature": null, "docstring": null }, "icon": { "name": "icon", "kind": "attribute", "path": "docforge.nav.resolver.NavSpec.icon", - "signature": "", + "signature": null, "docstring": null }, "load": { "name": "load", "kind": "function", "path": "docforge.nav.resolver.NavSpec.load", - "signature": "", + "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": "", + "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." } } @@ -260,7 +225,7 @@ "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.resolver.ResolvedNav", - "signature": "", + "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": { @@ -281,7 +246,7 @@ "name": "all_files", "kind": "function", "path": "docforge.nav.resolver.ResolvedNav.all_files", - "signature": "", + "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." } } @@ -290,7 +255,7 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolver.resolve_nav", - "signature": "", + "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." } } @@ -302,32 +267,11 @@ "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": { - "annotations": { - "name": "annotations", - "kind": "alias", - "path": "docforge.nav.spec.annotations", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.nav.spec.Path", - "signature": "", - "docstring": null - }, - "yaml": { - "name": "yaml", - "kind": "alias", - "path": "docforge.nav.spec.yaml", - "signature": "", - "docstring": null - }, "NavSpec": { "name": "NavSpec", "kind": "class", "path": "docforge.nav.spec.NavSpec", - "signature": "", + "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": { @@ -355,14 +299,14 @@ "name": "load", "kind": "function", "path": "docforge.nav.spec.NavSpec.load", - "signature": "", + "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": "", + "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." } } @@ -371,7 +315,7 @@ "name": "load_nav_spec", "kind": "function", "path": "docforge.nav.spec.load_nav_spec", - "signature": "", + "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." } } @@ -383,39 +327,11 @@ "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": { - "re": { - "name": "re", - "kind": "alias", - "path": "docforge.nav.wiki.re", - "signature": "", - "docstring": null - }, - "Callable": { - "name": "Callable", - "kind": "alias", - "path": "docforge.nav.wiki.Callable", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.nav.wiki.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.nav.wiki.Any", - "signature": "", - "docstring": null - }, "build_wiki_nav": { "name": "build_wiki_nav", "kind": "function", "path": "docforge.nav.wiki.build_wiki_nav", - "signature": "", + "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." } } diff --git a/docs/mcp/modules/docforge.nav.mkdocs.json b/docs/mcp/modules/docforge.nav.mkdocs.json index 9d272f8..5288f18 100644 --- a/docs/mcp/modules/docforge.nav.mkdocs.json +++ b/docs/mcp/modules/docforge.nav.mkdocs.json @@ -4,46 +4,32 @@ "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.nav.mkdocs.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.nav.mkdocs.Any", - "signature": "", - "docstring": null - }, "ResolvedNav": { "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.mkdocs.ResolvedNav", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "groups": { "name": "groups", "kind": "attribute", "path": "docforge.nav.mkdocs.ResolvedNav.groups", - "signature": "", + "signature": null, "docstring": null }, "all_files": { "name": "all_files", "kind": "function", "path": "docforge.nav.mkdocs.ResolvedNav.all_files", - "signature": "", + "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." } } @@ -52,14 +38,14 @@ "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.nav.mkdocs.MkDocsNavEmitter", - "signature": "", + "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": "", + "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." } } diff --git a/docs/mcp/modules/docforge.nav.resolver.json b/docs/mcp/modules/docforge.nav.resolver.json index 2f0432a..1921a28 100644 --- a/docs/mcp/modules/docforge.nav.resolver.json +++ b/docs/mcp/modules/docforge.nav.resolver.json @@ -4,67 +4,46 @@ "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": { - "glob": { - "name": "glob", - "kind": "alias", - "path": "docforge.nav.resolver.glob", - "signature": "", - "docstring": null - }, - "Iterable": { - "name": "Iterable", - "kind": "alias", - "path": "docforge.nav.resolver.Iterable", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.nav.resolver.Path", - "signature": "", - "docstring": null - }, "NavSpec": { "name": "NavSpec", "kind": "class", "path": "docforge.nav.resolver.NavSpec", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "groups": { "name": "groups", "kind": "attribute", "path": "docforge.nav.resolver.NavSpec.groups", - "signature": "", + "signature": null, "docstring": null }, "icon": { "name": "icon", "kind": "attribute", "path": "docforge.nav.resolver.NavSpec.icon", - "signature": "", + "signature": null, "docstring": null }, "load": { "name": "load", "kind": "function", "path": "docforge.nav.resolver.NavSpec.load", - "signature": "", + "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": "", + "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." } } @@ -73,7 +52,7 @@ "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.resolver.ResolvedNav", - "signature": "", + "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": { @@ -94,7 +73,7 @@ "name": "all_files", "kind": "function", "path": "docforge.nav.resolver.ResolvedNav.all_files", - "signature": "", + "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." } } @@ -103,7 +82,7 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolver.resolve_nav", - "signature": "", + "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." } } diff --git a/docs/mcp/modules/docforge.nav.spec.json b/docs/mcp/modules/docforge.nav.spec.json index 825783a..c99c121 100644 --- a/docs/mcp/modules/docforge.nav.spec.json +++ b/docs/mcp/modules/docforge.nav.spec.json @@ -4,32 +4,11 @@ "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": { - "annotations": { - "name": "annotations", - "kind": "alias", - "path": "docforge.nav.spec.annotations", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.nav.spec.Path", - "signature": "", - "docstring": null - }, - "yaml": { - "name": "yaml", - "kind": "alias", - "path": "docforge.nav.spec.yaml", - "signature": "", - "docstring": null - }, "NavSpec": { "name": "NavSpec", "kind": "class", "path": "docforge.nav.spec.NavSpec", - "signature": "", + "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": { @@ -57,14 +36,14 @@ "name": "load", "kind": "function", "path": "docforge.nav.spec.NavSpec.load", - "signature": "", + "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": "", + "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." } } @@ -73,7 +52,7 @@ "name": "load_nav_spec", "kind": "function", "path": "docforge.nav.spec.load_nav_spec", - "signature": "", + "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." } } diff --git a/docs/mcp/modules/docforge.nav.wiki.json b/docs/mcp/modules/docforge.nav.wiki.json index 7fde14e..3d4affb 100644 --- a/docs/mcp/modules/docforge.nav.wiki.json +++ b/docs/mcp/modules/docforge.nav.wiki.json @@ -4,39 +4,11 @@ "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": { - "re": { - "name": "re", - "kind": "alias", - "path": "docforge.nav.wiki.re", - "signature": "", - "docstring": null - }, - "Callable": { - "name": "Callable", - "kind": "alias", - "path": "docforge.nav.wiki.Callable", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.nav.wiki.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.nav.wiki.Any", - "signature": "", - "docstring": null - }, "build_wiki_nav": { "name": "build_wiki_nav", "kind": "function", "path": "docforge.nav.wiki.build_wiki_nav", - "signature": "", + "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." } } diff --git a/docs/mcp/modules/docforge.renderers.base.json b/docs/mcp/modules/docforge.renderers.base.json index 3df962e..a879ee6 100644 --- a/docs/mcp/modules/docforge.renderers.base.json +++ b/docs/mcp/modules/docforge.renderers.base.json @@ -4,67 +4,53 @@ "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.renderers.base.Path", - "signature": "", - "docstring": null - }, - "Protocol": { - "name": "Protocol", - "kind": "alias", - "path": "docforge.renderers.base.Protocol", - "signature": "", - "docstring": null - }, "Project": { "name": "Project", "kind": "class", "path": "docforge.renderers.base.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.renderers.base.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.renderers.base.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -73,7 +59,7 @@ "name": "RendererConfig", "kind": "class", "path": "docforge.renderers.base.RendererConfig", - "signature": "", + "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": { @@ -96,7 +82,7 @@ "name": "DocRenderer", "kind": "class", "path": "docforge.renderers.base.DocRenderer", - "signature": "", + "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": { @@ -110,7 +96,7 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.base.DocRenderer.generate_sources", - "signature": "", + "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." } } diff --git a/docs/mcp/modules/docforge.renderers.json b/docs/mcp/modules/docforge.renderers.json index 2f6f8fc..0eb7e8d 100644 --- a/docs/mcp/modules/docforge.renderers.json +++ b/docs/mcp/modules/docforge.renderers.json @@ -8,28 +8,28 @@ "name": "MkDocsRenderer", "kind": "class", "path": "docforge.renderers.MkDocsRenderer", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.renderers.MkDocsRenderer.generate_sources", - "signature": "", + "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": "", + "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`." } } @@ -38,21 +38,21 @@ "name": "MCPRenderer", "kind": "class", "path": "docforge.renderers.MCPRenderer", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.renderers.MCPRenderer.generate_sources", - "signature": "", + "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." } } @@ -64,67 +64,53 @@ "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.renderers.base.Path", - "signature": "", - "docstring": null - }, - "Protocol": { - "name": "Protocol", - "kind": "alias", - "path": "docforge.renderers.base.Protocol", - "signature": "", - "docstring": null - }, "Project": { "name": "Project", "kind": "class", "path": "docforge.renderers.base.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.renderers.base.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.renderers.base.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -133,7 +119,7 @@ "name": "RendererConfig", "kind": "class", "path": "docforge.renderers.base.RendererConfig", - "signature": "", + "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": { @@ -156,7 +142,7 @@ "name": "DocRenderer", "kind": "class", "path": "docforge.renderers.base.DocRenderer", - "signature": "", + "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": { @@ -170,7 +156,7 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.base.DocRenderer.generate_sources", - "signature": "", + "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." } } @@ -184,88 +170,74 @@ "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": { - "json": { - "name": "json", - "kind": "alias", - "path": "docforge.renderers.mcp_renderer.json", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.renderers.mcp_renderer.Path", - "signature": "", - "docstring": null - }, "DocObject": { "name": "DocObject", "kind": "class", "path": "docforge.renderers.mcp_renderer.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -274,49 +246,49 @@ "name": "Module", "kind": "class", "path": "docforge.renderers.mcp_renderer.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.renderers.mcp_renderer.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -325,49 +297,49 @@ "name": "Project", "kind": "class", "path": "docforge.renderers.mcp_renderer.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -376,7 +348,7 @@ "name": "MCPRenderer", "kind": "class", "path": "docforge.renderers.mcp_renderer.MCPRenderer", - "signature": "", + "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": { @@ -390,17 +362,10 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources", - "signature": "", + "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." } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.renderers.mcp_renderer.Any", - "signature": "", - "docstring": null } } }, @@ -411,60 +376,53 @@ "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.renderers.mkdocs_renderer.Path", - "signature": "", - "docstring": null - }, "Module": { "name": "Module", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.renderers.mkdocs_renderer.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.renderers.mkdocs_renderer.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -473,49 +431,49 @@ "name": "Project", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.renderers.mkdocs_renderer.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -524,7 +482,7 @@ "name": "MkDocsRenderer", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", - "signature": "", + "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": { @@ -538,14 +496,14 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", - "signature": "", + "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": "", + "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`." } } diff --git a/docs/mcp/modules/docforge.renderers.mcp_renderer.json b/docs/mcp/modules/docforge.renderers.mcp_renderer.json index 3fc1e34..a9b54d4 100644 --- a/docs/mcp/modules/docforge.renderers.mcp_renderer.json +++ b/docs/mcp/modules/docforge.renderers.mcp_renderer.json @@ -4,88 +4,74 @@ "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": { - "json": { - "name": "json", - "kind": "alias", - "path": "docforge.renderers.mcp_renderer.json", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.renderers.mcp_renderer.Path", - "signature": "", - "docstring": null - }, "DocObject": { "name": "DocObject", "kind": "class", "path": "docforge.renderers.mcp_renderer.DocObject", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "kind": { "name": "kind", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.kind", - "signature": "", + "signature": null, "docstring": null }, "path": { "name": "path", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.path", - "signature": "", + "signature": null, "docstring": null }, "signature": { "name": "signature", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.signature", - "signature": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.DocObject.members", - "signature": "", + "signature": null, "docstring": null }, "add_member": { "name": "add_member", "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.add_member", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -94,49 +80,49 @@ "name": "Module", "kind": "class", "path": "docforge.renderers.mcp_renderer.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.renderers.mcp_renderer.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -145,49 +131,49 @@ "name": "Project", "kind": "class", "path": "docforge.renderers.mcp_renderer.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.renderers.mcp_renderer.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -196,7 +182,7 @@ "name": "MCPRenderer", "kind": "class", "path": "docforge.renderers.mcp_renderer.MCPRenderer", - "signature": "", + "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": { @@ -210,17 +196,10 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources", - "signature": "", + "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." } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.renderers.mcp_renderer.Any", - "signature": "", - "docstring": null } } } diff --git a/docs/mcp/modules/docforge.renderers.mkdocs_renderer.json b/docs/mcp/modules/docforge.renderers.mkdocs_renderer.json index 1e468a0..3454abb 100644 --- a/docs/mcp/modules/docforge.renderers.mkdocs_renderer.json +++ b/docs/mcp/modules/docforge.renderers.mkdocs_renderer.json @@ -4,60 +4,53 @@ "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": { - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.renderers.mkdocs_renderer.Path", - "signature": "", - "docstring": null - }, "Module": { "name": "Module", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Module", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "docstring": { "name": "docstring", "kind": "attribute", "path": "docforge.renderers.mkdocs_renderer.Module.docstring", - "signature": "", + "signature": null, "docstring": null }, "members": { "name": "members", "kind": "attribute", "path": "docforge.renderers.mkdocs_renderer.Module.members", - "signature": "", + "signature": null, "docstring": null }, "add_object": { "name": "add_object", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Module.add_object", - "signature": "", + "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": "", + "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": "", + "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." } } @@ -66,49 +59,49 @@ "name": "Project", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Project", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "modules": { "name": "modules", "kind": "attribute", "path": "docforge.renderers.mkdocs_renderer.Project.modules", - "signature": "", + "signature": null, "docstring": null }, "add_module": { "name": "add_module", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.add_module", - "signature": "", + "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": "", + "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": "", + "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": "", + "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." } } @@ -117,7 +110,7 @@ "name": "MkDocsRenderer", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", - "signature": "", + "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": { @@ -131,14 +124,14 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", - "signature": "", + "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": "", + "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`." } } diff --git a/docs/mcp/modules/docforge.servers.json b/docs/mcp/modules/docforge.servers.json index c82cf66..4bf8fb2 100644 --- a/docs/mcp/modules/docforge.servers.json +++ b/docs/mcp/modules/docforge.servers.json @@ -8,28 +8,28 @@ "name": "MCPServer", "kind": "class", "path": "docforge.servers.MCPServer", - "signature": "", + "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": "", + "signature": null, "docstring": null }, "app": { "name": "app", "kind": "attribute", "path": "docforge.servers.MCPServer.app", - "signature": "", + "signature": null, "docstring": null }, "run": { "name": "run", "kind": "function", "path": "docforge.servers.MCPServer.run", - "signature": "", + "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`." } } @@ -41,53 +41,11 @@ "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": { - "annotations": { - "name": "annotations", - "kind": "alias", - "path": "docforge.servers.mcp_server.annotations", - "signature": "", - "docstring": null - }, - "json": { - "name": "json", - "kind": "alias", - "path": "docforge.servers.mcp_server.json", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.servers.mcp_server.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.servers.mcp_server.Any", - "signature": "", - "docstring": null - }, - "Literal": { - "name": "Literal", - "kind": "alias", - "path": "docforge.servers.mcp_server.Literal", - "signature": "", - "docstring": null - }, - "FastMCP": { - "name": "FastMCP", - "kind": "alias", - "path": "docforge.servers.mcp_server.FastMCP", - "signature": "", - "docstring": null - }, "MCPServer": { "name": "MCPServer", "kind": "class", "path": "docforge.servers.mcp_server.MCPServer", - "signature": "", + "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": { @@ -108,7 +66,7 @@ "name": "run", "kind": "function", "path": "docforge.servers.mcp_server.MCPServer.run", - "signature": "", + "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`." } } diff --git a/docs/mcp/modules/docforge.servers.mcp_server.json b/docs/mcp/modules/docforge.servers.mcp_server.json index a7a69f8..a1fb995 100644 --- a/docs/mcp/modules/docforge.servers.mcp_server.json +++ b/docs/mcp/modules/docforge.servers.mcp_server.json @@ -4,53 +4,11 @@ "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": { - "annotations": { - "name": "annotations", - "kind": "alias", - "path": "docforge.servers.mcp_server.annotations", - "signature": "", - "docstring": null - }, - "json": { - "name": "json", - "kind": "alias", - "path": "docforge.servers.mcp_server.json", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "docforge.servers.mcp_server.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.servers.mcp_server.Any", - "signature": "", - "docstring": null - }, - "Literal": { - "name": "Literal", - "kind": "alias", - "path": "docforge.servers.mcp_server.Literal", - "signature": "", - "docstring": null - }, - "FastMCP": { - "name": "FastMCP", - "kind": "alias", - "path": "docforge.servers.mcp_server.FastMCP", - "signature": "", - "docstring": null - }, "MCPServer": { "name": "MCPServer", "kind": "class", "path": "docforge.servers.mcp_server.MCPServer", - "signature": "", + "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": { @@ -71,7 +29,7 @@ "name": "run", "kind": "function", "path": "docforge.servers.mcp_server.MCPServer.run", - "signature": "", + "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`." } } diff --git a/tests/renderers/mcp/test_mcp_signatures.py b/tests/renderers/mcp/test_mcp_signatures.py new file mode 100644 index 0000000..9f2cc09 --- /dev/null +++ b/tests/renderers/mcp/test_mcp_signatures.py @@ -0,0 +1,73 @@ +import json +from pathlib import Path + +from docforge import MCPRenderer +from docforge.loaders import GriffeLoader, discover_module_paths + + +def _load_docforge_bundle(tmp_path: Path) -> Path: + project_root = Path(__file__).resolve().parents[3] + loader = GriffeLoader() + paths = discover_module_paths("docforge", project_root=project_root) + project = loader.load_project(paths) + + out_dir = tmp_path / "mcp" + MCPRenderer().generate_sources(project, out_dir) + return out_dir + + +def test_mcp_signatures_are_clean(tmp_path: Path) -> None: + out_dir = _load_docforge_bundle(tmp_path) + + object_payload = json.loads( + (out_dir / "modules" / "docforge.models.object.json").read_text( + encoding="utf-8" + ) + ) + + cls = object_payload["content"]["objects"]["DocObject"] + assert isinstance(cls["signature"], str) + assert "bound method" not in cls["signature"] + assert cls["signature"].startswith("DocObject(") + + renderer_payload = json.loads( + (out_dir / "modules" / "docforge.renderers.mcp_renderer.json").read_text( + encoding="utf-8" + ) + ) + + method = renderer_payload["content"]["objects"]["MCPRenderer"]["members"][ + "generate_sources" + ] + assert isinstance(method["signature"], str) + assert "bound method" not in method["signature"] + assert method["signature"].startswith("generate_sources(") + + +def test_mcp_skips_unresolvable_import_aliases(tmp_path: Path) -> None: + out_dir = _load_docforge_bundle(tmp_path) + + renderer_payload = json.loads( + (out_dir / "modules" / "docforge.renderers.mcp_renderer.json").read_text( + encoding="utf-8" + ) + ) + + object_names = set(renderer_payload["content"]["objects"]) + assert "json" not in object_names + assert "Path" not in object_names + + +def test_mcp_keeps_resolvable_package_reexports(tmp_path: Path) -> None: + out_dir = _load_docforge_bundle(tmp_path) + + root_payload = json.loads( + (out_dir / "modules" / "docforge.json").read_text(encoding="utf-8") + ) + + discover = root_payload["content"]["objects"]["discover_module_paths"] + assert discover["name"] == "discover_module_paths" + assert isinstance(discover["signature"], str) + assert "bound method" not in discover["signature"] + assert discover["signature"].startswith("discover_module_paths(") + assert discover["docstring"] is not None