From 582b6809a07090d26a019f570a3e3fd5ecc99063 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sat, 12 Sep 2026 13:12:51 +0530 Subject: [PATCH] docs: bring docforge docstrings and wiki to GSDFC standard - fix GSDFC spec contradictions in __init__ docstring (parenthesized types, fenced-block rule) and sync generated README - rewrite docstrings across loaders, models, nav, servers, renderers, cli; sync .pyi stubs - add pydoclint (google style) gate to dev extras and pyproject config - fix mcp nav resources doc:// -> docs:// - refresh docs/lib and docs/mcp, drop stale docforge/ duplicate group - update wiki pages and add GSDFC + MCP guides under 05_development --- README.md | 21 +- docforge/__init__.py | 21 +- docforge/cli/api_utils.py | 12 +- docforge/cli/commands.py | 40 +- docforge/cli/commands.pyi | 5 +- docforge/cli/mcp_utils.py | 12 +- docforge/cli/mkdocs_utils.py | 46 +- docforge/loaders/griffe_loader.py | 43 +- docforge/loaders/griffe_loader.pyi | 3 +- docforge/models/module.py | 13 +- docforge/models/object.py | 21 +- docforge/models/project.py | 18 +- docforge/nav/mkdocs.py | 27 +- docforge/nav/resolver.py | 38 +- docforge/nav/spec.py | 39 +- docforge/nav/wiki.py | 14 +- docforge/nav/wiki.pyi | 32 +- docforge/renderers/mcp_renderer.py | 8 +- docforge/renderers/mkdocs_renderer.py | 19 +- docforge/servers/mcp_server.py | 18 + docforge/servers/mcp_server.pyi | 5 +- 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/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/lib/{docforge => }/nav/wiki.md | 0 docs/mcp/index.json | 2 +- docs/mcp/modules/docforge.cli.api_utils.json | 12 +- docs/mcp/modules/docforge.cli.commands.json | 150 ++++-- docs/mcp/modules/docforge.cli.json | 219 +++++--- docs/mcp/modules/docforge.cli.mcp_utils.json | 18 +- .../modules/docforge.cli.mkdocs_utils.json | 39 +- docs/mcp/modules/docforge.json | 469 +++++++++++------- .../docforge.loaders.griffe_loader.json | 26 +- docs/mcp/modules/docforge.loaders.json | 34 +- docs/mcp/modules/docforge.models.json | 54 +- docs/mcp/modules/docforge.models.module.json | 16 +- docs/mcp/modules/docforge.models.object.json | 14 +- docs/mcp/modules/docforge.models.project.json | 16 +- docs/mcp/modules/docforge.nav.json | 112 ++++- docs/mcp/modules/docforge.nav.mkdocs.json | 10 +- docs/mcp/modules/docforge.nav.resolver.json | 16 +- docs/mcp/modules/docforge.nav.spec.json | 23 +- docs/mcp/modules/docforge.nav.wiki.json | 44 ++ docs/mcp/modules/docforge.renderers.base.json | 2 +- docs/mcp/modules/docforge.renderers.json | 26 +- .../docforge.renderers.mcp_renderer.json | 8 +- .../docforge.renderers.mkdocs_renderer.json | 12 +- docs/mcp/modules/docforge.servers.json | 10 +- .../modules/docforge.servers.mcp_server.json | 8 +- docs/mcp/nav.json | 50 +- docs/wiki/01_overview.md | 10 +- docs/wiki/02_architecture.md | 10 +- docs/wiki/03_conventions.md | 15 +- docs/wiki/04_iterative_workflow.md | 14 +- docs/wiki/05_development/01_environment.md | 5 +- docs/wiki/05_development/02_quality_gates.md | 1 + docs/wiki/05_development/03_gsdfc_guide.md | 108 ++++ docs/wiki/05_development/04_mcp_guide.md | 51 ++ docs/wiki/index.md | 7 +- mkdocs.yml | 2 + pyproject.toml | 9 + 82 files changed, 1467 insertions(+), 703 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/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 rename docs/lib/{docforge => }/nav/wiki.md (100%) create mode 100644 docs/mcp/modules/docforge.nav.wiki.json create mode 100644 docs/wiki/05_development/03_gsdfc_guide.md create mode 100644 docs/wiki/05_development/04_mcp_guide.md diff --git a/README.md b/README.md index 6a3a6f1..f43539d 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,18 @@ doc-forge build --mcp --module my_package doc-forge build --mcp --mkdocs --module my_package ``` +## Include a hand-written wiki in the MkDocs site: + +```bash +doc-forge build --wiki --mkdocs --module my_package +``` + +## Build wiki pages only (no module required): + +```bash +doc-forge build --wiki --site-name my_package +``` + ## Serve MkDocs locally: ```bash @@ -130,7 +142,9 @@ GSDFC defines how docstrings must be written so they render correctly in MkDocs - Use **Markdown headings** at package and module level. - Use **Google-style structured sections** at class, function, and method level. -- Use type hints in signatures instead of duplicating types in prose. +- Use type hints in signatures. +- Use parenthesized types in prose entries (`name (Type):`) that match the + signature types. This keeps docstrings self-contained and machine-parseable. - Write summaries in imperative form. - Sections are separated by `---` @@ -190,7 +204,10 @@ Example: engine.run() ``` -Avoid fenced code blocks inside structured sections. +Avoid fenced code blocks inside argument descriptions and other prose lines. + +Inside `Example:` sections, fenced `python` code blocks are allowed and must be +indented four spaces, matching the examples below. --- diff --git a/docforge/__init__.py b/docforge/__init__.py index a777233..09418ef 100644 --- a/docforge/__init__.py +++ b/docforge/__init__.py @@ -41,6 +41,18 @@ doc-forge build --mcp --module my_package doc-forge build --mcp --mkdocs --module my_package ``` +## Include a hand-written wiki in the MkDocs site: + +```bash +doc-forge build --wiki --mkdocs --module my_package +``` + +## Build wiki pages only (no module required): + +```bash +doc-forge build --wiki --site-name my_package +``` + ## Serve MkDocs locally: ```bash @@ -129,7 +141,9 @@ GSDFC defines how docstrings must be written so they render correctly in MkDocs - Use **Markdown headings** at package and module level. - Use **Google-style structured sections** at class, function, and method level. -- Use type hints in signatures instead of duplicating types in prose. +- Use type hints in signatures. +- Use parenthesized types in prose entries (`name (Type):`) that match the + signature types. This keeps docstrings self-contained and machine-parseable. - Write summaries in imperative form. - Sections are separated by `---` @@ -189,7 +203,10 @@ Example: engine.run() ``` -Avoid fenced code blocks inside structured sections. +Avoid fenced code blocks inside argument descriptions and other prose lines. + +Inside `Example:` sections, fenced `python` code blocks are allowed and must be +indented four spaces, matching the examples below. --- diff --git a/docforge/cli/api_utils.py b/docforge/cli/api_utils.py index cb760c7..2041967 100644 --- a/docforge/cli/api_utils.py +++ b/docforge/cli/api_utils.py @@ -35,7 +35,8 @@ def load_openapi_spec(spec_path: Path) -> dict: Load and validate an OpenAPI specification from a JSON file. Args: - spec_path: Path to the OpenAPI JSON specification file. + spec_path (Path): + Path to the OpenAPI JSON specification file. Returns: dict: @@ -68,7 +69,8 @@ def derive_metadata(spec: dict) -> OpenAPIMetadata: Derive MkDocs site metadata from an OpenAPI spec ``info`` block. Args: - spec: Parsed OpenAPI specification. + spec (dict): + Parsed OpenAPI specification. Returns: OpenAPIMetadata: @@ -97,8 +99,10 @@ def generate_api_sources(spec: dict, docs_dir: Path) -> None: an ``index.md`` embedding the swagger UI is generated alongside it. Args: - spec: Parsed OpenAPI specification. - docs_dir: Directory (for example ``docs/api``) where the swagger + spec (dict): + Parsed OpenAPI specification. + docs_dir (Path): + Directory (for example ``docs/api``) where the swagger sources are written. """ docs_dir.mkdir(parents=True, exist_ok=True) diff --git a/docforge/cli/commands.py b/docforge/cli/commands.py index 7a5e845..8d1ba46 100644 --- a/docforge/cli/commands.py +++ b/docforge/cli/commands.py @@ -4,6 +4,15 @@ Command definitions for the doc-forge CLI. Provides the CLI structure using Click, including build, serve, and tree commands. + +--- + +Notes: + - The `build` command validates requested modes before generating anything. + - `--mkdocs`, `--api`, and `--wiki` share a single MkDocs build; `--mcp` + generates a machine-readable bundle independently. + +--- """ from pathlib import Path @@ -12,6 +21,7 @@ import click from docforge.cli import api_utils, mcp_utils, mkdocs_utils from docforge.loaders import GriffeLoader +from docforge.models import DocObject @click.group() @@ -99,9 +109,9 @@ def build( """ Build documentation artifacts. - This command performs the full documentation build pipeline: - style of the selected platform, generates renderer-specific - documentation sources, and optionally builds the final output. + This command runs the full documentation pipeline: it loads Python + modules, generates renderer-specific documentation sources, and + optionally builds or serves the final output. Depending on the selected options, the build can target: @@ -110,6 +120,12 @@ def build( - Hand-written wiki pages included in the MkDocs site - MCP structured documentation resources + Notes: + - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be + provided. + - `--mkdocs`, `--api`, and `--wiki` are combined into a single MkDocs + build, while `--mcp` emits a machine-readable bundle. + Args: mcp (bool): Enable MCP documentation generation. @@ -126,16 +142,16 @@ def build( module_is_source (bool): Treat the specified module directory as the project root. - module (Optional[str]): + module (str | None): Python module import path to document. - openapi_spec (Optional[Path]): + openapi_spec (Path | None): Path to the OpenAPI JSON specification used for API docs. - project_name (Optional[str]): + project_name (str | None): Optional override for the project name. - site_name (Optional[str]): + site_name (str | None): Display name for the MkDocs site. docs_dir (Path): @@ -147,7 +163,7 @@ def build( nav_file (Path): Path to the navigation specification file. - template (Optional[Path]): + template (Path | None): Optional custom MkDocs configuration template. mkdocs_yml (Path): @@ -282,7 +298,7 @@ def serve( mkdocs (bool): Serve the MkDocs development site. - module (Optional[str]): + module (str | None): Python module import path to serve via MCP. mkdocs_yml (Path): @@ -333,7 +349,7 @@ def tree( module (str): Python module import path to introspect. - project_name (Optional[str]): + project_name (str | None): Optional name to display as the project root. """ loader = GriffeLoader() @@ -347,7 +363,7 @@ def tree( _print_object(obj, indent="│ ") -def _print_object(obj, indent: str) -> None: +def _print_object(obj: DocObject, indent: str) -> None: """ Recursively print a documentation object and its members. @@ -355,7 +371,7 @@ def _print_object(obj, indent: str) -> None: and prints each object with indentation to represent hierarchy. Args: - obj: + obj (DocObject): Documentation object to print. indent (str): diff --git a/docforge/cli/commands.pyi b/docforge/cli/commands.pyi index 92c3167..4b2bd22 100644 --- a/docforge/cli/commands.pyi +++ b/docforge/cli/commands.pyi @@ -1,8 +1,9 @@ from pathlib import Path -from typing import Any from click.core import Group +from docforge.models import DocObject + cli: Group def build( @@ -33,4 +34,4 @@ def tree( module: str, project_name: str | None, ) -> None: ... -def _print_object(obj: Any, indent: str) -> None: ... +def _print_object(obj: DocObject, indent: str) -> None: ... diff --git a/docforge/cli/mcp_utils.py b/docforge/cli/mcp_utils.py index a47cef5..41aef9a 100644 --- a/docforge/cli/mcp_utils.py +++ b/docforge/cli/mcp_utils.py @@ -2,6 +2,16 @@ # Summary Utilities for working with MCP in the doc-forge CLI. + +--- + +Notes: + - `generate_resources` produces the bundle consumed by `MCPServer`: + `index.json`, `nav.json`, and per-module resources under `modules/`. + - Resource URIs use the `docs://` scheme: `docs://index`, `docs://nav`, + and `docs://modules/{module}`. + +--- """ from pathlib import Path @@ -26,7 +36,7 @@ def generate_resources(module: str, project_name: str | None, out_dir: Path) -> Python module import path used as the entry point for documentation generation. - project_name (Optional[str]): + project_name (str | None): Optional override for the project name used in generated documentation metadata. diff --git a/docforge/cli/mkdocs_utils.py b/docforge/cli/mkdocs_utils.py index 949133e..db9b002 100644 --- a/docforge/cli/mkdocs_utils.py +++ b/docforge/cli/mkdocs_utils.py @@ -2,6 +2,15 @@ # Summary Utilities for working with MkDocs in the doc-forge CLI. + +--- + +Notes: + - A single generated `mkdocs.yml` serves lib, api, and wiki content with + merged navigation. Wiki navigation, when enabled, precedes every other + group and its `index.md` becomes the site `Home`. + +--- """ import os @@ -44,14 +53,14 @@ def generate_sources( docs_dir (Path): Directory where the generated Markdown files will be written. - project_name (Optional[str]): + project_name (str | None): Optional override for the project name used in documentation metadata. - module_is_source (Optional[bool]): + module_is_source (bool | None): If True, treat the specified module directory as the project root rather than a nested module. - readme_dir (Optional[Path]): + readme_dir (Path | None): Directory where the generated README.md should be written. If not provided, defaults to the parent of ``docs_dir``. """ @@ -105,7 +114,7 @@ def generate_config( nav_file (Path): Path to the `docforge.nav.yml` navigation specification. - template (Optional[Path]): + template (Path | None): Optional path to a fully custom MkDocs configuration template. If not provided, built-in templates are merged; the provided template replaces the built-in templates entirely. @@ -116,19 +125,19 @@ def generate_config( site_name (str): Display name for the generated documentation site. - modes (Optional[Iterable[str]]): + modes (Iterable[str] | None): Documentation modes to enable. Each mode contributes its own built-in template fragment (for example ``lib``, ``api``, or ``wiki``), merged on top of the shared ``mkdocs.common.yml`` template. - site_description (Optional[str]): + site_description (str | None): Optional site description written into the configuration. - site_author (Optional[str]): + site_author (str | None): Optional site author written into the configuration. - wiki_dir (Optional[Path]): + wiki_dir (Path | None): Optional path to a hand-written wiki directory (for example ``docs/wiki``). When provided, the site navigation is derived from the wiki file structure and placed before the navigation @@ -186,13 +195,13 @@ def _load_template( When a custom template path is provided, it is used as-is. Otherwise the shared ``mkdocs.common.yml`` template is deep-merged with the fragments - contributed by each enabled mode (``lib`` or ``api``). + contributed by each enabled mode (``lib``, ``api``, or ``wiki``). Args: - template (Optional[Path]): + template (Path | None): Optional fully custom template that replaces the built-ins. - modes (Optional[Iterable[str]]): + modes (Iterable[str] | None): Documentation modes whose template fragments should be merged. Returns: @@ -237,7 +246,8 @@ def _item_name(item: object) -> str: first key. This is used to deduplicate plugin and extension lists. Args: - item: List entry, either a string or a single-key mapping. + item (object): + List entry, either a string or a single-key mapping. Returns: str: @@ -253,8 +263,10 @@ def _merge_list(base: list, added: list) -> list: Merge two lists, preserving order and dropping duplicates by name. Args: - base: Existing list entries. - added: Entries to append when not already present. + base (list): + Existing list entries. + added (list): + Entries to append when not already present. Returns: list: @@ -279,8 +291,10 @@ def _deep_merge(base: dict, part: dict) -> dict: the fragment override the base. Args: - base: Configuration being built up. - part: Template fragment to merge into the base. + base (dict): + Configuration being built up. + part (dict): + Template fragment to merge into the base. Returns: dict: diff --git a/docforge/loaders/griffe_loader.py b/docforge/loaders/griffe_loader.py index c71c74f..43fa841 100644 --- a/docforge/loaders/griffe_loader.py +++ b/docforge/loaders/griffe_loader.py @@ -6,6 +6,14 @@ Utilities for loading and introspecting Python modules using Griffe. This module provides the `GriffeLoader` class and helper utilities used to discover Python modules, introspect their structure, and convert the results into doc-forge documentation models. + +--- + +Notes: + - All analysis is static; analyzed modules are never executed. + - Private members (names starting with `_`) are skipped during conversion. + +--- """ import logging @@ -46,12 +54,12 @@ def discover_module_paths( module_name (str): Top-level package name to discover modules from. - project_root (Path, optional): + project_root (Path | None): Root directory used to resolve module paths. If not provided, the current working directory is used. Returns: - List[str]: + list[str]: A sorted list of unique dotted module import paths. Raises: @@ -88,6 +96,10 @@ class GriffeLoader: This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into `Project`, `Module`, and `DocObject` instances used by doc-forge. + + Attributes: + _loader (_GriffeLoader): + Internal Griffe loader with dedicated module and line collections. """ def __init__(self) -> None: @@ -106,7 +118,7 @@ class GriffeLoader: self, module_paths: list[str], project_name: str | None = None, - skip_import_errors: bool = None, + skip_import_errors: bool | None = None, ) -> Project: """ Load multiple modules and assemble them into a Project model. @@ -116,14 +128,14 @@ class GriffeLoader: object. Args: - module_paths (List[str]): + module_paths (list[str]): List of dotted module import paths to load. - project_name (str, optional): + project_name (str | None): Optional override for the project name. Defaults to the top-level name of the first module. - skip_import_errors (bool, optional): + skip_import_errors (bool | None): If True, modules that fail to load will be skipped instead of raising an error. Returns: @@ -172,6 +184,21 @@ class GriffeLoader: Returns: Module: A populated `Module` instance. + + Raises: + ImportError: + If the module cannot be loaded by Griffe. + + KeyError: + If the loaded module is missing from the module collection. + + Example: + Load a single module: + + ```python + loader = GriffeLoader() + module = loader.load_module("mypackage.submodule") + ``` """ self._loader.load(path) griffe_module = self._loader.modules_collection[path] @@ -260,7 +287,7 @@ class GriffeLoader: Griffe object to inspect. Returns: - Optional[str]: + str | None: The raw docstring text if available, otherwise `None`. """ try: @@ -277,7 +304,7 @@ class GriffeLoader: Griffe object to inspect. Returns: - Optional[str]: + str | None: String representation of the object's signature if available, otherwise `None`. """ try: diff --git a/docforge/loaders/griffe_loader.pyi b/docforge/loaders/griffe_loader.pyi index bbded1c..1fa04b0 100644 --- a/docforge/loaders/griffe_loader.pyi +++ b/docforge/loaders/griffe_loader.pyi @@ -11,6 +11,7 @@ class GriffeLoader: """Griffe-based introspection loaders. This is the only supported introspection backend in doc-forge. + Converts Griffe results into `Project`, `Module`, and `DocObject` models. """ def __init__(self) -> None: ... @@ -18,7 +19,7 @@ class GriffeLoader: self, module_paths: list[str], project_name: str | None = ..., - skip_import_errors: bool = ..., + skip_import_errors: bool | None = ..., ) -> Project: """Load a documentation project from Python modules.""" diff --git a/docforge/models/module.py b/docforge/models/module.py index cc58412..7d17f1f 100644 --- a/docforge/models/module.py +++ b/docforge/models/module.py @@ -7,6 +7,13 @@ This module defines the `Module` class used in the doc-forge documentation model. A `Module` acts as a container for top-level documented objects (classes, functions, variables, and other members) discovered during introspection. + +--- + +Notes: + - Only public members are stored; private names are filtered by the loader. + +--- """ from collections.abc import Iterable @@ -26,10 +33,10 @@ class Module: path (str): Dotted import path of the module. - docstring (Optional[str]): + docstring (str | None): Module-level documentation string, if present. - members (Dict[str, DocObject]): + members (dict[str, DocObject]): Mapping of object names to their corresponding `DocObject` representations. """ @@ -45,7 +52,7 @@ class Module: path (str): Dotted import path identifying the module. - docstring (Optional[str]): + docstring (str | None): Module-level documentation text, if available. """ self.path = path diff --git a/docforge/models/object.py b/docforge/models/object.py index 200ec85..17e51f8 100644 --- a/docforge/models/object.py +++ b/docforge/models/object.py @@ -7,6 +7,14 @@ This module defines the `DocObject` class, the fundamental recursive unit of the doc-forge documentation model. Each `DocObject` represents a Python entity such as a class, function, method, or attribute, and may contain nested members that form a hierarchical documentation structure. + +--- + +Notes: + - `DocObject` instances form a tree mirroring the Python import hierarchy. + - Objects are renderer-agnostic and may be consumed by any renderer. + +--- """ from collections.abc import Iterable @@ -30,13 +38,13 @@ class DocObject: path (str): Fully qualified dotted path to the object. - signature (Optional[str]): + signature (str | None): Callable signature if the object represents a callable. - docstring (Optional[str]): + docstring (str | None): Raw docstring text extracted from the source code. - members (Dict[str, DocObject]): + members (dict[str, DocObject]): Mapping of member names to child `DocObject` instances. """ @@ -61,10 +69,10 @@ class DocObject: path (str): Fully qualified dotted path of the object. - signature (Optional[str]): + signature (str | None): Callable signature if applicable. - docstring (Optional[str]): + docstring (str | None): Documentation string associated with the object. """ self.name = name @@ -82,7 +90,8 @@ class DocObject: nested objects to their parent containers. Args: - obj: Documentation object to add as a member. + obj (DocObject): + Documentation object to add as a member. """ self.members[obj.name] = obj diff --git a/docforge/models/project.py b/docforge/models/project.py index 0dde674..7760703 100644 --- a/docforge/models/project.py +++ b/docforge/models/project.py @@ -6,6 +6,14 @@ Documentation model representing a project. This module defines the `Project` class, the top-level container used by doc-forge to represent a documented codebase. A `Project` aggregates multiple modules and provides access to them through a unified interface. + +--- + +Notes: + - Modules are keyed by their dotted import path. + - Objects are renderer-agnostic; the same model feeds every renderer. + +--- """ from collections.abc import Iterable @@ -24,7 +32,7 @@ class Project: name (str): Name of the project. - modules (Dict[str, Module]): + modules (dict[str, Module]): Mapping of module paths to `Module` instances. """ @@ -35,6 +43,14 @@ class Project: Args: name (str): Name used to identify the documentation project. + + Example: + Create a project and register a module: + + ```python + project = Project("mypackage") + project.add_module(module) + ``` """ self.name = name self.modules: dict[str, Module] = {} diff --git a/docforge/nav/mkdocs.py b/docforge/nav/mkdocs.py index 54418fd..7f33d9b 100644 --- a/docforge/nav/mkdocs.py +++ b/docforge/nav/mkdocs.py @@ -4,6 +4,14 @@ MkDocs navigation emitter. This module provides the ``MkDocsNavEmitter`` class, which converts a ``ResolvedNav`` instance into the navigation structure required by the MkDocs ``nav`` configuration. + +--- + +Notes: + - The emitted structure is a list of dictionaries, one per top-level nav + entry, matching the MkDocs ``nav`` YAML format. + +--- """ from pathlib import Path @@ -25,13 +33,15 @@ class MkDocsNavEmitter: Generate a navigation structure for ``mkdocs.yml``. Args: - nav: Resolved navigation data describing documentation groups + nav (ResolvedNav): + Resolved navigation data describing documentation groups and their associated Markdown files. Returns: - A list of dictionaries representing the MkDocs navigation layout. - Each dictionary maps a navigation label to a page or a list of - pages. + list[dict[str, Any]]: + A list of dictionaries representing the MkDocs navigation layout. + Each dictionary maps a navigation label to a page or a list of + pages. """ result: list[dict[str, Any]] = [] @@ -59,11 +69,14 @@ class MkDocsNavEmitter: resulting path is relative to the documentation root. Args: - path: Filesystem path to convert. - docs_root: Root directory of the documentation sources. + path (Path): + Filesystem path to convert. + docs_root (Path | None): + Root directory of the documentation sources. Returns: - POSIX-style path relative to the documentation root. + str: + POSIX-style path relative to the documentation root. """ if docs_root and path.is_absolute(): try: diff --git a/docforge/nav/resolver.py b/docforge/nav/resolver.py index d32fa38..f3c2382 100644 --- a/docforge/nav/resolver.py +++ b/docforge/nav/resolver.py @@ -3,6 +3,14 @@ Navigation resolution utilities. This module resolves a ``NavSpec`` against the filesystem by expanding glob patterns and validating that referenced documentation files exist. + +--- + +Notes: + - Glob resolution is recursive and returns paths in sorted order. + - Unmatched patterns raise ``FileNotFoundError`` to fail fast on typos. + +--- """ import glob @@ -35,9 +43,12 @@ class ResolvedNav: Initialize a ResolvedNav instance. Args: - home: Relative path to the home page within the documentation root. - groups: Mapping of group titles to resolved documentation file paths. - docs_root: Root directory of the documentation source files. + home (str | None): + Relative path to the home page within the documentation root. + groups (dict[str, list[Path]]): + Mapping of group titles to resolved documentation file paths. + docs_root (Path | None): + Root directory of the documentation source files. """ self.home = home self.groups = groups @@ -47,8 +58,10 @@ class ResolvedNav: """ Iterate over all files referenced by the navigation structure. - Returns: - An iterable of ``Path`` objects representing documentation files. + Yields: + Path: + A documentation file referenced by the navigation, including + the home page when defined. Raises: RuntimeError: If the home page is defined but the documentation @@ -74,11 +87,14 @@ def resolve_nav( that referenced documentation files exist within the documentation root. Args: - spec: Navigation specification describing documentation layout. - docs_root: Root directory containing documentation Markdown files. + spec (NavSpec): + Navigation specification describing documentation layout. + docs_root (Path): + Root directory containing documentation Markdown files. Returns: - A ``ResolvedNav`` instance containing validated navigation paths. + ResolvedNav: + A `ResolvedNav` instance containing validated navigation paths. Raises: FileNotFoundError: If the documentation root does not exist or a @@ -92,10 +108,12 @@ def resolve_nav( Resolve a glob pattern relative to the documentation root. Args: - pattern: Glob pattern used to match documentation files. + pattern (str): + Glob pattern used to match documentation files. Returns: - A sorted list of matching ``Path`` objects. + list[Path]: + A sorted list of matching `Path` objects. Raises: FileNotFoundError: If the pattern does not match any files. diff --git a/docforge/nav/spec.py b/docforge/nav/spec.py index bcbf8a8..8158350 100644 --- a/docforge/nav/spec.py +++ b/docforge/nav/spec.py @@ -4,8 +4,19 @@ Navigation specification model. This module defines the ``NavSpec`` class, which represents the navigation structure defined by the user in the doc-forge navigation specification (typically ``docforge.nav.yml``). + +--- + +Notes: + - The spec file supports an optional ``icon`` mapping for MkDocs theme + customization. + - All file references in ``groups`` are relative to the documentation root. + +--- """ +from __future__ import annotations + from pathlib import Path import yaml @@ -38,10 +49,13 @@ class NavSpec: Initialize a NavSpec instance. Args: - home: Relative path to the home document. - groups: Mapping of group names to lists of path patterns + home (str | None): + Relative path to the home document. + groups (dict[str, list[str]]): + Mapping of group names to lists of path patterns (glob expressions). - icon: Optional mapping of theme icon entries applied to the + icon (dict[str, str] | None): + Optional mapping of theme icon entries applied to the generated MkDocs configuration. """ self.home = home @@ -49,15 +63,17 @@ class NavSpec: self.icon = icon @classmethod - def load(cls, path: Path) -> "NavSpec": + def load(cls, path: Path) -> NavSpec: """ Load a navigation specification from a YAML file. Args: - path: Filesystem path to the navigation specification file. + path (Path): + Filesystem path to the navigation specification file. Returns: - A ``NavSpec`` instance representing the parsed configuration. + NavSpec: + A ``NavSpec`` instance representing the parsed configuration. Raises: FileNotFoundError: If the specified file does not exist. @@ -105,8 +121,9 @@ class NavSpec: Return all path patterns referenced by the specification. Returns: - A list containing the home document (if defined) and all - group pattern entries. + list[str]: + A list containing the home document (if defined) and all + group pattern entries. """ patterns: list[str] = [] @@ -127,10 +144,12 @@ def load_nav_spec(path: Path) -> NavSpec: corresponding ``NavSpec`` instance. Args: - path: Path to the navigation specification file. + path (Path): + Path to the navigation specification file. Returns: - A ``NavSpec`` instance representing the parsed specification. + NavSpec: + A ``NavSpec`` instance representing the parsed specification. Raises: FileNotFoundError: If the specification file does not exist. diff --git a/docforge/nav/wiki.py b/docforge/nav/wiki.py index ecde65a..0829d5c 100644 --- a/docforge/nav/wiki.py +++ b/docforge/nav/wiki.py @@ -20,6 +20,7 @@ modified by doc-forge; only the navigation layout is inferred. """ import re +from collections.abc import Callable from pathlib import Path from typing import Any @@ -46,7 +47,7 @@ def build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]: Path to the hand-written wiki directory, for example ``docs/wiki``. Returns: - List[Dict[str, Any]]: + list[dict[str, Any]]: Navigation entries compatible with the MkDocs ``nav`` configuration. The list is empty if the wiki contains no Markdown files. @@ -75,7 +76,10 @@ def build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]: return nav -def _render_entries(base_dir: Path, rel) -> list[dict[str, Any]]: +def _render_entries( + base_dir: Path, + rel: Callable[[Path], str], +) -> list[dict[str, Any]]: """ Render navigation entries for the children of a wiki directory. @@ -87,11 +91,11 @@ def _render_entries(base_dir: Path, rel) -> list[dict[str, Any]]: base_dir (Path): Directory whose children are rendered. - rel: + rel (Callable[[Path], str]): Callable converting a wiki file path into a docs-relative path. Returns: - List[Dict[str, Any]]: + list[dict[str, Any]]: Navigation entries for ``base_dir`` in natural sort order. """ children = sorted( @@ -152,7 +156,7 @@ def _natural_key(name: str) -> list[object]: Filename or directory name to key. Returns: - List[object]: + list[object]: Mixed list of lowercased strings and integers used for sorting. """ return [ diff --git a/docforge/nav/wiki.pyi b/docforge/nav/wiki.pyi index fe62725..a0d435c 100644 --- a/docforge/nav/wiki.pyi +++ b/docforge/nav/wiki.pyi @@ -1,3 +1,4 @@ +from collections.abc import Callable from pathlib import Path from typing import Any @@ -5,11 +6,36 @@ def build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]: """ Derive an MkDocs navigation block from a wiki directory. + Args: + wiki_dir (Path): + Path to the hand-written wiki directory. + Returns: - Wiki navigation entries compatible with the MkDocs - `nav` configuration. + list[dict[str, Any]]: + Wiki navigation entries compatible with the MkDocs `nav` + configuration. Raises: - FileNotFoundError: if the wiki directory does not exist + FileNotFoundError: + If the wiki directory does not exist. + """ + ... + +def _render_entries( + base_dir: Path, + rel: Callable[[Path], str], +) -> list[dict[str, Any]]: + """ + Render navigation entries for the children of a wiki directory. + + Args: + base_dir (Path): + Directory whose children are rendered. + rel (Callable[[Path], str]): + Callable converting a wiki file path into a docs-relative path. + + Returns: + list[dict[str, Any]]: + Navigation entries for `base_dir` in natural sort order. """ ... diff --git a/docforge/renderers/mcp_renderer.py b/docforge/renderers/mcp_renderer.py index 425d18c..2e3f97a 100644 --- a/docforge/renderers/mcp_renderer.py +++ b/docforge/renderers/mcp_renderer.py @@ -49,7 +49,7 @@ class MCPRenderer: nav.append( { "module": module.path, - "resource": f"doc://modules/{module.path}", + "resource": f"docs://modules/{module.path}", } ) @@ -101,7 +101,7 @@ class MCPRenderer: Module instance to convert. Returns: - Dict: + dict: Dictionary representing the module and its documented objects. """ data: dict = { @@ -124,7 +124,7 @@ class MCPRenderer: Documentation object to convert. Returns: - Dict: + dict: Dictionary describing the object and any nested members. """ data: dict = { @@ -149,7 +149,7 @@ class MCPRenderer: Serialize data to formatted JSON. Args: - data (Dict): + data (dict): Dictionary to serialize. Returns: diff --git a/docforge/renderers/mkdocs_renderer.py b/docforge/renderers/mkdocs_renderer.py index aaea47c..8880592 100644 --- a/docforge/renderers/mkdocs_renderer.py +++ b/docforge/renderers/mkdocs_renderer.py @@ -54,7 +54,7 @@ class MkDocsRenderer: out_dir (Path): Directory where generated Markdown files will be written. - module_is_source (bool, optional): + module_is_source (bool | None): If True, treat the specified module as the documentation root rather than nesting it inside a folder. """ @@ -87,11 +87,10 @@ class MkDocsRenderer: """ Generate a `README.md` file from the root module docstring. - Behavior: - - - If `module_is_source` is True, `README.md` is written to the project - root directory. - - If False, README generation is currently not implemented. + Notes: + - If `module_is_source` is True, `README.md` is written to the + project root directory. + - If False, README generation is currently not implemented. Args: project (Project): @@ -100,10 +99,10 @@ class MkDocsRenderer: docs_dir (Path): Directory containing generated documentation sources. - module_is_source (Optional[bool]): + module_is_source (bool | None): Whether the module is treated as the project source root. - readme_dir (Optional[Path]): + readme_dir (Path | None): Directory where the generated README.md should be written. Defaults to the parent of `docs_dir`. """ @@ -157,7 +156,7 @@ class MkDocsRenderer: Project model to inspect. Returns: - Optional[Module]: + Module | None: The root `Module` if found, otherwise `None`. """ for module in project.get_all_modules(): @@ -189,7 +188,7 @@ class MkDocsRenderer: out_dir (Path): Base directory for generated documentation files. - module_is_source (bool, optional): + module_is_source (bool | None): Whether the module acts as the documentation root directory. """ diff --git a/docforge/servers/mcp_server.py b/docforge/servers/mcp_server.py index 6b27541..1ee5688 100644 --- a/docforge/servers/mcp_server.py +++ b/docforge/servers/mcp_server.py @@ -5,6 +5,16 @@ MCP server implementation. This module defines the `MCPServer` class, which serves pre-generated documentation bundles through the Model Context Protocol (MCP). + +--- + +Notes: + - The served bundle is generated offline by `MCPRenderer`. + - Missing resources are reported as structured error dictionaries rather + than raising exceptions. + - The server exposes read-only resources and a single health-check tool. + +--- """ from __future__ import annotations @@ -22,6 +32,14 @@ class MCPServer: The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer. + + Attributes: + mcp_root (Path): + Directory containing the generated MCP documentation bundle. + + app (FastMCP): + Underlying FastMCP application instance that registers resources + and tools. """ def __init__(self, mcp_root: Path, name: str) -> None: diff --git a/docforge/servers/mcp_server.pyi b/docforge/servers/mcp_server.pyi index f469071..8b2308a 100644 --- a/docforge/servers/mcp_server.pyi +++ b/docforge/servers/mcp_server.pyi @@ -4,7 +4,10 @@ from typing import Any, Literal from mcp.server.fastmcp import FastMCP class MCPServer: - """MCP server for serving documentation.""" + """MCP server serving a pre-generated documentation bundle. + + Exposes read-only documentation resources and a health-check tool. + """ mcp_root: Path app: FastMCP 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/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/lib/docforge/nav/wiki.md b/docs/lib/nav/wiki.md similarity index 100% rename from docs/lib/docforge/nav/wiki.md rename to docs/lib/nav/wiki.md diff --git a/docs/mcp/index.json b/docs/mcp/index.json index 9055418..6ce9145 100644 --- a/docs/mcp/index.json +++ b/docs/mcp/index.json @@ -1,6 +1,6 @@ { "project": "docforge", "type": "docforge-model", - "modules_count": 23, + "modules_count": 24, "source": "docforge" } \ No newline at end of file diff --git a/docs/mcp/modules/docforge.cli.api_utils.json b/docs/mcp/modules/docforge.cli.api_utils.json index 547c81a..1fc4060 100644 --- a/docs/mcp/modules/docforge.cli.api_utils.json +++ b/docs/mcp/modules/docforge.cli.api_utils.json @@ -73,22 +73,22 @@ "name": "load_openapi_spec", "kind": "function", "path": "docforge.cli.api_utils.load_openapi_spec", - "signature": "", - "docstring": "Load and validate an OpenAPI specification from a JSON file.\n\nArgs:\n spec_path: Path to the OpenAPI JSON specification file.\n\nReturns:\n dict:\n The parsed OpenAPI specification.\n\nRaises:\n click.ClickException:\n If the file cannot be read or the ``info`` block is invalid." + "signature": "", + "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": "", - "docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec: Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec." + "signature": "", + "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": "", - "docstring": "Generate swagger-enabled Markdown sources and the spec copy.\n\nThe specification is written as ``openapi.json`` inside ``docs_dir`` and\nan ``index.md`` embedding the swagger UI is generated alongside it.\n\nArgs:\n spec: Parsed OpenAPI specification.\n docs_dir: Directory (for example ``docs/api``) where the swagger\n sources are written." + "signature": "", + "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", diff --git a/docs/mcp/modules/docforge.cli.commands.json b/docs/mcp/modules/docforge.cli.commands.json index 5397439..9dfa53e 100644 --- a/docs/mcp/modules/docforge.cli.commands.json +++ b/docs/mcp/modules/docforge.cli.commands.json @@ -2,7 +2,7 @@ "module": "docforge.cli.commands", "content": { "path": "docforge.cli.commands", - "docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.", + "docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.\n\n---\n\nNotes:\n - The `build` command validates requested modes before generating anything.\n - `--mkdocs`, `--api`, and `--wiki` share a single MkDocs build; `--mcp`\n generates a machine-readable bundle independently.\n\n---", "objects": { "Path": { "name": "Path", @@ -95,21 +95,21 @@ "kind": "function", "path": "docforge.cli.commands.api_utils.load_openapi_spec", "signature": "", - "docstring": "Load and validate an OpenAPI specification from a JSON file.\n\nArgs:\n spec_path: Path to the OpenAPI JSON specification file.\n\nReturns:\n dict:\n The parsed OpenAPI specification.\n\nRaises:\n click.ClickException:\n If the file cannot be read or the ``info`` block is invalid." + "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": "", - "docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec: Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec." + "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": "", - "docstring": "Generate swagger-enabled Markdown sources and the spec copy.\n\nThe specification is written as ``openapi.json`` inside ``docs_dir`` and\nan ``index.md`` embedding the swagger UI is generated alongside it.\n\nArgs:\n spec: Parsed OpenAPI specification.\n docs_dir: Directory (for example ``docs/api``) where the swagger\n sources are written." + "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", @@ -125,7 +125,7 @@ "kind": "module", "path": "docforge.cli.commands.mcp_utils", "signature": "", - "docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.", + "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", @@ -146,21 +146,21 @@ "kind": "class", "path": "docforge.cli.commands.mcp_utils.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -169,7 +169,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.discover_module_paths", "signature": "", - "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, optional):\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." + "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", @@ -199,7 +199,7 @@ "kind": "class", "path": "docforge.cli.commands.mcp_utils.MCPServer", "signature": "", - "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.", + "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", @@ -229,7 +229,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.generate_resources", "signature": "", - "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 (Optional[str]):\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." + "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", @@ -245,7 +245,7 @@ "kind": "module", "path": "docforge.cli.commands.mkdocs_utils", "signature": "", - "docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.", + "docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A single generated `mkdocs.yml` serves lib, api, and wiki content with\n merged navigation. Wiki navigation, when enabled, precedes every other\n group and its `index.md` becomes the site `Home`.\n\n---", "members": { "os": { "name": "os", @@ -294,21 +294,21 @@ "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -317,7 +317,7 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths", "signature": "", - "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, optional):\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." + "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", @@ -331,23 +331,30 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit", "signature": "", - "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\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." + "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav (ResolvedNav):\n Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n list[dict[str, Any]]:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." } } }, + "build_wiki_nav": { + "name": "build_wiki_nav", + "kind": "function", + "path": "docforge.cli.commands.mkdocs_utils.build_wiki_nav", + "signature": "", + "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": "", - "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 to the navigation specification file.\n\nReturns:\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." + "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": "", - "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: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\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." + "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", @@ -368,14 +375,14 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "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, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." + "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": "", - "docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n 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 (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`." + "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`." } } }, @@ -384,14 +391,14 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_sources", "signature": "", - "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 (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``." + "docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_config", "signature": "", - "docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Optional[Path]):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Optional[Iterable[str]]):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib`` or ``api``),\n merged on top of the shared ``mkdocs.common.yml`` template.\n\n site_description (Optional[str]):\n Optional site description written into the configuration.\n\n site_author (Optional[str]):\n Optional site author written into the configuration.\n\nRaises:\n click.FileError:\n If the navigation specification or template file cannot be found." + "docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification (and, when a wiki directory is provided, from the wiki\nfile structure).\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories\nand hand-written wiki content under a ``wiki/`` subdirectory.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Iterable[str] | None):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib``, ``api``, or\n ``wiki``), merged on top of the shared ``mkdocs.common.yml``\n template.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n wiki_dir (Path | None):\n Optional path to a hand-written wiki directory (for example\n ``docs/wiki``). When provided, the site navigation is derived\n from the wiki file structure and placed before the navigation\n groups defined in ``nav_file``.\n\nRaises:\n click.FileError:\n If the navigation specification, template, or wiki directory\n cannot be found." }, "build": { "name": "build", @@ -414,21 +421,93 @@ "kind": "class", "path": "docforge.cli.commands.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance.\n\nRaises:\n ImportError:\n If the module cannot be loaded by Griffe.\n\n KeyError:\n If the loaded module is missing from the module collection.\n\nExample:\n Load a single module:\n\n ```python\n loader = GriffeLoader()\n module = loader.load_module(\"mypackage.submodule\")\n ```" + } + } + }, + "DocObject": { + "name": "DocObject", + "kind": "class", + "path": "docforge.cli.commands.DocObject", + "signature": "", + "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": "", + "docstring": null + }, + "kind": { + "name": "kind", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.kind", + "signature": "", + "docstring": null + }, + "path": { + "name": "path", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.path", + "signature": "", + "docstring": null + }, + "signature": { + "name": "signature", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.signature", + "signature": "", + "docstring": null + }, + "docstring": { + "name": "docstring", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.docstring", + "signature": "", + "docstring": null + }, + "members": { + "name": "members", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.members", + "signature": "", + "docstring": null + }, + "add_member": { + "name": "add_member", + "kind": "function", + "path": "docforge.cli.commands.DocObject.add_member", + "signature": "", + "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": "", + "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": "", + "docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." } } }, @@ -443,29 +522,22 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", - "docstring": "Build documentation artifacts.\n\nThis command performs the full documentation build pipeline:\nstyle of the selected platform, generates renderer-specific\ndocumentation sources, and optionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites for library reference docs\n- Swagger-enabled API docs generated from an OpenAPI spec\n- MCP structured documentation resources\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs library documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (Optional[str]):\n Python module import path to document.\n\n openapi_spec (Optional[Path]):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (Optional[str]):\n Optional override for the project name.\n\n site_name (Optional[str]):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Optional[Path]):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." + "signature": "", + "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds or serves the final output.\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites for library reference docs\n- Swagger-enabled API docs generated from an OpenAPI spec\n- Hand-written wiki pages included in the MkDocs site\n- MCP structured documentation resources\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` are combined into a single MkDocs\n build, while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs library documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Include a hand-written wiki directory in the MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.serve", - "signature": "", - "docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (Optional[str]):\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." + "signature": "", + "docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided." }, "tree": { "name": "tree", "kind": "function", "path": "docforge.cli.commands.tree", - "signature": "", - "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 (Optional[str]):\n Optional name to display as the project root." - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.commands.Any", - "signature": "", - "docstring": null + "signature": "", + "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", diff --git a/docs/mcp/modules/docforge.cli.json b/docs/mcp/modules/docforge.cli.json index 536047d..92d61f5 100644 --- a/docs/mcp/modules/docforge.cli.json +++ b/docs/mcp/modules/docforge.cli.json @@ -103,22 +103,22 @@ "name": "load_openapi_spec", "kind": "function", "path": "docforge.cli.api_utils.load_openapi_spec", - "signature": "", - "docstring": "Load and validate an OpenAPI specification from a JSON file.\n\nArgs:\n spec_path: Path to the OpenAPI JSON specification file.\n\nReturns:\n dict:\n The parsed OpenAPI specification.\n\nRaises:\n click.ClickException:\n If the file cannot be read or the ``info`` block is invalid." + "signature": "", + "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": "", - "docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec: Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec." + "signature": "", + "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": "", - "docstring": "Generate swagger-enabled Markdown sources and the spec copy.\n\nThe specification is written as ``openapi.json`` inside ``docs_dir`` and\nan ``index.md`` embedding the swagger UI is generated alongside it.\n\nArgs:\n spec: Parsed OpenAPI specification.\n docs_dir: Directory (for example ``docs/api``) where the swagger\n sources are written." + "signature": "", + "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", @@ -134,7 +134,7 @@ "kind": "module", "path": "docforge.cli.commands", "signature": null, - "docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.", + "docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.\n\n---\n\nNotes:\n - The `build` command validates requested modes before generating anything.\n - `--mkdocs`, `--api`, and `--wiki` share a single MkDocs build; `--mcp`\n generates a machine-readable bundle independently.\n\n---", "members": { "Path": { "name": "Path", @@ -227,21 +227,21 @@ "kind": "function", "path": "docforge.cli.commands.api_utils.load_openapi_spec", "signature": "", - "docstring": "Load and validate an OpenAPI specification from a JSON file.\n\nArgs:\n spec_path: Path to the OpenAPI JSON specification file.\n\nReturns:\n dict:\n The parsed OpenAPI specification.\n\nRaises:\n click.ClickException:\n If the file cannot be read or the ``info`` block is invalid." + "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": "", - "docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec: Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec." + "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": "", - "docstring": "Generate swagger-enabled Markdown sources and the spec copy.\n\nThe specification is written as ``openapi.json`` inside ``docs_dir`` and\nan ``index.md`` embedding the swagger UI is generated alongside it.\n\nArgs:\n spec: Parsed OpenAPI specification.\n docs_dir: Directory (for example ``docs/api``) where the swagger\n sources are written." + "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", @@ -257,7 +257,7 @@ "kind": "module", "path": "docforge.cli.commands.mcp_utils", "signature": "", - "docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.", + "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", @@ -278,21 +278,21 @@ "kind": "class", "path": "docforge.cli.commands.mcp_utils.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -301,7 +301,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.discover_module_paths", "signature": "", - "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, optional):\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." + "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", @@ -331,7 +331,7 @@ "kind": "class", "path": "docforge.cli.commands.mcp_utils.MCPServer", "signature": "", - "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.", + "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", @@ -361,7 +361,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.generate_resources", "signature": "", - "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 (Optional[str]):\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." + "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", @@ -377,7 +377,7 @@ "kind": "module", "path": "docforge.cli.commands.mkdocs_utils", "signature": "", - "docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.", + "docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A single generated `mkdocs.yml` serves lib, api, and wiki content with\n merged navigation. Wiki navigation, when enabled, precedes every other\n group and its `index.md` becomes the site `Home`.\n\n---", "members": { "os": { "name": "os", @@ -426,21 +426,21 @@ "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -449,7 +449,7 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths", "signature": "", - "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, optional):\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." + "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", @@ -463,23 +463,30 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit", "signature": "", - "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\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." + "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav (ResolvedNav):\n Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n list[dict[str, Any]]:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." } } }, + "build_wiki_nav": { + "name": "build_wiki_nav", + "kind": "function", + "path": "docforge.cli.commands.mkdocs_utils.build_wiki_nav", + "signature": "", + "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": "", - "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 to the navigation specification file.\n\nReturns:\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." + "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": "", - "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: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\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." + "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", @@ -500,14 +507,14 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "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, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." + "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": "", - "docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n 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 (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`." + "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`." } } }, @@ -516,14 +523,14 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_sources", "signature": "", - "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 (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``." + "docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_config", "signature": "", - "docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Optional[Path]):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Optional[Iterable[str]]):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib`` or ``api``),\n merged on top of the shared ``mkdocs.common.yml`` template.\n\n site_description (Optional[str]):\n Optional site description written into the configuration.\n\n site_author (Optional[str]):\n Optional site author written into the configuration.\n\nRaises:\n click.FileError:\n If the navigation specification or template file cannot be found." + "docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification (and, when a wiki directory is provided, from the wiki\nfile structure).\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories\nand hand-written wiki content under a ``wiki/`` subdirectory.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Iterable[str] | None):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib``, ``api``, or\n ``wiki``), merged on top of the shared ``mkdocs.common.yml``\n template.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n wiki_dir (Path | None):\n Optional path to a hand-written wiki directory (for example\n ``docs/wiki``). When provided, the site navigation is derived\n from the wiki file structure and placed before the navigation\n groups defined in ``nav_file``.\n\nRaises:\n click.FileError:\n If the navigation specification, template, or wiki directory\n cannot be found." }, "build": { "name": "build", @@ -546,21 +553,93 @@ "kind": "class", "path": "docforge.cli.commands.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance.\n\nRaises:\n ImportError:\n If the module cannot be loaded by Griffe.\n\n KeyError:\n If the loaded module is missing from the module collection.\n\nExample:\n Load a single module:\n\n ```python\n loader = GriffeLoader()\n module = loader.load_module(\"mypackage.submodule\")\n ```" + } + } + }, + "DocObject": { + "name": "DocObject", + "kind": "class", + "path": "docforge.cli.commands.DocObject", + "signature": "", + "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": "", + "docstring": null + }, + "kind": { + "name": "kind", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.kind", + "signature": "", + "docstring": null + }, + "path": { + "name": "path", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.path", + "signature": "", + "docstring": null + }, + "signature": { + "name": "signature", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.signature", + "signature": "", + "docstring": null + }, + "docstring": { + "name": "docstring", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.docstring", + "signature": "", + "docstring": null + }, + "members": { + "name": "members", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.members", + "signature": "", + "docstring": null + }, + "add_member": { + "name": "add_member", + "kind": "function", + "path": "docforge.cli.commands.DocObject.add_member", + "signature": "", + "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": "", + "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": "", + "docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." } } }, @@ -575,29 +654,22 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", - "docstring": "Build documentation artifacts.\n\nThis command performs the full documentation build pipeline:\nstyle of the selected platform, generates renderer-specific\ndocumentation sources, and optionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites for library reference docs\n- Swagger-enabled API docs generated from an OpenAPI spec\n- MCP structured documentation resources\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs library documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (Optional[str]):\n Python module import path to document.\n\n openapi_spec (Optional[Path]):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (Optional[str]):\n Optional override for the project name.\n\n site_name (Optional[str]):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Optional[Path]):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." + "signature": "", + "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds or serves the final output.\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites for library reference docs\n- Swagger-enabled API docs generated from an OpenAPI spec\n- Hand-written wiki pages included in the MkDocs site\n- MCP structured documentation resources\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` are combined into a single MkDocs\n build, while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs library documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Include a hand-written wiki directory in the MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.serve", - "signature": "", - "docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (Optional[str]):\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." + "signature": "", + "docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided." }, "tree": { "name": "tree", "kind": "function", "path": "docforge.cli.commands.tree", - "signature": "", - "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 (Optional[str]):\n Optional name to display as the project root." - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.commands.Any", - "signature": "", - "docstring": null + "signature": "", + "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", @@ -613,7 +685,7 @@ "kind": "module", "path": "docforge.cli.mcp_utils", "signature": null, - "docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.", + "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", @@ -634,21 +706,21 @@ "kind": "class", "path": "docforge.cli.mcp_utils.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -657,7 +729,7 @@ "kind": "function", "path": "docforge.cli.mcp_utils.discover_module_paths", "signature": "", - "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, optional):\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." + "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", @@ -687,7 +759,7 @@ "kind": "class", "path": "docforge.cli.mcp_utils.MCPServer", "signature": "", - "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.", + "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", @@ -716,14 +788,14 @@ "name": "generate_resources", "kind": "function", "path": "docforge.cli.mcp_utils.generate_resources", - "signature": "", - "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 (Optional[str]):\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." + "signature": "", + "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": "", "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." } } @@ -733,7 +805,7 @@ "kind": "module", "path": "docforge.cli.mkdocs_utils", "signature": null, - "docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.", + "docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A single generated `mkdocs.yml` serves lib, api, and wiki content with\n merged navigation. Wiki navigation, when enabled, precedes every other\n group and its `index.md` becomes the site `Home`.\n\n---", "members": { "os": { "name": "os", @@ -782,21 +854,21 @@ "kind": "class", "path": "docforge.cli.mkdocs_utils.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -805,7 +877,7 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.discover_module_paths", "signature": "", - "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, optional):\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." + "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", @@ -819,23 +891,30 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit", "signature": "", - "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\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." + "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav (ResolvedNav):\n Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n list[dict[str, Any]]:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." } } }, + "build_wiki_nav": { + "name": "build_wiki_nav", + "kind": "function", + "path": "docforge.cli.mkdocs_utils.build_wiki_nav", + "signature": "", + "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": "", - "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 to the navigation specification file.\n\nReturns:\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." + "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": "", - "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: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\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." + "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", @@ -856,14 +935,14 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "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, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." + "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": "", - "docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n 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 (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`." + "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`." } } }, @@ -871,28 +950,28 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_sources", - "signature": "", - "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 (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``." + "signature": "", + "docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_config", - "signature": "", - "docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Optional[Path]):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Optional[Iterable[str]]):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib`` or ``api``),\n merged on top of the shared ``mkdocs.common.yml`` template.\n\n site_description (Optional[str]):\n Optional site description written into the configuration.\n\n site_author (Optional[str]):\n Optional site author written into the configuration.\n\nRaises:\n click.FileError:\n If the navigation specification or template file cannot be found." + "signature": "", + "docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification (and, when a wiki directory is provided, from the wiki\nfile structure).\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories\nand hand-written wiki content under a ``wiki/`` subdirectory.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Iterable[str] | None):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib``, ``api``, or\n ``wiki``), merged on top of the shared ``mkdocs.common.yml``\n template.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n wiki_dir (Path | None):\n Optional path to a hand-written wiki directory (for example\n ``docs/wiki``). When provided, the site navigation is derived\n from the wiki file structure and placed before the navigation\n groups defined in ``nav_file``.\n\nRaises:\n click.FileError:\n If the navigation specification, template, or wiki directory\n cannot be found." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.mkdocs_utils.build", - "signature": "", + "signature": "", "docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.mkdocs_utils.serve", - "signature": "", + "signature": "", "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.mcp_utils.json b/docs/mcp/modules/docforge.cli.mcp_utils.json index 107ed3f..cb43910 100644 --- a/docs/mcp/modules/docforge.cli.mcp_utils.json +++ b/docs/mcp/modules/docforge.cli.mcp_utils.json @@ -2,7 +2,7 @@ "module": "docforge.cli.mcp_utils", "content": { "path": "docforge.cli.mcp_utils", - "docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.", + "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", @@ -23,21 +23,21 @@ "kind": "class", "path": "docforge.cli.mcp_utils.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -46,7 +46,7 @@ "kind": "function", "path": "docforge.cli.mcp_utils.discover_module_paths", "signature": "", - "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, optional):\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." + "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", @@ -76,7 +76,7 @@ "kind": "class", "path": "docforge.cli.mcp_utils.MCPServer", "signature": "", - "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.", + "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", @@ -105,14 +105,14 @@ "name": "generate_resources", "kind": "function", "path": "docforge.cli.mcp_utils.generate_resources", - "signature": "", - "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 (Optional[str]):\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." + "signature": "", + "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": "", "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 6a260f5..2ab6539 100644 --- a/docs/mcp/modules/docforge.cli.mkdocs_utils.json +++ b/docs/mcp/modules/docforge.cli.mkdocs_utils.json @@ -2,7 +2,7 @@ "module": "docforge.cli.mkdocs_utils", "content": { "path": "docforge.cli.mkdocs_utils", - "docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.", + "docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A single generated `mkdocs.yml` serves lib, api, and wiki content with\n merged navigation. Wiki navigation, when enabled, precedes every other\n group and its `index.md` becomes the site `Home`.\n\n---", "objects": { "os": { "name": "os", @@ -51,21 +51,21 @@ "kind": "class", "path": "docforge.cli.mkdocs_utils.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -74,7 +74,7 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.discover_module_paths", "signature": "", - "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, optional):\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." + "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", @@ -88,23 +88,30 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit", "signature": "", - "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\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." + "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav (ResolvedNav):\n Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n list[dict[str, Any]]:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." } } }, + "build_wiki_nav": { + "name": "build_wiki_nav", + "kind": "function", + "path": "docforge.cli.mkdocs_utils.build_wiki_nav", + "signature": "", + "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": "", - "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 to the navigation specification file.\n\nReturns:\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." + "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": "", - "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: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\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." + "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", @@ -125,14 +132,14 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "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, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." + "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": "", - "docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n 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 (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`." + "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`." } } }, @@ -140,28 +147,28 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_sources", - "signature": "", - "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 (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``." + "signature": "", + "docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_config", - "signature": "", - "docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Optional[Path]):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Optional[Iterable[str]]):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib`` or ``api``),\n merged on top of the shared ``mkdocs.common.yml`` template.\n\n site_description (Optional[str]):\n Optional site description written into the configuration.\n\n site_author (Optional[str]):\n Optional site author written into the configuration.\n\nRaises:\n click.FileError:\n If the navigation specification or template file cannot be found." + "signature": "", + "docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification (and, when a wiki directory is provided, from the wiki\nfile structure).\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories\nand hand-written wiki content under a ``wiki/`` subdirectory.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Iterable[str] | None):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib``, ``api``, or\n ``wiki``), merged on top of the shared ``mkdocs.common.yml``\n template.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n wiki_dir (Path | None):\n Optional path to a hand-written wiki directory (for example\n ``docs/wiki``). When provided, the site navigation is derived\n from the wiki file structure and placed before the navigation\n groups defined in ``nav_file``.\n\nRaises:\n click.FileError:\n If the navigation specification, template, or wiki directory\n cannot be found." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.mkdocs_utils.build", - "signature": "", + "signature": "", "docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.mkdocs_utils.serve", - "signature": "", + "signature": "", "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 ae0cb51..6cabd48 100644 --- a/docs/mcp/modules/docforge.json +++ b/docs/mcp/modules/docforge.json @@ -2,28 +2,28 @@ "module": "docforge", "content": { "path": "docforge", - "docstring": "# Summary\n\nRenderer-agnostic Python documentation compiler that converts Python docstrings\ninto structured documentation for both humans (MkDocs) and machines (MCP / AI agents).\n\n`doc-forge` statically analyzes source code, builds a semantic model of modules,\nclasses, functions, and attributes, and renders that model into documentation\noutputs without executing user code.\n\n---\n\n# Installation\n\nInstall using pip:\n\n```bash\npip install doc-forge\n```\n\n---\n\n# CLI usage\n\n## Generate an MkDocs site from a Python package:\n\n```bash\ndoc-forge build --mkdocs --module my_package\n```\n\n## Generate MCP JSON documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\n\n## Generate MkDocs site and MCP JSON documentation:\n\n```bash\ndoc-forge build --mcp --mkdocs --module my_package\n```\n\n## Serve MkDocs locally:\n\n```bash\ndoc-forge serve --mkdocs --module my_package\n```\n\n## Serve MCP locally:\n\n```bash\ndoc-forge serve --mcp --module my_package\n```\n\n---\n\n# Core concepts\n\n## Loader\nExtracts symbols, signatures, and docstrings using static analysis.\n\n## Semantic model\nStructured, renderer-agnostic representation of the API.\n\n## Renderer\nConverts the semantic model into output formats such as MkDocs or MCP JSON.\n\n## Symbol\nAny documentable object\n\n- module\n- class\n- function\n- method\n- property\n- attribute\n\n---\n\n# Architecture\n\n`doc-forge` follows a compiler architecture:\n\n## Front-end:\n\nStatic analysis of modules, classes, functions, type hints, and docstrings.\n\n## Middle-end:\n\nBuilds a semantic model describing symbols and relationships.\n\n## Back-end:\n\nRenders documentation using interchangeable renderers.\n\nThis architecture ensures deterministic documentation generation.\n\n---\n\n# Rendering pipeline\n\nTypical flow:\n\n Python package\n |\n Loader (static analysis)\n |\n Semantic model\n |\n Renderer\n |\n MkDocs site or MCP JSON\n\n---\n\n# Google-Styled Doc-Forge Convention (GSDFC)\n\nGSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.\n\n- Docstrings are the single source of truth.\n- `doc-forge` compiles docstrings but does not generate documentation content.\n- Documentation follows the Python import hierarchy.\n- Every public symbol should have a complete and accurate docstring.\n\n---\n\n## General rules\n\n- Use **Markdown headings** at package and module level.\n- Use **Google-style structured sections** at class, function, and method level.\n- Use type hints in signatures instead of duplicating types in prose.\n- Write summaries in imperative form.\n- Sections are separated by `---`\n\n---\n\n# Notes subsection grouping\n\nGroup related information using labeled subsections.\n\nExample:\n\n Notes:\n **Guarantees:**\n\n - deterministic behavior\n\n **Lifecycle:**\n\n - created during initialization\n - reused across executions\n\n **Thread safety:**\n\n - safe for concurrent reads\n\n---\n\n# Example formatting\n\n- Use indentation for examples.\n- Indent section contents using four spaces.\n- Use code blocks for example code.\n\nExample:\n Single example:\n\n Example:\n\n ```python\n foo = Foo(\"example\")\n process(foo, multiplier=2)\n ```\n\n Multiple examples:\n\n Example:\n Create foo:\n\n ```python\n foo = Foo(\"example\")\n ```\n\n Run engine:\n\n ```python\n engine = BarEngine([foo])\n engine.run()\n ```\n\nAvoid fenced code blocks inside structured sections.\n\n---\n\n# Separator rules\n\nUse horizontal separators only at docstring root level to separate sections:\n\n```markdown\n---\n```\n\nAllowed locations:\n\n- package docstrings\n- module docstrings\n- major documentation sections\n\nDo not use separators inside code sections.\n\n---\n\n# Package docstrings\n\nPackage docstrings act as the documentation home page.\n\nRecommended sections:\n\n # Summary\n # Installation\n # Quick start\n # CLI usage\n # Core concepts\n # Architecture\n # Rendering pipeline\n # Examples\n # Notes\n\nExample:\n Package Doc String:\n\n '''\n # Summary\n\n Foo-bar processing framework.\n\n Provides tools for defining Foo objects and executing Bar pipelines.\n\n ---\n\n # Installation\n\n ```bash\n pip install foo-bar\n ```\n\n ---\n\n # Quick start\n\n ```python\n from foobar import Foo, BarEngine\n\n foo = Foo(\"example\")\n engine = BarEngine([foo])\n\n result = engine.run()\n ```\n\n ---\n '''\n\n---\n\n# Module docstrings\n\nModule docstrings describe a subsystem.\n\nRecommended sections:\n\n # Summary\n # Examples\n # Notes\n\nExample:\n Module Doc String:\n\n '''\n # Summary\n\n Foo execution subsystem.\n\n Provides utilities for executing Foo objects through Bar stages.\n\n ---\n\n Example:\n\n ```python\n from foobar.engine import BarEngine\n from foobar.foo import Foo\n\n foo = Foo(\"example\")\n\n engine = BarEngine([foo])\n engine.run()\n ```\n\n ---\n '''\n\n---\n\n# Class docstrings\n\nClass docstrings define object responsibility, lifecycle, and attributes.\n\nRecommended sections:\n\n Attributes:\n Notes:\n Example:\n Raises:\n\nExample:\n Simple Foo:\n\n ```python\n class Foo:\n '''\n Represents a unit of work.\n\n Attributes:\n name (str):\n Identifier of the foo instance.\n\n value (int):\n Numeric value associated with foo.\n\n Notes:\n Guarantees:\n\n - instances are immutable after creation\n\n Lifecycle:\n\n - create instance\n - pass to processing engine\n\n Example:\n Create and inspect a Foo:\n\n ```python\n foo = Foo(\"example\", value=42)\n print(foo.name)\n ```\n '''\n ```\n\n Complex Bar:\n\n ```python\n class BarEngine:\n '''\n Executes Foo objects through Bar stages.\n\n Attributes:\n foos (tuple[Foo, ...]):\n Foo instances managed by the engine.\n\n Notes:\n Guarantees:\n\n - deterministic execution order\n\n Example:\n Run engine:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n ```\n\n---\n\n# Function and method docstrings\n\nFunction docstrings define API contracts.\n\nRecommended sections:\n\n Args:\n Returns:\n Raises:\n Yields:\n Notes:\n Example:\n\nExample:\n Simple process method:\n\n ```python\n def process(foo: Foo, multiplier: int) -> int:\n '''\n Process a Foo instance.\n\n Args:\n foo (Foo):\n Foo instance to process.\n\n multiplier (int):\n Value used to scale foo.\n\n Returns:\n int:\n Processed result.\n\n Raises:\n ValueError:\n If multiplier is negative.\n\n Notes:\n Guarantees:\n\n - foo is not modified\n\n Example:\n Process foo:\n\n ```python\n foo = Foo(\"example\", value=10)\n\n result = process(foo, multiplier=2)\n print(result)\n ```\n '''\n ```\n\n Multiple Examples:\n\n ```python\n def combine(foo_a: Foo, foo_b: Foo) -> Foo:\n '''\n Combine two Foo instances.\n\n Args:\n foo_a (Foo):\n First foo.\n\n foo_b (Foo):\n Second foo.\n\n Returns:\n Foo:\n Combined foo.\n\n Example:\n Basic usage:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n combined = combine(foo1, foo2)\n ```\n\n Pipeline usage:\n\n ```python\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n ```\n\n---\n\n# Property docstrings\n\nProperties must document return values.\n\nExample:\n Property Doc String:\n\n ```python\n @property\n def foos(self) -> tuple[Foo, ...]:\n '''\n Return contained Foo instances.\n\n Returns:\n tuple[Foo, ...]:\n Stored foo objects.\n\n Example:\n ```python\n container = FooContainer()\n\n foos = container.foos\n ```\n '''\n ```\n\n---\n\n# Attribute documentation\n\nDocument attributes in class docstrings using `Attributes:`.\n\nExample:\n Attribute Doc String:\n\n ```python\n '''\n Represents a processing stage.\n\n Attributes:\n id (str):\n Unique identifier.\n\n enabled (bool):\n Whether the stage is active.\n '''\n ```\n\n---\n\n# Parsing guarantees\n\nGSDFC ensures doc-forge can deterministically extract:\n\n- symbol kind (module, class, function, property, attribute)\n- symbol name\n- parameters\n- return values\n- attributes\n- examples\n- structured Notes subsections\n\nThis enables:\n\n- reliable MkDocs rendering\n- deterministic MCP export\n- accurate AI semantic interpretation\n\n---\n\nNotes:\n - doc-forge never executes analyzed modules.\n - Documentation is generated entirely through static analysis.", + "docstring": "# Summary\n\nRenderer-agnostic Python documentation compiler that converts Python docstrings\ninto structured documentation for both humans (MkDocs) and machines (MCP / AI agents).\n\n`doc-forge` statically analyzes source code, builds a semantic model of modules,\nclasses, functions, and attributes, and renders that model into documentation\noutputs without executing user code.\n\n---\n\n# Installation\n\nInstall using pip:\n\n```bash\npip install doc-forge\n```\n\n---\n\n# CLI usage\n\n## Generate an MkDocs site from a Python package:\n\n```bash\ndoc-forge build --mkdocs --module my_package\n```\n\n## Generate MCP JSON documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\n\n## Generate MkDocs site and MCP JSON documentation:\n\n```bash\ndoc-forge build --mcp --mkdocs --module my_package\n```\n\n## Include a hand-written wiki in the MkDocs site:\n\n```bash\ndoc-forge build --wiki --mkdocs --module my_package\n```\n\n## Build wiki pages only (no module required):\n\n```bash\ndoc-forge build --wiki --site-name my_package\n```\n\n## Serve MkDocs locally:\n\n```bash\ndoc-forge serve --mkdocs --module my_package\n```\n\n## Serve MCP locally:\n\n```bash\ndoc-forge serve --mcp --module my_package\n```\n\n---\n\n# Core concepts\n\n## Loader\nExtracts symbols, signatures, and docstrings using static analysis.\n\n## Semantic model\nStructured, renderer-agnostic representation of the API.\n\n## Renderer\nConverts the semantic model into output formats such as MkDocs or MCP JSON.\n\n## Symbol\nAny documentable object\n\n- module\n- class\n- function\n- method\n- property\n- attribute\n\n---\n\n# Architecture\n\n`doc-forge` follows a compiler architecture:\n\n## Front-end:\n\nStatic analysis of modules, classes, functions, type hints, and docstrings.\n\n## Middle-end:\n\nBuilds a semantic model describing symbols and relationships.\n\n## Back-end:\n\nRenders documentation using interchangeable renderers.\n\nThis architecture ensures deterministic documentation generation.\n\n---\n\n# Rendering pipeline\n\nTypical flow:\n\n Python package\n |\n Loader (static analysis)\n |\n Semantic model\n |\n Renderer\n |\n MkDocs site or MCP JSON\n\n---\n\n# Google-Styled Doc-Forge Convention (GSDFC)\n\nGSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.\n\n- Docstrings are the single source of truth.\n- `doc-forge` compiles docstrings but does not generate documentation content.\n- Documentation follows the Python import hierarchy.\n- Every public symbol should have a complete and accurate docstring.\n\n---\n\n## General rules\n\n- Use **Markdown headings** at package and module level.\n- Use **Google-style structured sections** at class, function, and method level.\n- Use type hints in signatures.\n- Use parenthesized types in prose entries (`name (Type):`) that match the\n signature types. This keeps docstrings self-contained and machine-parseable.\n- Write summaries in imperative form.\n- Sections are separated by `---`\n\n---\n\n# Notes subsection grouping\n\nGroup related information using labeled subsections.\n\nExample:\n\n Notes:\n **Guarantees:**\n\n - deterministic behavior\n\n **Lifecycle:**\n\n - created during initialization\n - reused across executions\n\n **Thread safety:**\n\n - safe for concurrent reads\n\n---\n\n# Example formatting\n\n- Use indentation for examples.\n- Indent section contents using four spaces.\n- Use code blocks for example code.\n\nExample:\n Single example:\n\n Example:\n\n ```python\n foo = Foo(\"example\")\n process(foo, multiplier=2)\n ```\n\n Multiple examples:\n\n Example:\n Create foo:\n\n ```python\n foo = Foo(\"example\")\n ```\n\n Run engine:\n\n ```python\n engine = BarEngine([foo])\n engine.run()\n ```\n\nAvoid fenced code blocks inside argument descriptions and other prose lines.\n\nInside `Example:` sections, fenced `python` code blocks are allowed and must be\nindented four spaces, matching the examples below.\n\n---\n\n# Separator rules\n\nUse horizontal separators only at docstring root level to separate sections:\n\n```markdown\n---\n```\n\nAllowed locations:\n\n- package docstrings\n- module docstrings\n- major documentation sections\n\nDo not use separators inside code sections.\n\n---\n\n# Package docstrings\n\nPackage docstrings act as the documentation home page.\n\nRecommended sections:\n\n # Summary\n # Installation\n # Quick start\n # CLI usage\n # Core concepts\n # Architecture\n # Rendering pipeline\n # Examples\n # Notes\n\nExample:\n Package Doc String:\n\n '''\n # Summary\n\n Foo-bar processing framework.\n\n Provides tools for defining Foo objects and executing Bar pipelines.\n\n ---\n\n # Installation\n\n ```bash\n pip install foo-bar\n ```\n\n ---\n\n # Quick start\n\n ```python\n from foobar import Foo, BarEngine\n\n foo = Foo(\"example\")\n engine = BarEngine([foo])\n\n result = engine.run()\n ```\n\n ---\n '''\n\n---\n\n# Module docstrings\n\nModule docstrings describe a subsystem.\n\nRecommended sections:\n\n # Summary\n # Examples\n # Notes\n\nExample:\n Module Doc String:\n\n '''\n # Summary\n\n Foo execution subsystem.\n\n Provides utilities for executing Foo objects through Bar stages.\n\n ---\n\n Example:\n\n ```python\n from foobar.engine import BarEngine\n from foobar.foo import Foo\n\n foo = Foo(\"example\")\n\n engine = BarEngine([foo])\n engine.run()\n ```\n\n ---\n '''\n\n---\n\n# Class docstrings\n\nClass docstrings define object responsibility, lifecycle, and attributes.\n\nRecommended sections:\n\n Attributes:\n Notes:\n Example:\n Raises:\n\nExample:\n Simple Foo:\n\n ```python\n class Foo:\n '''\n Represents a unit of work.\n\n Attributes:\n name (str):\n Identifier of the foo instance.\n\n value (int):\n Numeric value associated with foo.\n\n Notes:\n Guarantees:\n\n - instances are immutable after creation\n\n Lifecycle:\n\n - create instance\n - pass to processing engine\n\n Example:\n Create and inspect a Foo:\n\n ```python\n foo = Foo(\"example\", value=42)\n print(foo.name)\n ```\n '''\n ```\n\n Complex Bar:\n\n ```python\n class BarEngine:\n '''\n Executes Foo objects through Bar stages.\n\n Attributes:\n foos (tuple[Foo, ...]):\n Foo instances managed by the engine.\n\n Notes:\n Guarantees:\n\n - deterministic execution order\n\n Example:\n Run engine:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n ```\n\n---\n\n# Function and method docstrings\n\nFunction docstrings define API contracts.\n\nRecommended sections:\n\n Args:\n Returns:\n Raises:\n Yields:\n Notes:\n Example:\n\nExample:\n Simple process method:\n\n ```python\n def process(foo: Foo, multiplier: int) -> int:\n '''\n Process a Foo instance.\n\n Args:\n foo (Foo):\n Foo instance to process.\n\n multiplier (int):\n Value used to scale foo.\n\n Returns:\n int:\n Processed result.\n\n Raises:\n ValueError:\n If multiplier is negative.\n\n Notes:\n Guarantees:\n\n - foo is not modified\n\n Example:\n Process foo:\n\n ```python\n foo = Foo(\"example\", value=10)\n\n result = process(foo, multiplier=2)\n print(result)\n ```\n '''\n ```\n\n Multiple Examples:\n\n ```python\n def combine(foo_a: Foo, foo_b: Foo) -> Foo:\n '''\n Combine two Foo instances.\n\n Args:\n foo_a (Foo):\n First foo.\n\n foo_b (Foo):\n Second foo.\n\n Returns:\n Foo:\n Combined foo.\n\n Example:\n Basic usage:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n combined = combine(foo1, foo2)\n ```\n\n Pipeline usage:\n\n ```python\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n ```\n\n---\n\n# Property docstrings\n\nProperties must document return values.\n\nExample:\n Property Doc String:\n\n ```python\n @property\n def foos(self) -> tuple[Foo, ...]:\n '''\n Return contained Foo instances.\n\n Returns:\n tuple[Foo, ...]:\n Stored foo objects.\n\n Example:\n ```python\n container = FooContainer()\n\n foos = container.foos\n ```\n '''\n ```\n\n---\n\n# Attribute documentation\n\nDocument attributes in class docstrings using `Attributes:`.\n\nExample:\n Attribute Doc String:\n\n ```python\n '''\n Represents a processing stage.\n\n Attributes:\n id (str):\n Unique identifier.\n\n enabled (bool):\n Whether the stage is active.\n '''\n ```\n\n---\n\n# Parsing guarantees\n\nGSDFC ensures doc-forge can deterministically extract:\n\n- symbol kind (module, class, function, property, attribute)\n- symbol name\n- parameters\n- return values\n- attributes\n- examples\n- structured Notes subsections\n\nThis enables:\n\n- reliable MkDocs rendering\n- deterministic MCP export\n- accurate AI semantic interpretation\n\n---\n\nNotes:\n - doc-forge never executes analyzed modules.\n - Documentation is generated entirely through static analysis.", "objects": { "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -32,7 +32,7 @@ "kind": "function", "path": "docforge.discover_module_paths", "signature": "", - "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, optional):\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." + "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", @@ -53,14 +53,14 @@ "kind": "function", "path": "docforge.MkDocsRenderer.generate_sources", "signature": "", - "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, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." + "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": "", - "docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n 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 (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`." + "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`." } } }, @@ -216,22 +216,22 @@ "name": "load_openapi_spec", "kind": "function", "path": "docforge.cli.api_utils.load_openapi_spec", - "signature": "", - "docstring": "Load and validate an OpenAPI specification from a JSON file.\n\nArgs:\n spec_path: Path to the OpenAPI JSON specification file.\n\nReturns:\n dict:\n The parsed OpenAPI specification.\n\nRaises:\n click.ClickException:\n If the file cannot be read or the ``info`` block is invalid." + "signature": "", + "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": "", - "docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec: Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec." + "signature": "", + "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": "", - "docstring": "Generate swagger-enabled Markdown sources and the spec copy.\n\nThe specification is written as ``openapi.json`` inside ``docs_dir`` and\nan ``index.md`` embedding the swagger UI is generated alongside it.\n\nArgs:\n spec: Parsed OpenAPI specification.\n docs_dir: Directory (for example ``docs/api``) where the swagger\n sources are written." + "signature": "", + "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", @@ -247,7 +247,7 @@ "kind": "module", "path": "docforge.cli.commands", "signature": null, - "docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.", + "docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.\n\n---\n\nNotes:\n - The `build` command validates requested modes before generating anything.\n - `--mkdocs`, `--api`, and `--wiki` share a single MkDocs build; `--mcp`\n generates a machine-readable bundle independently.\n\n---", "members": { "Path": { "name": "Path", @@ -340,21 +340,21 @@ "kind": "function", "path": "docforge.cli.commands.api_utils.load_openapi_spec", "signature": "", - "docstring": "Load and validate an OpenAPI specification from a JSON file.\n\nArgs:\n spec_path: Path to the OpenAPI JSON specification file.\n\nReturns:\n dict:\n The parsed OpenAPI specification.\n\nRaises:\n click.ClickException:\n If the file cannot be read or the ``info`` block is invalid." + "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": "", - "docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec: Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec." + "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": "", - "docstring": "Generate swagger-enabled Markdown sources and the spec copy.\n\nThe specification is written as ``openapi.json`` inside ``docs_dir`` and\nan ``index.md`` embedding the swagger UI is generated alongside it.\n\nArgs:\n spec: Parsed OpenAPI specification.\n docs_dir: Directory (for example ``docs/api``) where the swagger\n sources are written." + "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", @@ -370,7 +370,7 @@ "kind": "module", "path": "docforge.cli.commands.mcp_utils", "signature": "", - "docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.", + "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", @@ -391,21 +391,21 @@ "kind": "class", "path": "docforge.cli.commands.mcp_utils.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -414,7 +414,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.discover_module_paths", "signature": "", - "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, optional):\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." + "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", @@ -444,7 +444,7 @@ "kind": "class", "path": "docforge.cli.commands.mcp_utils.MCPServer", "signature": "", - "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.", + "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", @@ -474,7 +474,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.generate_resources", "signature": "", - "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 (Optional[str]):\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." + "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", @@ -490,7 +490,7 @@ "kind": "module", "path": "docforge.cli.commands.mkdocs_utils", "signature": "", - "docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.", + "docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A single generated `mkdocs.yml` serves lib, api, and wiki content with\n merged navigation. Wiki navigation, when enabled, precedes every other\n group and its `index.md` becomes the site `Home`.\n\n---", "members": { "os": { "name": "os", @@ -539,21 +539,21 @@ "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -562,7 +562,7 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths", "signature": "", - "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, optional):\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." + "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", @@ -576,23 +576,30 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit", "signature": "", - "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\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." + "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav (ResolvedNav):\n Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n list[dict[str, Any]]:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." } } }, + "build_wiki_nav": { + "name": "build_wiki_nav", + "kind": "function", + "path": "docforge.cli.commands.mkdocs_utils.build_wiki_nav", + "signature": "", + "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": "", - "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 to the navigation specification file.\n\nReturns:\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." + "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": "", - "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: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\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." + "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", @@ -613,14 +620,14 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "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, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." + "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": "", - "docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n 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 (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`." + "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`." } } }, @@ -629,14 +636,14 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_sources", "signature": "", - "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 (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``." + "docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_config", "signature": "", - "docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Optional[Path]):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Optional[Iterable[str]]):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib`` or ``api``),\n merged on top of the shared ``mkdocs.common.yml`` template.\n\n site_description (Optional[str]):\n Optional site description written into the configuration.\n\n site_author (Optional[str]):\n Optional site author written into the configuration.\n\nRaises:\n click.FileError:\n If the navigation specification or template file cannot be found." + "docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification (and, when a wiki directory is provided, from the wiki\nfile structure).\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories\nand hand-written wiki content under a ``wiki/`` subdirectory.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Iterable[str] | None):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib``, ``api``, or\n ``wiki``), merged on top of the shared ``mkdocs.common.yml``\n template.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n wiki_dir (Path | None):\n Optional path to a hand-written wiki directory (for example\n ``docs/wiki``). When provided, the site navigation is derived\n from the wiki file structure and placed before the navigation\n groups defined in ``nav_file``.\n\nRaises:\n click.FileError:\n If the navigation specification, template, or wiki directory\n cannot be found." }, "build": { "name": "build", @@ -659,21 +666,93 @@ "kind": "class", "path": "docforge.cli.commands.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance.\n\nRaises:\n ImportError:\n If the module cannot be loaded by Griffe.\n\n KeyError:\n If the loaded module is missing from the module collection.\n\nExample:\n Load a single module:\n\n ```python\n loader = GriffeLoader()\n module = loader.load_module(\"mypackage.submodule\")\n ```" + } + } + }, + "DocObject": { + "name": "DocObject", + "kind": "class", + "path": "docforge.cli.commands.DocObject", + "signature": "", + "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": "", + "docstring": null + }, + "kind": { + "name": "kind", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.kind", + "signature": "", + "docstring": null + }, + "path": { + "name": "path", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.path", + "signature": "", + "docstring": null + }, + "signature": { + "name": "signature", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.signature", + "signature": "", + "docstring": null + }, + "docstring": { + "name": "docstring", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.docstring", + "signature": "", + "docstring": null + }, + "members": { + "name": "members", + "kind": "attribute", + "path": "docforge.cli.commands.DocObject.members", + "signature": "", + "docstring": null + }, + "add_member": { + "name": "add_member", + "kind": "function", + "path": "docforge.cli.commands.DocObject.add_member", + "signature": "", + "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": "", + "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": "", + "docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." } } }, @@ -688,29 +767,22 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", - "docstring": "Build documentation artifacts.\n\nThis command performs the full documentation build pipeline:\nstyle of the selected platform, generates renderer-specific\ndocumentation sources, and optionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites for library reference docs\n- Swagger-enabled API docs generated from an OpenAPI spec\n- MCP structured documentation resources\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs library documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (Optional[str]):\n Python module import path to document.\n\n openapi_spec (Optional[Path]):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (Optional[str]):\n Optional override for the project name.\n\n site_name (Optional[str]):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Optional[Path]):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." + "signature": "", + "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds or serves the final output.\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites for library reference docs\n- Swagger-enabled API docs generated from an OpenAPI spec\n- Hand-written wiki pages included in the MkDocs site\n- MCP structured documentation resources\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` are combined into a single MkDocs\n build, while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs library documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Include a hand-written wiki directory in the MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.serve", - "signature": "", - "docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (Optional[str]):\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." + "signature": "", + "docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided." }, "tree": { "name": "tree", "kind": "function", "path": "docforge.cli.commands.tree", - "signature": "", - "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 (Optional[str]):\n Optional name to display as the project root." - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "docforge.cli.commands.Any", - "signature": "", - "docstring": null + "signature": "", + "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", @@ -726,7 +798,7 @@ "kind": "module", "path": "docforge.cli.mcp_utils", "signature": null, - "docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.", + "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", @@ -747,21 +819,21 @@ "kind": "class", "path": "docforge.cli.mcp_utils.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -770,7 +842,7 @@ "kind": "function", "path": "docforge.cli.mcp_utils.discover_module_paths", "signature": "", - "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, optional):\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." + "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", @@ -800,7 +872,7 @@ "kind": "class", "path": "docforge.cli.mcp_utils.MCPServer", "signature": "", - "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.", + "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", @@ -829,14 +901,14 @@ "name": "generate_resources", "kind": "function", "path": "docforge.cli.mcp_utils.generate_resources", - "signature": "", - "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 (Optional[str]):\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." + "signature": "", + "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": "", "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." } } @@ -846,7 +918,7 @@ "kind": "module", "path": "docforge.cli.mkdocs_utils", "signature": null, - "docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.", + "docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A single generated `mkdocs.yml` serves lib, api, and wiki content with\n merged navigation. Wiki navigation, when enabled, precedes every other\n group and its `index.md` becomes the site `Home`.\n\n---", "members": { "os": { "name": "os", @@ -895,21 +967,21 @@ "kind": "class", "path": "docforge.cli.mkdocs_utils.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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,7 +990,7 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.discover_module_paths", "signature": "", - "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, optional):\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." + "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", @@ -932,23 +1004,30 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit", "signature": "", - "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\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." + "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav (ResolvedNav):\n Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n list[dict[str, Any]]:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." } } }, + "build_wiki_nav": { + "name": "build_wiki_nav", + "kind": "function", + "path": "docforge.cli.mkdocs_utils.build_wiki_nav", + "signature": "", + "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": "", - "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 to the navigation specification file.\n\nReturns:\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." + "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": "", - "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: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\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." + "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", @@ -969,14 +1048,14 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "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, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." + "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": "", - "docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n 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 (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`." + "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`." } } }, @@ -984,28 +1063,28 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_sources", - "signature": "", - "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 (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``." + "signature": "", + "docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_config", - "signature": "", - "docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Optional[Path]):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Optional[Iterable[str]]):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib`` or ``api``),\n merged on top of the shared ``mkdocs.common.yml`` template.\n\n site_description (Optional[str]):\n Optional site description written into the configuration.\n\n site_author (Optional[str]):\n Optional site author written into the configuration.\n\nRaises:\n click.FileError:\n If the navigation specification or template file cannot be found." + "signature": "", + "docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification (and, when a wiki directory is provided, from the wiki\nfile structure).\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories\nand hand-written wiki content under a ``wiki/`` subdirectory.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Iterable[str] | None):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib``, ``api``, or\n ``wiki``), merged on top of the shared ``mkdocs.common.yml``\n template.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n wiki_dir (Path | None):\n Optional path to a hand-written wiki directory (for example\n ``docs/wiki``). When provided, the site navigation is derived\n from the wiki file structure and placed before the navigation\n groups defined in ``nav_file``.\n\nRaises:\n click.FileError:\n If the navigation specification, template, or wiki directory\n cannot be found." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.mkdocs_utils.build", - "signature": "", + "signature": "", "docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.mkdocs_utils.serve", - "signature": "", + "signature": "", "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." } } @@ -1024,21 +1103,21 @@ "kind": "class", "path": "docforge.loaders.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -1047,14 +1126,14 @@ "kind": "function", "path": "docforge.loaders.discover_module_paths", "signature": "", - "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, optional):\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." + "docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path | None):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n list[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist." }, "griffe_loader": { "name": "griffe_loader", "kind": "module", "path": "docforge.loaders.griffe_loader", "signature": null, - "docstring": "# Summary\n\nUtilities for loading and introspecting Python modules using Griffe.\n\nThis module provides the `GriffeLoader` class and helper utilities used to\ndiscover Python modules, introspect their structure, and convert the results\ninto doc-forge documentation models.", + "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---", "members": { "logging": { "name": "logging", @@ -1103,7 +1182,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.DocObject", "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "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", @@ -1152,7 +1231,7 @@ "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.add_member", "signature": "", - "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: Documentation object to add as a member." + "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member." }, "get_member": { "name": "get_member", @@ -1175,7 +1254,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -1226,7 +1305,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.Project", "signature": "", - "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.", + "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", @@ -1283,29 +1362,29 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.loaders.griffe_loader.discover_module_paths", - "signature": "", - "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, optional):\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." + "signature": "", + "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": "", - "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.", + "signature": "", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "signature": "", + "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": "", - "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." + "signature": "", + "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 ```" } } } @@ -1325,7 +1404,7 @@ "kind": "class", "path": "docforge.models.Project", "signature": "", - "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.", + "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", @@ -1376,7 +1455,7 @@ "kind": "class", "path": "docforge.models.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -1427,7 +1506,7 @@ "kind": "class", "path": "docforge.models.DocObject", "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "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", @@ -1476,7 +1555,7 @@ "kind": "function", "path": "docforge.models.DocObject.add_member", "signature": "", - "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: Documentation object to add as a member." + "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member." }, "get_member": { "name": "get_member", @@ -1499,7 +1578,7 @@ "kind": "module", "path": "docforge.models.module", "signature": null, - "docstring": "# Summary\n\nDocumentation model representing a Python module or package.\n\nThis module defines the `Module` class used in the doc-forge documentation\nmodel. A `Module` acts as a container for top-level documented objects\n(classes, functions, variables, and other members) discovered during\nintrospection.", + "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", @@ -1513,7 +1592,7 @@ "kind": "class", "path": "docforge.models.module.DocObject", "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "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", @@ -1562,7 +1641,7 @@ "kind": "function", "path": "docforge.models.module.DocObject.add_member", "signature": "", - "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: Documentation object to add as a member." + "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member." }, "get_member": { "name": "get_member", @@ -1584,8 +1663,8 @@ "name": "Module", "kind": "class", "path": "docforge.models.module.Module", - "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "signature": "", + "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", @@ -1612,21 +1691,21 @@ "name": "add_object", "kind": "function", "path": "docforge.models.module.Module.add_object", - "signature": "", + "signature": "", "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": "", "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": "", "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." } } @@ -1638,7 +1717,7 @@ "kind": "module", "path": "docforge.models.object", "signature": null, - "docstring": "# Summary\n\nDocumentation model representing individual Python objects.\n\nThis module defines the `DocObject` class, the fundamental recursive unit of\nthe doc-forge documentation model. Each `DocObject` represents a Python\nentity such as a class, function, method, or attribute, and may contain nested\nmembers that form a hierarchical documentation structure.", + "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", @@ -1651,8 +1730,8 @@ "name": "DocObject", "kind": "class", "path": "docforge.models.object.DocObject", - "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "signature": "", + "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", @@ -1700,21 +1779,21 @@ "name": "add_member", "kind": "function", "path": "docforge.models.object.DocObject.add_member", - "signature": "", - "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: Documentation object to add as a member." + "signature": "", + "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": "", "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": "", "docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." } } @@ -1726,7 +1805,7 @@ "kind": "module", "path": "docforge.models.project", "signature": null, - "docstring": "# Summary\n\nDocumentation model representing a project.\n\nThis module defines the `Project` class, the top-level container used by\ndoc-forge to represent a documented codebase. A `Project` aggregates multiple\nmodules and provides access to them through a unified interface.", + "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", @@ -1740,7 +1819,7 @@ "kind": "class", "path": "docforge.models.project.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -1790,8 +1869,8 @@ "name": "Project", "kind": "class", "path": "docforge.models.project.Project", - "signature": "", - "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.", + "signature": "", + "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", @@ -1811,28 +1890,28 @@ "name": "add_module", "kind": "function", "path": "docforge.models.project.Project.add_module", - "signature": "", + "signature": "", "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": "", "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": "", "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": "", "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." } } @@ -1881,14 +1960,14 @@ "kind": "function", "path": "docforge.nav.NavSpec.load", "signature": "", - "docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\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." + "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": "", - "docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries." + "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." } } }, @@ -1897,7 +1976,7 @@ "kind": "function", "path": "docforge.nav.load_nav_spec", "signature": "", - "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 to the navigation specification file.\n\nReturns:\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." + "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", @@ -1925,7 +2004,7 @@ "kind": "function", "path": "docforge.nav.ResolvedNav.all_files", "signature": "", - "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution." + "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." } } }, @@ -1934,7 +2013,7 @@ "kind": "function", "path": "docforge.nav.resolve_nav", "signature": "", - "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: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\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." + "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", @@ -1948,16 +2027,23 @@ "kind": "function", "path": "docforge.nav.MkDocsNavEmitter.emit", "signature": "", - "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\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." + "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav (ResolvedNav):\n Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n list[dict[str, Any]]:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." } } }, + "build_wiki_nav": { + "name": "build_wiki_nav", + "kind": "function", + "path": "docforge.nav.build_wiki_nav", + "signature": "", + "docstring": "Derive an MkDocs navigation block from a wiki directory.\n\nReturned paths are relative to the parent of ``wiki_dir`` and carry the\nwiki directory name as their leading component (for example\n``wiki/01_overview.md`` when the wiki lives at ``docs/wiki``). This makes\nthe result directly usable in an MkDocs ``nav`` block with\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries compatible with the MkDocs ``nav`` configuration.\n The list is empty if the wiki contains no Markdown files.\n\nRaises:\n FileNotFoundError:\n If the wiki directory does not exist." + }, "mkdocs": { "name": "mkdocs", "kind": "module", "path": "docforge.nav.mkdocs", "signature": null, - "docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.", + "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", @@ -1999,7 +2085,7 @@ "kind": "function", "path": "docforge.nav.mkdocs.ResolvedNav.all_files", "signature": "", - "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution." + "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." } } }, @@ -2007,15 +2093,15 @@ "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.nav.mkdocs.MkDocsNavEmitter", - "signature": "", + "signature": "", "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": "", - "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\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." + "signature": "", + "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." } } } @@ -2026,7 +2112,7 @@ "kind": "module", "path": "docforge.nav.resolver", "signature": null, - "docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.", + "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", @@ -2082,14 +2168,14 @@ "kind": "function", "path": "docforge.nav.resolver.NavSpec.load", "signature": "", - "docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\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." + "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": "", - "docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries." + "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." } } }, @@ -2097,7 +2183,7 @@ "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.resolver.ResolvedNav", - "signature": "", + "signature": "", "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": { @@ -2118,8 +2204,8 @@ "name": "all_files", "kind": "function", "path": "docforge.nav.resolver.ResolvedNav.all_files", - "signature": "", - "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution." + "signature": "", + "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." } } }, @@ -2127,8 +2213,8 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolver.resolve_nav", - "signature": "", - "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: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\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." + "signature": "", + "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." } } }, @@ -2137,8 +2223,15 @@ "kind": "module", "path": "docforge.nav.spec", "signature": null, - "docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).", + "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", @@ -2157,7 +2250,7 @@ "name": "NavSpec", "kind": "class", "path": "docforge.nav.spec.NavSpec", - "signature": "", + "signature": "", "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": { @@ -2185,15 +2278,15 @@ "name": "load", "kind": "function", "path": "docforge.nav.spec.NavSpec.load", - "signature": "", - "docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\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." + "signature": "", + "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": "", - "docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries." + "signature": "", + "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." } } }, @@ -2201,8 +2294,52 @@ "name": "load_nav_spec", "kind": "function", "path": "docforge.nav.spec.load_nav_spec", - "signature": "", - "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 to the navigation specification file.\n\nReturns:\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." + "signature": "", + "docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path (Path):\n Path to the navigation specification file.\n\nReturns:\n NavSpec:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid." + } + } + }, + "wiki": { + "name": "wiki", + "kind": "module", + "path": "docforge.nav.wiki", + "signature": null, + "docstring": "# Summary\n\nWiki navigation derivation.\n\nThis module provides ``build_wiki_nav``, which derives an MkDocs-ready\nnavigation block from the file structure of a hand-written wiki directory\n(typically ``docs/wiki``). wiki content is authored by hand and is never\nmodified by doc-forge; only the navigation layout is inferred.\n\n# Notes\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.", + "members": { + "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": "", + "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." } } } @@ -2234,14 +2371,14 @@ "kind": "function", "path": "docforge.renderers.MkDocsRenderer.generate_sources", "signature": "", - "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, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." + "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": "", - "docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n 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 (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`." + "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`." } } }, @@ -2294,7 +2431,7 @@ "kind": "class", "path": "docforge.renderers.base.Project", "signature": "", - "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.", + "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", @@ -2414,7 +2551,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.DocObject", "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "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", @@ -2463,7 +2600,7 @@ "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.add_member", "signature": "", - "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: Documentation object to add as a member." + "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member." }, "get_member": { "name": "get_member", @@ -2486,7 +2623,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -2537,7 +2674,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.Project", "signature": "", - "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.", + "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", @@ -2634,7 +2771,7 @@ "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -2685,7 +2822,7 @@ "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Project", "signature": "", - "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.", + "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", @@ -2735,7 +2872,7 @@ "name": "MkDocsRenderer", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", - "signature": "", + "signature": "", "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": { @@ -2750,14 +2887,14 @@ "kind": "function", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", "signature": "", - "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, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." + "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": "", - "docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n 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 (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`." + "signature": "", + "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`." } } } @@ -2777,7 +2914,7 @@ "kind": "class", "path": "docforge.servers.MCPServer", "signature": "", - "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.", + "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", @@ -2807,7 +2944,7 @@ "kind": "module", "path": "docforge.servers.mcp_server", "signature": null, - "docstring": "# Summary\n\nMCP server implementation.\n\nThis module defines the `MCPServer` class, which serves pre-generated\ndocumentation bundles through the Model Context Protocol (MCP).", + "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", @@ -2855,8 +2992,8 @@ "name": "MCPServer", "kind": "class", "path": "docforge.servers.mcp_server.MCPServer", - "signature": "", - "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.", + "signature": "", + "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", @@ -2876,7 +3013,7 @@ "name": "run", "kind": "function", "path": "docforge.servers.mcp_server.MCPServer.run", - "signature": "", + "signature": "", "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 316d34f..82f2bd7 100644 --- a/docs/mcp/modules/docforge.loaders.griffe_loader.json +++ b/docs/mcp/modules/docforge.loaders.griffe_loader.json @@ -2,7 +2,7 @@ "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.", + "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---", "objects": { "logging": { "name": "logging", @@ -51,7 +51,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.DocObject", "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "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", @@ -100,7 +100,7 @@ "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.add_member", "signature": "", - "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: Documentation object to add as a member." + "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member." }, "get_member": { "name": "get_member", @@ -123,7 +123,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -174,7 +174,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.Project", "signature": "", - "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.", + "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", @@ -231,29 +231,29 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.loaders.griffe_loader.discover_module_paths", - "signature": "", - "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, optional):\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." + "signature": "", + "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": "", - "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.", + "signature": "", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "signature": "", + "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": "", - "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." + "signature": "", + "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 fcfe8b7..ade3960 100644 --- a/docs/mcp/modules/docforge.loaders.json +++ b/docs/mcp/modules/docforge.loaders.json @@ -9,21 +9,21 @@ "kind": "class", "path": "docforge.loaders.GriffeLoader", "signature": "", - "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.", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "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": "", - "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." + "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 ```" } } }, @@ -32,14 +32,14 @@ "kind": "function", "path": "docforge.loaders.discover_module_paths", "signature": "", - "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, optional):\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." + "docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path | None):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n list[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist." }, "griffe_loader": { "name": "griffe_loader", "kind": "module", "path": "docforge.loaders.griffe_loader", "signature": null, - "docstring": "# Summary\n\nUtilities for loading and introspecting Python modules using Griffe.\n\nThis module provides the `GriffeLoader` class and helper utilities used to\ndiscover Python modules, introspect their structure, and convert the results\ninto doc-forge documentation models.", + "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---", "members": { "logging": { "name": "logging", @@ -88,7 +88,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.DocObject", "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "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", @@ -137,7 +137,7 @@ "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.add_member", "signature": "", - "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: Documentation object to add as a member." + "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member." }, "get_member": { "name": "get_member", @@ -160,7 +160,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -211,7 +211,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.Project", "signature": "", - "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.", + "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", @@ -268,29 +268,29 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.loaders.griffe_loader.discover_module_paths", - "signature": "", - "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, optional):\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." + "signature": "", + "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": "", - "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.", + "signature": "", + "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": "", - "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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." + "signature": "", + "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": "", - "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." + "signature": "", + "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 1d513fb..a167787 100644 --- a/docs/mcp/modules/docforge.models.json +++ b/docs/mcp/modules/docforge.models.json @@ -9,7 +9,7 @@ "kind": "class", "path": "docforge.models.Project", "signature": "", - "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.", + "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", @@ -60,7 +60,7 @@ "kind": "class", "path": "docforge.models.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -111,7 +111,7 @@ "kind": "class", "path": "docforge.models.DocObject", "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "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", @@ -160,7 +160,7 @@ "kind": "function", "path": "docforge.models.DocObject.add_member", "signature": "", - "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: Documentation object to add as a member." + "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member." }, "get_member": { "name": "get_member", @@ -183,7 +183,7 @@ "kind": "module", "path": "docforge.models.module", "signature": null, - "docstring": "# Summary\n\nDocumentation model representing a Python module or package.\n\nThis module defines the `Module` class used in the doc-forge documentation\nmodel. A `Module` acts as a container for top-level documented objects\n(classes, functions, variables, and other members) discovered during\nintrospection.", + "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", @@ -197,7 +197,7 @@ "kind": "class", "path": "docforge.models.module.DocObject", "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "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", @@ -246,7 +246,7 @@ "kind": "function", "path": "docforge.models.module.DocObject.add_member", "signature": "", - "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: Documentation object to add as a member." + "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member." }, "get_member": { "name": "get_member", @@ -268,8 +268,8 @@ "name": "Module", "kind": "class", "path": "docforge.models.module.Module", - "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "signature": "", + "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", @@ -296,21 +296,21 @@ "name": "add_object", "kind": "function", "path": "docforge.models.module.Module.add_object", - "signature": "", + "signature": "", "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": "", "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": "", "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." } } @@ -322,7 +322,7 @@ "kind": "module", "path": "docforge.models.object", "signature": null, - "docstring": "# Summary\n\nDocumentation model representing individual Python objects.\n\nThis module defines the `DocObject` class, the fundamental recursive unit of\nthe doc-forge documentation model. Each `DocObject` represents a Python\nentity such as a class, function, method, or attribute, and may contain nested\nmembers that form a hierarchical documentation structure.", + "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", @@ -335,8 +335,8 @@ "name": "DocObject", "kind": "class", "path": "docforge.models.object.DocObject", - "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "signature": "", + "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", @@ -384,21 +384,21 @@ "name": "add_member", "kind": "function", "path": "docforge.models.object.DocObject.add_member", - "signature": "", - "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: Documentation object to add as a member." + "signature": "", + "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": "", "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": "", "docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." } } @@ -410,7 +410,7 @@ "kind": "module", "path": "docforge.models.project", "signature": null, - "docstring": "# Summary\n\nDocumentation model representing a project.\n\nThis module defines the `Project` class, the top-level container used by\ndoc-forge to represent a documented codebase. A `Project` aggregates multiple\nmodules and provides access to them through a unified interface.", + "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", @@ -424,7 +424,7 @@ "kind": "class", "path": "docforge.models.project.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -474,8 +474,8 @@ "name": "Project", "kind": "class", "path": "docforge.models.project.Project", - "signature": "", - "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.", + "signature": "", + "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", @@ -495,28 +495,28 @@ "name": "add_module", "kind": "function", "path": "docforge.models.project.Project.add_module", - "signature": "", + "signature": "", "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": "", "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": "", "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": "", "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 55fb892..12cc47e 100644 --- a/docs/mcp/modules/docforge.models.module.json +++ b/docs/mcp/modules/docforge.models.module.json @@ -2,7 +2,7 @@ "module": "docforge.models.module", "content": { "path": "docforge.models.module", - "docstring": "# Summary\n\nDocumentation model representing a Python module or package.\n\nThis module defines the `Module` class used in the doc-forge documentation\nmodel. A `Module` acts as a container for top-level documented objects\n(classes, functions, variables, and other members) discovered during\nintrospection.", + "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", @@ -16,7 +16,7 @@ "kind": "class", "path": "docforge.models.module.DocObject", "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "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", @@ -65,7 +65,7 @@ "kind": "function", "path": "docforge.models.module.DocObject.add_member", "signature": "", - "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: Documentation object to add as a member." + "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member." }, "get_member": { "name": "get_member", @@ -87,8 +87,8 @@ "name": "Module", "kind": "class", "path": "docforge.models.module.Module", - "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "signature": "", + "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", @@ -115,21 +115,21 @@ "name": "add_object", "kind": "function", "path": "docforge.models.module.Module.add_object", - "signature": "", + "signature": "", "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": "", "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": "", "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 3c18f97..ff22ae4 100644 --- a/docs/mcp/modules/docforge.models.object.json +++ b/docs/mcp/modules/docforge.models.object.json @@ -2,7 +2,7 @@ "module": "docforge.models.object", "content": { "path": "docforge.models.object", - "docstring": "# Summary\n\nDocumentation model representing individual Python objects.\n\nThis module defines the `DocObject` class, the fundamental recursive unit of\nthe doc-forge documentation model. Each `DocObject` represents a Python\nentity such as a class, function, method, or attribute, and may contain nested\nmembers that form a hierarchical documentation structure.", + "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", @@ -15,8 +15,8 @@ "name": "DocObject", "kind": "class", "path": "docforge.models.object.DocObject", - "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "signature": "", + "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", @@ -64,21 +64,21 @@ "name": "add_member", "kind": "function", "path": "docforge.models.object.DocObject.add_member", - "signature": "", - "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: Documentation object to add as a member." + "signature": "", + "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": "", "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": "", "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 c91f83b..5ae72c9 100644 --- a/docs/mcp/modules/docforge.models.project.json +++ b/docs/mcp/modules/docforge.models.project.json @@ -2,7 +2,7 @@ "module": "docforge.models.project", "content": { "path": "docforge.models.project", - "docstring": "# Summary\n\nDocumentation model representing a project.\n\nThis module defines the `Project` class, the top-level container used by\ndoc-forge to represent a documented codebase. A `Project` aggregates multiple\nmodules and provides access to them through a unified interface.", + "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", @@ -16,7 +16,7 @@ "kind": "class", "path": "docforge.models.project.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -66,8 +66,8 @@ "name": "Project", "kind": "class", "path": "docforge.models.project.Project", - "signature": "", - "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.", + "signature": "", + "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", @@ -87,28 +87,28 @@ "name": "add_module", "kind": "function", "path": "docforge.models.project.Project.add_module", - "signature": "", + "signature": "", "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": "", "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": "", "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": "", "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 85ef248..6cd1fae 100644 --- a/docs/mcp/modules/docforge.nav.json +++ b/docs/mcp/modules/docforge.nav.json @@ -37,14 +37,14 @@ "kind": "function", "path": "docforge.nav.NavSpec.load", "signature": "", - "docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\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." + "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": "", - "docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries." + "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." } } }, @@ -53,7 +53,7 @@ "kind": "function", "path": "docforge.nav.load_nav_spec", "signature": "", - "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 to the navigation specification file.\n\nReturns:\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." + "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", @@ -81,7 +81,7 @@ "kind": "function", "path": "docforge.nav.ResolvedNav.all_files", "signature": "", - "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution." + "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." } } }, @@ -90,7 +90,7 @@ "kind": "function", "path": "docforge.nav.resolve_nav", "signature": "", - "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: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\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." + "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", @@ -104,16 +104,23 @@ "kind": "function", "path": "docforge.nav.MkDocsNavEmitter.emit", "signature": "", - "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\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." + "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav (ResolvedNav):\n Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n list[dict[str, Any]]:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." } } }, + "build_wiki_nav": { + "name": "build_wiki_nav", + "kind": "function", + "path": "docforge.nav.build_wiki_nav", + "signature": "", + "docstring": "Derive an MkDocs navigation block from a wiki directory.\n\nReturned paths are relative to the parent of ``wiki_dir`` and carry the\nwiki directory name as their leading component (for example\n``wiki/01_overview.md`` when the wiki lives at ``docs/wiki``). This makes\nthe result directly usable in an MkDocs ``nav`` block with\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries compatible with the MkDocs ``nav`` configuration.\n The list is empty if the wiki contains no Markdown files.\n\nRaises:\n FileNotFoundError:\n If the wiki directory does not exist." + }, "mkdocs": { "name": "mkdocs", "kind": "module", "path": "docforge.nav.mkdocs", "signature": null, - "docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.", + "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", @@ -155,7 +162,7 @@ "kind": "function", "path": "docforge.nav.mkdocs.ResolvedNav.all_files", "signature": "", - "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution." + "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." } } }, @@ -163,15 +170,15 @@ "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.nav.mkdocs.MkDocsNavEmitter", - "signature": "", + "signature": "", "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": "", - "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\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." + "signature": "", + "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." } } } @@ -182,7 +189,7 @@ "kind": "module", "path": "docforge.nav.resolver", "signature": null, - "docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.", + "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", @@ -238,14 +245,14 @@ "kind": "function", "path": "docforge.nav.resolver.NavSpec.load", "signature": "", - "docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\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." + "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": "", - "docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries." + "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." } } }, @@ -253,7 +260,7 @@ "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.resolver.ResolvedNav", - "signature": "", + "signature": "", "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": { @@ -274,8 +281,8 @@ "name": "all_files", "kind": "function", "path": "docforge.nav.resolver.ResolvedNav.all_files", - "signature": "", - "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution." + "signature": "", + "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." } } }, @@ -283,8 +290,8 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolver.resolve_nav", - "signature": "", - "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: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\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." + "signature": "", + "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." } } }, @@ -293,8 +300,15 @@ "kind": "module", "path": "docforge.nav.spec", "signature": null, - "docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).", + "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", @@ -313,7 +327,7 @@ "name": "NavSpec", "kind": "class", "path": "docforge.nav.spec.NavSpec", - "signature": "", + "signature": "", "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": { @@ -341,15 +355,15 @@ "name": "load", "kind": "function", "path": "docforge.nav.spec.NavSpec.load", - "signature": "", - "docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\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." + "signature": "", + "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": "", - "docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries." + "signature": "", + "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." } } }, @@ -357,8 +371,52 @@ "name": "load_nav_spec", "kind": "function", "path": "docforge.nav.spec.load_nav_spec", - "signature": "", - "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 to the navigation specification file.\n\nReturns:\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." + "signature": "", + "docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path (Path):\n Path to the navigation specification file.\n\nReturns:\n NavSpec:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid." + } + } + }, + "wiki": { + "name": "wiki", + "kind": "module", + "path": "docforge.nav.wiki", + "signature": null, + "docstring": "# Summary\n\nWiki navigation derivation.\n\nThis module provides ``build_wiki_nav``, which derives an MkDocs-ready\nnavigation block from the file structure of a hand-written wiki directory\n(typically ``docs/wiki``). wiki content is authored by hand and is never\nmodified by doc-forge; only the navigation layout is inferred.\n\n# Notes\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.", + "members": { + "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": "", + "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 1bb40f9..9d272f8 100644 --- a/docs/mcp/modules/docforge.nav.mkdocs.json +++ b/docs/mcp/modules/docforge.nav.mkdocs.json @@ -2,7 +2,7 @@ "module": "docforge.nav.mkdocs", "content": { "path": "docforge.nav.mkdocs", - "docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.", + "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", @@ -44,7 +44,7 @@ "kind": "function", "path": "docforge.nav.mkdocs.ResolvedNav.all_files", "signature": "", - "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution." + "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,15 +52,15 @@ "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.nav.mkdocs.MkDocsNavEmitter", - "signature": "", + "signature": "", "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": "", - "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\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." + "signature": "", + "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 2df085f..2f0432a 100644 --- a/docs/mcp/modules/docforge.nav.resolver.json +++ b/docs/mcp/modules/docforge.nav.resolver.json @@ -2,7 +2,7 @@ "module": "docforge.nav.resolver", "content": { "path": "docforge.nav.resolver", - "docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.", + "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", @@ -58,14 +58,14 @@ "kind": "function", "path": "docforge.nav.resolver.NavSpec.load", "signature": "", - "docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\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." + "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": "", - "docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries." + "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 +73,7 @@ "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.resolver.ResolvedNav", - "signature": "", + "signature": "", "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,8 +94,8 @@ "name": "all_files", "kind": "function", "path": "docforge.nav.resolver.ResolvedNav.all_files", - "signature": "", - "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution." + "signature": "", + "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,8 +103,8 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolver.resolve_nav", - "signature": "", - "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: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\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." + "signature": "", + "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 ab0d693..825783a 100644 --- a/docs/mcp/modules/docforge.nav.spec.json +++ b/docs/mcp/modules/docforge.nav.spec.json @@ -2,8 +2,15 @@ "module": "docforge.nav.spec", "content": { "path": "docforge.nav.spec", - "docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).", + "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", @@ -22,7 +29,7 @@ "name": "NavSpec", "kind": "class", "path": "docforge.nav.spec.NavSpec", - "signature": "", + "signature": "", "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": { @@ -50,15 +57,15 @@ "name": "load", "kind": "function", "path": "docforge.nav.spec.NavSpec.load", - "signature": "", - "docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\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." + "signature": "", + "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": "", - "docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries." + "signature": "", + "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." } } }, @@ -66,8 +73,8 @@ "name": "load_nav_spec", "kind": "function", "path": "docforge.nav.spec.load_nav_spec", - "signature": "", - "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 to the navigation specification file.\n\nReturns:\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." + "signature": "", + "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 new file mode 100644 index 0000000..7fde14e --- /dev/null +++ b/docs/mcp/modules/docforge.nav.wiki.json @@ -0,0 +1,44 @@ +{ + "module": "docforge.nav.wiki", + "content": { + "path": "docforge.nav.wiki", + "docstring": "# Summary\n\nWiki navigation derivation.\n\nThis module provides ``build_wiki_nav``, which derives an MkDocs-ready\nnavigation block from the file structure of a hand-written wiki directory\n(typically ``docs/wiki``). wiki content is authored by hand and is never\nmodified by doc-forge; only the navigation layout is inferred.\n\n# Notes\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.", + "objects": { + "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": "", + "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." + } + } + } +} \ No newline at end of file diff --git a/docs/mcp/modules/docforge.renderers.base.json b/docs/mcp/modules/docforge.renderers.base.json index f19dd9b..3df962e 100644 --- a/docs/mcp/modules/docforge.renderers.base.json +++ b/docs/mcp/modules/docforge.renderers.base.json @@ -23,7 +23,7 @@ "kind": "class", "path": "docforge.renderers.base.Project", "signature": "", - "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.", + "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", diff --git a/docs/mcp/modules/docforge.renderers.json b/docs/mcp/modules/docforge.renderers.json index e2e2aa7..2f6f8fc 100644 --- a/docs/mcp/modules/docforge.renderers.json +++ b/docs/mcp/modules/docforge.renderers.json @@ -23,14 +23,14 @@ "kind": "function", "path": "docforge.renderers.MkDocsRenderer.generate_sources", "signature": "", - "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, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." + "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": "", - "docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n 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 (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`." + "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`." } } }, @@ -83,7 +83,7 @@ "kind": "class", "path": "docforge.renderers.base.Project", "signature": "", - "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.", + "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", @@ -203,7 +203,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.DocObject", "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "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", @@ -252,7 +252,7 @@ "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.add_member", "signature": "", - "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: Documentation object to add as a member." + "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member." }, "get_member": { "name": "get_member", @@ -275,7 +275,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -326,7 +326,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.Project", "signature": "", - "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.", + "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", @@ -423,7 +423,7 @@ "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -474,7 +474,7 @@ "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Project", "signature": "", - "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.", + "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", @@ -524,7 +524,7 @@ "name": "MkDocsRenderer", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", - "signature": "", + "signature": "", "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": { @@ -539,14 +539,14 @@ "kind": "function", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", "signature": "", - "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, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." + "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": "", - "docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n 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 (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`." + "signature": "", + "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 0fad6c6..3fc1e34 100644 --- a/docs/mcp/modules/docforge.renderers.mcp_renderer.json +++ b/docs/mcp/modules/docforge.renderers.mcp_renderer.json @@ -23,7 +23,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.DocObject", "signature": "", - "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 (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", + "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", @@ -72,7 +72,7 @@ "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.add_member", "signature": "", - "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: Documentation object to add as a member." + "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member." }, "get_member": { "name": "get_member", @@ -95,7 +95,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -146,7 +146,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.Project", "signature": "", - "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.", + "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", diff --git a/docs/mcp/modules/docforge.renderers.mkdocs_renderer.json b/docs/mcp/modules/docforge.renderers.mkdocs_renderer.json index 352c9cd..1e468a0 100644 --- a/docs/mcp/modules/docforge.renderers.mkdocs_renderer.json +++ b/docs/mcp/modules/docforge.renderers.mkdocs_renderer.json @@ -16,7 +16,7 @@ "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Module", "signature": "", - "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 (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", + "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", @@ -67,7 +67,7 @@ "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Project", "signature": "", - "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.", + "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", @@ -117,7 +117,7 @@ "name": "MkDocsRenderer", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", - "signature": "", + "signature": "", "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": { @@ -132,14 +132,14 @@ "kind": "function", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", "signature": "", - "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, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." + "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": "", - "docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n 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 (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`." + "signature": "", + "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 7d09733..c82cf66 100644 --- a/docs/mcp/modules/docforge.servers.json +++ b/docs/mcp/modules/docforge.servers.json @@ -9,7 +9,7 @@ "kind": "class", "path": "docforge.servers.MCPServer", "signature": "", - "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.", + "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", @@ -39,7 +39,7 @@ "kind": "module", "path": "docforge.servers.mcp_server", "signature": null, - "docstring": "# Summary\n\nMCP server implementation.\n\nThis module defines the `MCPServer` class, which serves pre-generated\ndocumentation bundles through the Model Context Protocol (MCP).", + "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", @@ -87,8 +87,8 @@ "name": "MCPServer", "kind": "class", "path": "docforge.servers.mcp_server.MCPServer", - "signature": "", - "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.", + "signature": "", + "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", @@ -108,7 +108,7 @@ "name": "run", "kind": "function", "path": "docforge.servers.mcp_server.MCPServer.run", - "signature": "", + "signature": "", "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 372c906..a7a69f8 100644 --- a/docs/mcp/modules/docforge.servers.mcp_server.json +++ b/docs/mcp/modules/docforge.servers.mcp_server.json @@ -2,7 +2,7 @@ "module": "docforge.servers.mcp_server", "content": { "path": "docforge.servers.mcp_server", - "docstring": "# Summary\n\nMCP server implementation.\n\nThis module defines the `MCPServer` class, which serves pre-generated\ndocumentation bundles through the Model Context Protocol (MCP).", + "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", @@ -50,8 +50,8 @@ "name": "MCPServer", "kind": "class", "path": "docforge.servers.mcp_server.MCPServer", - "signature": "", - "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.", + "signature": "", + "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", @@ -71,7 +71,7 @@ "name": "run", "kind": "function", "path": "docforge.servers.mcp_server.MCPServer.run", - "signature": "", + "signature": "", "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/nav.json b/docs/mcp/nav.json index 8f62362..c73b16b 100644 --- a/docs/mcp/nav.json +++ b/docs/mcp/nav.json @@ -1,94 +1,98 @@ [ { "module": "docforge", - "resource": "doc://modules/docforge" + "resource": "docs://modules/docforge" }, { "module": "docforge.cli", - "resource": "doc://modules/docforge.cli" + "resource": "docs://modules/docforge.cli" }, { "module": "docforge.cli.api_utils", - "resource": "doc://modules/docforge.cli.api_utils" + "resource": "docs://modules/docforge.cli.api_utils" }, { "module": "docforge.cli.commands", - "resource": "doc://modules/docforge.cli.commands" + "resource": "docs://modules/docforge.cli.commands" }, { "module": "docforge.cli.main", - "resource": "doc://modules/docforge.cli.main" + "resource": "docs://modules/docforge.cli.main" }, { "module": "docforge.cli.mcp_utils", - "resource": "doc://modules/docforge.cli.mcp_utils" + "resource": "docs://modules/docforge.cli.mcp_utils" }, { "module": "docforge.cli.mkdocs_utils", - "resource": "doc://modules/docforge.cli.mkdocs_utils" + "resource": "docs://modules/docforge.cli.mkdocs_utils" }, { "module": "docforge.loaders", - "resource": "doc://modules/docforge.loaders" + "resource": "docs://modules/docforge.loaders" }, { "module": "docforge.loaders.griffe_loader", - "resource": "doc://modules/docforge.loaders.griffe_loader" + "resource": "docs://modules/docforge.loaders.griffe_loader" }, { "module": "docforge.models", - "resource": "doc://modules/docforge.models" + "resource": "docs://modules/docforge.models" }, { "module": "docforge.models.module", - "resource": "doc://modules/docforge.models.module" + "resource": "docs://modules/docforge.models.module" }, { "module": "docforge.models.object", - "resource": "doc://modules/docforge.models.object" + "resource": "docs://modules/docforge.models.object" }, { "module": "docforge.models.project", - "resource": "doc://modules/docforge.models.project" + "resource": "docs://modules/docforge.models.project" }, { "module": "docforge.nav", - "resource": "doc://modules/docforge.nav" + "resource": "docs://modules/docforge.nav" }, { "module": "docforge.nav.mkdocs", - "resource": "doc://modules/docforge.nav.mkdocs" + "resource": "docs://modules/docforge.nav.mkdocs" }, { "module": "docforge.nav.resolver", - "resource": "doc://modules/docforge.nav.resolver" + "resource": "docs://modules/docforge.nav.resolver" }, { "module": "docforge.nav.spec", - "resource": "doc://modules/docforge.nav.spec" + "resource": "docs://modules/docforge.nav.spec" + }, + { + "module": "docforge.nav.wiki", + "resource": "docs://modules/docforge.nav.wiki" }, { "module": "docforge.renderers", - "resource": "doc://modules/docforge.renderers" + "resource": "docs://modules/docforge.renderers" }, { "module": "docforge.renderers.base", - "resource": "doc://modules/docforge.renderers.base" + "resource": "docs://modules/docforge.renderers.base" }, { "module": "docforge.renderers.mcp_renderer", - "resource": "doc://modules/docforge.renderers.mcp_renderer" + "resource": "docs://modules/docforge.renderers.mcp_renderer" }, { "module": "docforge.renderers.mkdocs_renderer", - "resource": "doc://modules/docforge.renderers.mkdocs_renderer" + "resource": "docs://modules/docforge.renderers.mkdocs_renderer" }, { "module": "docforge.servers", - "resource": "doc://modules/docforge.servers" + "resource": "docs://modules/docforge.servers" }, { "module": "docforge.servers.mcp_server", - "resource": "doc://modules/docforge.servers.mcp_server" + "resource": "docs://modules/docforge.servers.mcp_server" } ] \ No newline at end of file diff --git a/docs/wiki/01_overview.md b/docs/wiki/01_overview.md index 70cf1e2..d011ed9 100644 --- a/docs/wiki/01_overview.md +++ b/docs/wiki/01_overview.md @@ -11,7 +11,7 @@ and assembles a single MkDocs site from all available material. | `lib` | GSDFC docstrings | `docs/lib/**` rendered markdown | | `api` | OpenAPI JSON spec | `docs/api/**` rendered markdown | | `wiki` | Hand-written markdown | `docs/wiki/**` (unchanged) | -| `mcp` | Griffe + renderers | `docs/mcp/**` structured files | +| `mcp` | GSDFC docstrings + renderers | `docs/mcp/**` structured JSON | ## Combined build @@ -22,4 +22,10 @@ One `mkdocs.yml` and one MkDocs build serve all kinds: 3. The wiki `index.md` becomes the site `Home`. Hand-written wiki content is never overwritten or regenerated — only its -navigation is derived automatically. \ No newline at end of file +navigation is derived automatically. + +## MCP bundle + +`docs/mcp/**` is a self-contained, machine-readable reference generated from +docforge's own GSDFC docstrings. `doc-forge serve --mcp --module docforge` +serves it over MCP. See the [MCP Guide](05_development/04_mcp_guide.md). \ No newline at end of file diff --git a/docs/wiki/02_architecture.md b/docs/wiki/02_architecture.md index 48b4f50..36dd93f 100644 --- a/docs/wiki/02_architecture.md +++ b/docs/wiki/02_architecture.md @@ -7,8 +7,7 @@ bottom through the CLI. The `docforge/loaders` package wraps `griffe` to extract modules, functions, classes, and Google-style docstring sections. Loaded data is normalized into -the object model under `docforge/models` (`Module`, `Object`, `Project`, -`Field`). +the object model under `docforge/models` (`Project`, `Module`, `DocObject`). ## Navigation @@ -23,6 +22,13 @@ file structure via `build_wiki_nav`. - `MkDocsRenderer` → `docs/lib/**` reference markdown - `MCPRenderer` → `docs/mcp/**` structured documentation +## Servers + +`docforge/servers` serves generated artifacts over live protocols: + +- `MCPServer` → serves a pre-generated `docs/mcp/**` bundle through MCP + resources (`docs://index`, `docs://nav`, `docs://modules/{module}`) + ## CLI `docforge/cli` wires it all together: diff --git a/docs/wiki/03_conventions.md b/docs/wiki/03_conventions.md index de07f98..1ab2ec4 100644 --- a/docs/wiki/03_conventions.md +++ b/docs/wiki/03_conventions.md @@ -6,6 +6,19 @@ All documented source uses the Google-Styled Doc-Forge Convention (GSDFC): `Args:`, `Returns:`, `Raises:`, and `Attributes:` sections with properly typed signatures. +The authoritative GSDFC specification lives in the `docforge/__init__.py` +package docstring, which is exported verbatim into +`docs/mcp/modules/docforge.json`, so the MCP bundle is self-documenting. + +Key rules: + +- Use parenthesized types in prose entries (`name (Type):`) that match the + signature types. +- Use `# Summary`, `# Examples`, and `# Notes` sections at module level. +- Use `Args:`, `Returns:`, `Raises:`, `Yields:`, `Notes:`, and `Example:` + sections at function and method level. +- Always update the matching `.pyi` stub alongside the `.py` implementation. + ## `.pyi` stubs Every module ships a matching `.pyi` stub kept in sync with the `.py` @@ -14,7 +27,7 @@ implementation. When signatures change, update both files. ## Wiki pages - Hand-written markdown lives in `docs/wiki/**` and is never generated. -- File names use a numeric prefix: `01_overview.md`, `02_components.md`. +- File names use a numeric prefix: `01_overview.md`, `02_architecture.md`. - Nested directories become nested navigation groups: `05_development/01_environment.md` → group *Development*. - `index.md` is the site `Home` at the root, and a section root inside a diff --git a/docs/wiki/04_iterative_workflow.md b/docs/wiki/04_iterative_workflow.md index f0f1d46..aec8108 100644 --- a/docs/wiki/04_iterative_workflow.md +++ b/docs/wiki/04_iterative_workflow.md @@ -8,11 +8,14 @@ A docs build runs through the CLI in a single pass. # Library reference only doc-forge build --mkdocs --module docforge -# Wik + library combined (single MkDocs build) +# Wiki + library combined (single MkDocs build) doc-forge build --wiki --mkdocs --module docforge # Wiki only — no module required doc-forge build --wiki --site-name docforge + +# MCP structured bundle +doc-forge build --mcp --module docforge ``` ## What a combined build does @@ -29,5 +32,12 @@ doc-forge build --wiki --site-name docforge ```bash doc-forge build --wiki --mkdocs --module docforge -doc-forge serve --mkdocs-yml mkdocs.yml +doc-forge serve --mkdocs --mkdocs-yml mkdocs.yml +``` + +## Serve the MCP bundle + +```bash +doc-forge build --mcp --module docforge +doc-forge serve --mcp --module docforge ``` \ No newline at end of file diff --git a/docs/wiki/05_development/01_environment.md b/docs/wiki/05_development/01_environment.md index 2926182..7c55380 100644 --- a/docs/wiki/05_development/01_environment.md +++ b/docs/wiki/05_development/01_environment.md @@ -8,7 +8,7 @@ python -m venv .venv pip install -e . ``` -Requires Python 3.11+. +Requires Python 3.10+ (per `pyproject.toml`). ## Dependencies @@ -17,4 +17,5 @@ Development extras include: - `pytest`, `pytest-cov` — test suite and coverage - `ruff` — lint and format checking - `black` — auto-formatting -- `mypy` — strict typing checks \ No newline at end of file +- `mypy` — strict typing checks +- `pydoclint` — docstring ↔ signature consistency checks \ No newline at end of file diff --git a/docs/wiki/05_development/02_quality_gates.md b/docs/wiki/05_development/02_quality_gates.md index d0d2716..8966aea 100644 --- a/docs/wiki/05_development/02_quality_gates.md +++ b/docs/wiki/05_development/02_quality_gates.md @@ -7,6 +7,7 @@ Run all checks before pushing: .venv\Scripts\python.exe -m ruff check docforge tests .venv\Scripts\python.exe -m black --check docforge tests .venv\Scripts\python.exe -m mypy docforge +.venv\Scripts\pydoclint.exe docforge ``` ## Test layout diff --git a/docs/wiki/05_development/03_gsdfc_guide.md b/docs/wiki/05_development/03_gsdfc_guide.md new file mode 100644 index 0000000..90d01ab --- /dev/null +++ b/docs/wiki/05_development/03_gsdfc_guide.md @@ -0,0 +1,108 @@ +# GSDFC Docstring Guide + +This page is the practical companion to the authoritative GSDFC specification +in the `docforge/__init__.py` package docstring. It describes how to write +docstrings that render correctly in MkDocs and stay machine-parseable by +doc-forge, MkDocs, and MCP clients. + +## Overview + +- Docstrings are the single source of truth. +- `doc-forge` compiles docstrings but never rewrites them. +- Every public symbol should have a complete, accurate docstring. +- Type hints live in signatures; prose entries repeat the type in + parentheses and must match the signature. + +## Module docstrings + +Modules use Markdown headings and `---` separators. + +Recommended sections: + +- `# Summary` — what the subsystem does +- `# Examples` — a representative usage snippet +- `# Notes` — guarantees, lifecycle, and thread-safety notes + +## Class docstrings + +Recommended sections, in order: + +- summary line describing responsibility +- `Attributes:` — instance attributes with `name (Type):` entries +- `Notes:` — grouped subsections such as **Guarantees**, **Lifecycle** +- `Example:` — indented `python` code block + +## Function and method docstrings + +Recommended section order: + +1. `Args:` +2. `Returns:` +3. `Raises:` +4. `Yields:` +5. `Notes:` +6. `Example:` + +Formatting rules: + +- `Args:` entries are `name (Type):` followed by an indented description. +- `Returns:` entries are `Type:` followed by an indented description. +- `Raises:` entries are `ExceptionType:` followed by an indented condition. +- `Yields:` replaces `Returns:` for generators. +- Summaries are written in the imperative mood. +- Fenced `python` blocks are allowed inside `Example:` sections, indented + four spaces. + +## Property docstrings + +Properties document their return values with a `Returns:` section and, when +meaningful, an `Example:`. + +## Example + +```python +def process(foo: Foo, multiplier: int) -> int: + """Process a Foo instance. + + Args: + foo (Foo): + Foo instance to process. + + multiplier (int): + Value used to scale foo. + + Returns: + int: + Processed result. + + Raises: + ValueError: + If multiplier is negative. + + Example: + Process foo: + + ```python + foo = Foo("example", value=10) + result = process(foo, multiplier=2) + print(result) + ``` + """ +``` + +## Keeping stubs in sync + +Every `.py` module ships a matching `.pyi` stub. When a signature or a public +symbol changes, update both files. Signature annotations in the stub must +match the implementation. + +## Enforcement + +`pydoclint` (Google style) runs in CI and verifies that `Args:`/`Returns:` +sections match function signatures, including types. + +- `allow-init-docstring = true` — `__init__` docstrings are allowed. +- `skip-checking-raises = true` — `Raises:` sections are descriptive and are + not required to map to literal `raise` statements. +- `check-class-attributes = false` — `Attributes:` sections document instance + attributes without class-level annotations. \ No newline at end of file diff --git a/docs/wiki/05_development/04_mcp_guide.md b/docs/wiki/05_development/04_mcp_guide.md new file mode 100644 index 0000000..6a2dbdf --- /dev/null +++ b/docs/wiki/05_development/04_mcp_guide.md @@ -0,0 +1,51 @@ +# MCP Guide + +Doc-forge can export a machine-readable **MCP bundle** from a project's +GSDFC docstrings and serve that bundle over the Model Context Protocol (MCP). +The bundle is self-contained: readers can derive the full API reference — +signatures, docstrings, and structure — for the documented project. + +## Building the bundle + +```bash +doc-forge build --mcp --module docforge +``` + +This writes structured JSON into `docs/mcp/`: + +- `index.json` — project metadata and module count +- `nav.json` — module list with `docs://modules/{module}` resource URIs +- `modules/{dotted.path}.json` — per-module serialized documentation + +## Serving the bundle + +```bash +doc-forge serve --mcp --module docforge +``` + +The `MCPServer` (in `docforge/servers/mcp_server.py`) exposes: + +| Resource | Description | +|----------------------|-----------------------------------| +| `docs://index` | Project metadata | +| `docs://nav` | Navigation structure | +| `docs://modules/{module}` | Individual module documentation | + +The server also registers a single diagnostic tool, `ping`, and is read-only. +Missing resources are returned as structured error dictionaries rather than +exceptions. The default transport is `streamable-http`; `stdio` and `sse` are +supported via `MCPServer.run`. + +## Bundle contents + +Each module resource contains: + +- `path` — dotted module path +- `docstring` — the raw GSDFC module docstring +- `objects` — a recursive mapping of public symbols with `name`, `kind`, + `path`, `signature`, and `docstring`, plus nested `members` + +Because the bundle is generated from docstrings, the quality of the bundle +equals the quality of the project's GSDFC docstrings. For docforge itself, +the GSDFC specification is carried in `modules/docforge.json` via the +`docforge/__init__.py` package docstring, making the bundle self-documenting. \ No newline at end of file diff --git a/docs/wiki/index.md b/docs/wiki/index.md index d581212..dcae17a 100644 --- a/docs/wiki/index.md +++ b/docs/wiki/index.md @@ -22,17 +22,20 @@ OpenAPI-based API docs. | Section | Description | |----------------------------------------------| -------------------------------------------------- | | [Overview](01_overview.md) | What docforge is and how it fits the pipeline | -| [Architecture](02_architecture.md) | Loaders, models, nav, renderers, CLI | +| [Architecture](02_architecture.md) | Loaders, models, nav, renderers, CLI, servers | | [Conventions](03_conventions.md) | GSDFC, `.pyi` stubs, and template conventions | | [Iterative Workflow](04_iterative_workflow.md) | How a docs build runs end to end | | [Development](05_development/01_environment.md) | Environment setup and quality gates | +| [Docstring Guide](05_development/03_gsdfc_guide.md) | How to write GSDFC-conformant docstrings | +| [MCP Guide](05_development/04_mcp_guide.md) | Building, serving, and consuming the MCP bundle | --- ## 🔗 Related Resources -- **Source Code:** `C:\Users\vishe\WorkSpace\code\aetos\doc-forge` +- **Source Code:** the `doc-forge` repository - **Wiki Kind:** hand-written content lives in `docs/wiki/` +- **MCP Bundle:** generated by `doc-forge build --mcp --module docforge` into `docs/mcp/` --- diff --git a/mkdocs.yml b/mkdocs.yml index 917808d..bf187fa 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -77,6 +77,8 @@ nav: - Development: - Environment: wiki/05_development/01_environment.md - Quality Gates: wiki/05_development/02_quality_gates.md + - Gsdfc Guide: wiki/05_development/03_gsdfc_guide.md + - Mcp Guide: wiki/05_development/04_mcp_guide.md - Loaders: - lib/loaders/index.md - lib/loaders/griffe_loader.md diff --git a/pyproject.toml b/pyproject.toml index 6e02ea3..c5c4768 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -83,6 +83,7 @@ dev = [ "black>=23.0.0", "ruff>=0.3.0", "mypy>=1.8.0", + "pydoclint>=0.9.1", "build>=1.0.0", "twine>=4.0.0", "pre-commit>=3.4.0", @@ -188,6 +189,14 @@ module = [ ignore_missing_imports = true +[tool.pydoclint] +style = "google" +exclude = '\.pyi$|tests/' +allow-init-docstring = true +skip-checking-raises = true +check-class-attributes = false + + [tool.coverage.run] source = ["docforge"] omit = [