aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: bring docforge docstrings and wiki to GSDFC standard

Browse Source 
- 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
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-09-12 13:12:51 +05:30
parent 8c6c46caf2
commit 582b6809a0
82 changed files with 1467 additions and 703 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
README.md
View File

@@ -42,6 +42,18 @@ doc-forge build --mcp --module my_package
doc-forge build --mcp --mkdocs --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: ## Serve MkDocs locally:
```bash ```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 **Markdown headings** at package and module level.
- Use **Google-style structured sections** at class, function, and method 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. - Write summaries in imperative form.
- Sections are separated by `---` - Sections are separated by `---`
@@ -190,7 +204,10 @@ Example:
engine.run() 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.
--- ---

21
docforge/__init__.py
View File

@@ -41,6 +41,18 @@ doc-forge build --mcp --module my_package
doc-forge build --mcp --mkdocs --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: ## Serve MkDocs locally:
```bash ```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 **Markdown headings** at package and module level.
- Use **Google-style structured sections** at class, function, and method 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. - Write summaries in imperative form.
- Sections are separated by `---` - Sections are separated by `---`
@@ -189,7 +203,10 @@ Example:
engine.run() 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.
--- ---

12
docforge/cli/api_utils.py
View File

@@ -35,7 +35,8 @@ def load_openapi_spec(spec_path: Path) -> dict:
Load and validate an OpenAPI specification from a JSON file. Load and validate an OpenAPI specification from a JSON file.
Args: Args:
spec_path: Path to the OpenAPI JSON specification file. spec_path (Path):
Path to the OpenAPI JSON specification file.
Returns: Returns:
dict: dict:
@@ -68,7 +69,8 @@ def derive_metadata(spec: dict) -> OpenAPIMetadata:
Derive MkDocs site metadata from an OpenAPI spec ``info`` block. Derive MkDocs site metadata from an OpenAPI spec ``info`` block.
Args: Args:
spec: Parsed OpenAPI specification. spec (dict):
Parsed OpenAPI specification.
Returns: Returns:
OpenAPIMetadata: 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. an ``index.md`` embedding the swagger UI is generated alongside it.
Args: Args:
spec: Parsed OpenAPI specification. spec (dict):
docs_dir: Directory (for example ``docs/api``) where the swagger Parsed OpenAPI specification.
docs_dir (Path):
Directory (for example ``docs/api``) where the swagger
sources are written. sources are written.
""" """
docs_dir.mkdir(parents=True, exist_ok=True) docs_dir.mkdir(parents=True, exist_ok=True)

40
docforge/cli/commands.py
View File

@@ -4,6 +4,15 @@
Command definitions for the doc-forge CLI. Command definitions for the doc-forge CLI.
Provides the CLI structure using Click, including build, serve, and tree commands. 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 from pathlib import Path
@@ -12,6 +21,7 @@ import click
from docforge.cli import api_utils, mcp_utils, mkdocs_utils from docforge.cli import api_utils, mcp_utils, mkdocs_utils
from docforge.loaders import GriffeLoader from docforge.loaders import GriffeLoader
from docforge.models import DocObject
@click.group() @click.group()
@@ -99,9 +109,9 @@ def build(
""" """
Build documentation artifacts. Build documentation artifacts.
This command performs the full documentation build pipeline: This command runs the full documentation pipeline: it loads Python
style of the selected platform, generates renderer-specific modules, generates renderer-specific documentation sources, and
documentation sources, and optionally builds the final output. optionally builds or serves the final output.
Depending on the selected options, the build can target: Depending on the selected options, the build can target:
@@ -110,6 +120,12 @@ def build(
- Hand-written wiki pages included in the MkDocs site - Hand-written wiki pages included in the MkDocs site
- MCP structured documentation resources - 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: Args:
mcp (bool): mcp (bool):
Enable MCP documentation generation. Enable MCP documentation generation.
@@ -126,16 +142,16 @@ def build(
module_is_source (bool): module_is_source (bool):
Treat the specified module directory as the project root. Treat the specified module directory as the project root.
module (Optional[str]): module (str | None):
Python module import path to document. Python module import path to document.
openapi_spec (Optional[Path]): openapi_spec (Path | None):
Path to the OpenAPI JSON specification used for API docs. Path to the OpenAPI JSON specification used for API docs.
project_name (Optional[str]): project_name (str | None):
Optional override for the project name. Optional override for the project name.
site_name (Optional[str]): site_name (str | None):
Display name for the MkDocs site. Display name for the MkDocs site.
docs_dir (Path): docs_dir (Path):
@@ -147,7 +163,7 @@ def build(
nav_file (Path): nav_file (Path):
Path to the navigation specification file. Path to the navigation specification file.
template (Optional[Path]): template (Path | None):
Optional custom MkDocs configuration template. Optional custom MkDocs configuration template.
mkdocs_yml (Path): mkdocs_yml (Path):
@@ -282,7 +298,7 @@ def serve(
mkdocs (bool): mkdocs (bool):
Serve the MkDocs development site. Serve the MkDocs development site.
module (Optional[str]): module (str | None):
Python module import path to serve via MCP. Python module import path to serve via MCP.
mkdocs_yml (Path): mkdocs_yml (Path):
@@ -333,7 +349,7 @@ def tree(
module (str): module (str):
Python module import path to introspect. Python module import path to introspect.
project_name (Optional[str]): project_name (str | None):
Optional name to display as the project root. Optional name to display as the project root.
""" """
loader = GriffeLoader() loader = GriffeLoader()
@@ -347,7 +363,7 @@ def tree(
_print_object(obj, indent="│ ") _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. 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. and prints each object with indentation to represent hierarchy.
Args: Args:
obj: obj (DocObject):
Documentation object to print. Documentation object to print.
indent (str): indent (str):

5
docforge/cli/commands.pyi
View File

@@ -1,8 +1,9 @@
from pathlib import Path from pathlib import Path
from typing import Any
from click.core import Group from click.core import Group
from docforge.models import DocObject
cli: Group cli: Group
def build( def build(
@@ -33,4 +34,4 @@ def tree(
module: str, module: str,
project_name: str | None, project_name: str | None,
) -> None: ... ) -> None: ...
def _print_object(obj: Any, indent: str) -> None: ... def _print_object(obj: DocObject, indent: str) -> None: ...

12
docforge/cli/mcp_utils.py
View File

@@ -2,6 +2,16 @@
# Summary # Summary
Utilities for working with MCP in the doc-forge CLI. 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 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 Python module import path used as the entry point for
documentation generation. documentation generation.
project_name (Optional[str]): project_name (str | None):
Optional override for the project name used in generated Optional override for the project name used in generated
documentation metadata. documentation metadata.

46
docforge/cli/mkdocs_utils.py
View File

@@ -2,6 +2,15 @@
# Summary # Summary
Utilities for working with MkDocs in the doc-forge CLI. 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 import os
@@ -44,14 +53,14 @@ def generate_sources(
docs_dir (Path): docs_dir (Path):
Directory where the generated Markdown files will be written. 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. 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 If True, treat the specified module directory as the project root
rather than a nested module. rather than a nested module.
readme_dir (Optional[Path]): readme_dir (Path | None):
Directory where the generated README.md should be written. If not Directory where the generated README.md should be written. If not
provided, defaults to the parent of ``docs_dir``. provided, defaults to the parent of ``docs_dir``.
""" """
@@ -105,7 +114,7 @@ def generate_config(
nav_file (Path): nav_file (Path):
Path to the `docforge.nav.yml` navigation specification. Path to the `docforge.nav.yml` navigation specification.
template (Optional[Path]): template (Path | None):
Optional path to a fully custom MkDocs configuration template. Optional path to a fully custom MkDocs configuration template.
If not provided, built-in templates are merged; the provided If not provided, built-in templates are merged; the provided
template replaces the built-in templates entirely. template replaces the built-in templates entirely.
@@ -116,19 +125,19 @@ def generate_config(
site_name (str): site_name (str):
Display name for the generated documentation site. Display name for the generated documentation site.
modes (Optional[Iterable[str]]): modes (Iterable[str] | None):
Documentation modes to enable. Each mode contributes its own Documentation modes to enable. Each mode contributes its own
built-in template fragment (for example ``lib``, ``api``, or built-in template fragment (for example ``lib``, ``api``, or
``wiki``), merged on top of the shared ``mkdocs.common.yml`` ``wiki``), merged on top of the shared ``mkdocs.common.yml``
template. template.
site_description (Optional[str]): site_description (str | None):
Optional site description written into the configuration. Optional site description written into the configuration.
site_author (Optional[str]): site_author (str | None):
Optional site author written into the configuration. 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 Optional path to a hand-written wiki directory (for example
``docs/wiki``). When provided, the site navigation is derived ``docs/wiki``). When provided, the site navigation is derived
from the wiki file structure and placed before the navigation 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 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 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: Args:
template (Optional[Path]): template (Path | None):
Optional fully custom template that replaces the built-ins. 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. Documentation modes whose template fragments should be merged.
Returns: Returns:
@@ -237,7 +246,8 @@ def _item_name(item: object) -> str:
first key. This is used to deduplicate plugin and extension lists. first key. This is used to deduplicate plugin and extension lists.
Args: 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: Returns:
str: str:
@@ -253,8 +263,10 @@ def _merge_list(base: list, added: list) -> list:
Merge two lists, preserving order and dropping duplicates by name. Merge two lists, preserving order and dropping duplicates by name.
Args: Args:
base: Existing list entries. base (list):
added: Entries to append when not already present. Existing list entries.
added (list):
Entries to append when not already present.
Returns: Returns:
list: list:
@@ -279,8 +291,10 @@ def _deep_merge(base: dict, part: dict) -> dict:
the fragment override the base. the fragment override the base.
Args: Args:
base: Configuration being built up. base (dict):
part: Template fragment to merge into the base. Configuration being built up.
part (dict):
Template fragment to merge into the base.
Returns: Returns:
dict: dict:

43
docforge/loaders/griffe_loader.py
View File

@@ -6,6 +6,14 @@ Utilities for loading and introspecting Python modules using Griffe.
This module provides the `GriffeLoader` class and helper utilities used to This module provides the `GriffeLoader` class and helper utilities used to
discover Python modules, introspect their structure, and convert the results discover Python modules, introspect their structure, and convert the results
into doc-forge documentation models. 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 import logging
@@ -46,12 +54,12 @@ def discover_module_paths(
module_name (str): module_name (str):
Top-level package name to discover modules from. 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 Root directory used to resolve module paths. If not provided, the
current working directory is used. current working directory is used.
Returns: Returns:
List[str]: list[str]:
A sorted list of unique dotted module import paths. A sorted list of unique dotted module import paths.
Raises: Raises:
@@ -88,6 +96,10 @@ class GriffeLoader:
This loader uses the Griffe introspection engine to analyze Python source This loader uses the Griffe introspection engine to analyze Python source
code and transform the extracted information into `Project`, `Module`, code and transform the extracted information into `Project`, `Module`,
and `DocObject` instances used by doc-forge. and `DocObject` instances used by doc-forge.
Attributes:
_loader (_GriffeLoader):
Internal Griffe loader with dedicated module and line collections.
""" """
def __init__(self) -> None: def __init__(self) -> None:
@@ -106,7 +118,7 @@ class GriffeLoader:
self, self,
module_paths: list[str], module_paths: list[str],
project_name: str | None = None, project_name: str | None = None,
skip_import_errors: bool = None, skip_import_errors: bool | None = None,
) -> Project: ) -> Project:
""" """
Load multiple modules and assemble them into a Project model. Load multiple modules and assemble them into a Project model.
@@ -116,14 +128,14 @@ class GriffeLoader:
object. object.
Args: Args:
module_paths (List[str]): module_paths (list[str]):
List of dotted module import paths to load. 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 Optional override for the project name. Defaults to the top-level
name of the first module. 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. If True, modules that fail to load will be skipped instead of raising an error.
Returns: Returns:
@@ -172,6 +184,21 @@ class GriffeLoader:
Returns: Returns:
Module: Module:
A populated `Module` instance. 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) self._loader.load(path)
griffe_module = self._loader.modules_collection[path] griffe_module = self._loader.modules_collection[path]
@@ -260,7 +287,7 @@ class GriffeLoader:
Griffe object to inspect. Griffe object to inspect.
Returns: Returns:
Optional[str]: str | None:
The raw docstring text if available, otherwise `None`. The raw docstring text if available, otherwise `None`.
""" """
try: try:
@@ -277,7 +304,7 @@ class GriffeLoader:
Griffe object to inspect. Griffe object to inspect.
Returns: Returns:
Optional[str]: str | None:
String representation of the object's signature if available, otherwise `None`. String representation of the object's signature if available, otherwise `None`.
""" """
try: try:

3
docforge/loaders/griffe_loader.pyi
View File

@@ -11,6 +11,7 @@ class GriffeLoader:
"""Griffe-based introspection loaders. """Griffe-based introspection loaders.
This is the only supported introspection backend in doc-forge. This is the only supported introspection backend in doc-forge.
Converts Griffe results into `Project`, `Module`, and `DocObject` models.
""" """
def __init__(self) -> None: ... def __init__(self) -> None: ...
@@ -18,7 +19,7 @@ class GriffeLoader:
self, self,
module_paths: list[str], module_paths: list[str],
project_name: str | None = ..., project_name: str | None = ...,
skip_import_errors: bool = ..., skip_import_errors: bool | None = ...,
) -> Project: ) -> Project:
"""Load a documentation project from Python modules.""" """Load a documentation project from Python modules."""

13
docforge/models/module.py
View File

@@ -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 model. A `Module` acts as a container for top-level documented objects
(classes, functions, variables, and other members) discovered during (classes, functions, variables, and other members) discovered during
introspection. introspection.
---
Notes:
- Only public members are stored; private names are filtered by the loader.
---
""" """
from collections.abc import Iterable from collections.abc import Iterable
@@ -26,10 +33,10 @@ class Module:
path (str): path (str):
Dotted import path of the module. Dotted import path of the module.
docstring (Optional[str]): docstring (str | None):
Module-level documentation string, if present. Module-level documentation string, if present.
members (Dict[str, DocObject]): members (dict[str, DocObject]):
Mapping of object names to their corresponding `DocObject` representations. Mapping of object names to their corresponding `DocObject` representations.
""" """
@@ -45,7 +52,7 @@ class Module:
path (str): path (str):
Dotted import path identifying the module. Dotted import path identifying the module.
docstring (Optional[str]): docstring (str | None):
Module-level documentation text, if available. Module-level documentation text, if available.
""" """
self.path = path self.path = path

21
docforge/models/object.py
View File

@@ -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 the doc-forge documentation model. Each `DocObject` represents a Python
entity such as a class, function, method, or attribute, and may contain nested entity such as a class, function, method, or attribute, and may contain nested
members that form a hierarchical documentation structure. 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 from collections.abc import Iterable
@@ -30,13 +38,13 @@ class DocObject:
path (str): path (str):
Fully qualified dotted path to the object. Fully qualified dotted path to the object.
signature (Optional[str]): signature (str | None):
Callable signature if the object represents a callable. Callable signature if the object represents a callable.
docstring (Optional[str]): docstring (str | None):
Raw docstring text extracted from the source code. Raw docstring text extracted from the source code.
members (Dict[str, DocObject]): members (dict[str, DocObject]):
Mapping of member names to child `DocObject` instances. Mapping of member names to child `DocObject` instances.
""" """
@@ -61,10 +69,10 @@ class DocObject:
path (str): path (str):
Fully qualified dotted path of the object. Fully qualified dotted path of the object.
signature (Optional[str]): signature (str | None):
Callable signature if applicable. Callable signature if applicable.
docstring (Optional[str]): docstring (str | None):
Documentation string associated with the object. Documentation string associated with the object.
""" """
self.name = name self.name = name
@@ -82,7 +90,8 @@ class DocObject:
nested objects to their parent containers. nested objects to their parent containers.
Args: Args:
obj: Documentation object to add as a member. obj (DocObject):
Documentation object to add as a member.
""" """
self.members[obj.name] = obj self.members[obj.name] = obj

18
docforge/models/project.py
View File

@@ -6,6 +6,14 @@ Documentation model representing a project.
This module defines the `Project` class, the top-level container used by This module defines the `Project` class, the top-level container used by
doc-forge to represent a documented codebase. A `Project` aggregates multiple doc-forge to represent a documented codebase. A `Project` aggregates multiple
modules and provides access to them through a unified interface. 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 from collections.abc import Iterable
@@ -24,7 +32,7 @@ class Project:
name (str): name (str):
Name of the project. Name of the project.
modules (Dict[str, Module]): modules (dict[str, Module]):
Mapping of module paths to `Module` instances. Mapping of module paths to `Module` instances.
""" """
@@ -35,6 +43,14 @@ class Project:
Args: Args:
name (str): name (str):
Name used to identify the documentation project. 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.name = name
self.modules: dict[str, Module] = {} self.modules: dict[str, Module] = {}

27
docforge/nav/mkdocs.py
View File

@@ -4,6 +4,14 @@ MkDocs navigation emitter.
This module provides the ``MkDocsNavEmitter`` class, which converts a This module provides the ``MkDocsNavEmitter`` class, which converts a
``ResolvedNav`` instance into the navigation structure required by the ``ResolvedNav`` instance into the navigation structure required by the
MkDocs ``nav`` configuration. 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 from pathlib import Path
@@ -25,13 +33,15 @@ class MkDocsNavEmitter:
Generate a navigation structure for ``mkdocs.yml``. Generate a navigation structure for ``mkdocs.yml``.
Args: Args:
nav: Resolved navigation data describing documentation groups nav (ResolvedNav):
Resolved navigation data describing documentation groups
and their associated Markdown files. and their associated Markdown files.
Returns: Returns:
A list of dictionaries representing the MkDocs navigation layout. list[dict[str, Any]]:
Each dictionary maps a navigation label to a page or a list of A list of dictionaries representing the MkDocs navigation layout.
pages. Each dictionary maps a navigation label to a page or a list of
pages.
""" """
result: list[dict[str, Any]] = [] result: list[dict[str, Any]] = []
@@ -59,11 +69,14 @@ class MkDocsNavEmitter:
resulting path is relative to the documentation root. resulting path is relative to the documentation root.
Args: Args:
path: Filesystem path to convert. path (Path):
docs_root: Root directory of the documentation sources. Filesystem path to convert.
docs_root (Path | None):
Root directory of the documentation sources.
Returns: 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(): if docs_root and path.is_absolute():
try: try:

38
docforge/nav/resolver.py
View File

@@ -3,6 +3,14 @@ Navigation resolution utilities.
This module resolves a ``NavSpec`` against the filesystem by expanding glob This module resolves a ``NavSpec`` against the filesystem by expanding glob
patterns and validating that referenced documentation files exist. 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 import glob
@@ -35,9 +43,12 @@ class ResolvedNav:
Initialize a ResolvedNav instance. Initialize a ResolvedNav instance.
Args: Args:
home: Relative path to the home page within the documentation root. home (str | None):
groups: Mapping of group titles to resolved documentation file paths. Relative path to the home page within the documentation root.
docs_root: Root directory of the documentation source files. 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.home = home
self.groups = groups self.groups = groups
@@ -47,8 +58,10 @@ class ResolvedNav:
""" """
Iterate over all files referenced by the navigation structure. Iterate over all files referenced by the navigation structure.
Returns: Yields:
An iterable of ``Path`` objects representing documentation files. Path:
A documentation file referenced by the navigation, including
the home page when defined.
Raises: Raises:
RuntimeError: If the home page is defined but the documentation 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. that referenced documentation files exist within the documentation root.
Args: Args:
spec: Navigation specification describing documentation layout. spec (NavSpec):
docs_root: Root directory containing documentation Markdown files. Navigation specification describing documentation layout.
docs_root (Path):
Root directory containing documentation Markdown files.
Returns: Returns:
A ``ResolvedNav`` instance containing validated navigation paths. ResolvedNav:
A `ResolvedNav` instance containing validated navigation paths.
Raises: Raises:
FileNotFoundError: If the documentation root does not exist or a 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. Resolve a glob pattern relative to the documentation root.
Args: Args:
pattern: Glob pattern used to match documentation files. pattern (str):
Glob pattern used to match documentation files.
Returns: Returns:
A sorted list of matching ``Path`` objects. list[Path]:
A sorted list of matching `Path` objects.
Raises: Raises:
FileNotFoundError: If the pattern does not match any files. FileNotFoundError: If the pattern does not match any files.

39
docforge/nav/spec.py
View File

@@ -4,8 +4,19 @@ Navigation specification model.
This module defines the ``NavSpec`` class, which represents the navigation This module defines the ``NavSpec`` class, which represents the navigation
structure defined by the user in the doc-forge navigation specification structure defined by the user in the doc-forge navigation specification
(typically ``docforge.nav.yml``). (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 from pathlib import Path
import yaml import yaml
@@ -38,10 +49,13 @@ class NavSpec:
Initialize a NavSpec instance. Initialize a NavSpec instance.
Args: Args:
home: Relative path to the home document. home (str | None):
groups: Mapping of group names to lists of path patterns Relative path to the home document.
groups (dict[str, list[str]]):
Mapping of group names to lists of path patterns
(glob expressions). (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. generated MkDocs configuration.
""" """
self.home = home self.home = home
@@ -49,15 +63,17 @@ class NavSpec:
self.icon = icon self.icon = icon
@classmethod @classmethod
def load(cls, path: Path) -> "NavSpec": def load(cls, path: Path) -> NavSpec:
""" """
Load a navigation specification from a YAML file. Load a navigation specification from a YAML file.
Args: Args:
path: Filesystem path to the navigation specification file. path (Path):
Filesystem path to the navigation specification file.
Returns: Returns:
A ``NavSpec`` instance representing the parsed configuration. NavSpec:
A ``NavSpec`` instance representing the parsed configuration.
Raises: Raises:
FileNotFoundError: If the specified file does not exist. FileNotFoundError: If the specified file does not exist.
@@ -105,8 +121,9 @@ class NavSpec:
Return all path patterns referenced by the specification. Return all path patterns referenced by the specification.
Returns: Returns:
A list containing the home document (if defined) and all list[str]:
group pattern entries. A list containing the home document (if defined) and all
group pattern entries.
""" """
patterns: list[str] = [] patterns: list[str] = []
@@ -127,10 +144,12 @@ def load_nav_spec(path: Path) -> NavSpec:
corresponding ``NavSpec`` instance. corresponding ``NavSpec`` instance.
Args: Args:
path: Path to the navigation specification file. path (Path):
Path to the navigation specification file.
Returns: Returns:
A ``NavSpec`` instance representing the parsed specification. NavSpec:
A ``NavSpec`` instance representing the parsed specification.
Raises: Raises:
FileNotFoundError: If the specification file does not exist. FileNotFoundError: If the specification file does not exist.

14
docforge/nav/wiki.py
View File

@@ -20,6 +20,7 @@ modified by doc-forge; only the navigation layout is inferred.
""" """
import re import re
from collections.abc import Callable
from pathlib import Path from pathlib import Path
from typing import Any 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``. Path to the hand-written wiki directory, for example ``docs/wiki``.
Returns: Returns:
List[Dict[str, Any]]: list[dict[str, Any]]:
Navigation entries compatible with the MkDocs ``nav`` configuration. Navigation entries compatible with the MkDocs ``nav`` configuration.
The list is empty if the wiki contains no Markdown files. 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 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. 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): base_dir (Path):
Directory whose children are rendered. Directory whose children are rendered.
rel: rel (Callable[[Path], str]):
Callable converting a wiki file path into a docs-relative path. Callable converting a wiki file path into a docs-relative path.
Returns: Returns:
List[Dict[str, Any]]: list[dict[str, Any]]:
Navigation entries for ``base_dir`` in natural sort order. Navigation entries for ``base_dir`` in natural sort order.
""" """
children = sorted( children = sorted(
@@ -152,7 +156,7 @@ def _natural_key(name: str) -> list[object]:
Filename or directory name to key. Filename or directory name to key.
Returns: Returns:
List[object]: list[object]:
Mixed list of lowercased strings and integers used for sorting. Mixed list of lowercased strings and integers used for sorting.
""" """
return [ return [

32
docforge/nav/wiki.pyi
View File

@@ -1,3 +1,4 @@
from collections.abc import Callable
from pathlib import Path from pathlib import Path
from typing import Any 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. Derive an MkDocs navigation block from a wiki directory.
Args:
wiki_dir (Path):
Path to the hand-written wiki directory.
Returns: Returns:
Wiki navigation entries compatible with the MkDocs list[dict[str, Any]]:
`nav` configuration. Wiki navigation entries compatible with the MkDocs `nav`
configuration.
Raises: 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.
""" """
... ...

8
docforge/renderers/mcp_renderer.py
View File

@@ -49,7 +49,7 @@ class MCPRenderer:
nav.append( nav.append(
{ {
"module": module.path, "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. Module instance to convert.
Returns: Returns:
Dict: dict:
Dictionary representing the module and its documented objects. Dictionary representing the module and its documented objects.
""" """
data: dict = { data: dict = {
@@ -124,7 +124,7 @@ class MCPRenderer:
Documentation object to convert. Documentation object to convert.
Returns: Returns:
Dict: dict:
Dictionary describing the object and any nested members. Dictionary describing the object and any nested members.
""" """
data: dict = { data: dict = {
@@ -149,7 +149,7 @@ class MCPRenderer:
Serialize data to formatted JSON. Serialize data to formatted JSON.
Args: Args:
data (Dict): data (dict):
Dictionary to serialize. Dictionary to serialize.
Returns: Returns:

19
docforge/renderers/mkdocs_renderer.py
View File

@@ -54,7 +54,7 @@ class MkDocsRenderer:
out_dir (Path): out_dir (Path):
Directory where generated Markdown files will be written. 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 If True, treat the specified module as the documentation root
rather than nesting it inside a folder. rather than nesting it inside a folder.
""" """
@@ -87,11 +87,10 @@ class MkDocsRenderer:
""" """
Generate a `README.md` file from the root module docstring. Generate a `README.md` file from the root module docstring.
Behavior: Notes:
- If `module_is_source` is True, `README.md` is written to the
- If `module_is_source` is True, `README.md` is written to the project project root directory.
root directory. - If False, README generation is currently not implemented.
- If False, README generation is currently not implemented.
Args: Args:
project (Project): project (Project):
@@ -100,10 +99,10 @@ class MkDocsRenderer:
docs_dir (Path): docs_dir (Path):
Directory containing generated documentation sources. 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. 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. Directory where the generated README.md should be written.
Defaults to the parent of `docs_dir`. Defaults to the parent of `docs_dir`.
""" """
@@ -157,7 +156,7 @@ class MkDocsRenderer:
Project model to inspect. Project model to inspect.
Returns: Returns:
Optional[Module]: Module | None:
The root `Module` if found, otherwise `None`. The root `Module` if found, otherwise `None`.
""" """
for module in project.get_all_modules(): for module in project.get_all_modules():
@@ -189,7 +188,7 @@ class MkDocsRenderer:
out_dir (Path): out_dir (Path):
Base directory for generated documentation files. 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. Whether the module acts as the documentation root directory.
""" """

18
docforge/servers/mcp_server.py
View File

@@ -5,6 +5,16 @@ MCP server implementation.
This module defines the `MCPServer` class, which serves pre-generated This module defines the `MCPServer` class, which serves pre-generated
documentation bundles through the Model Context Protocol (MCP). 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 from __future__ import annotations
@@ -22,6 +32,14 @@ class MCPServer:
The server exposes documentation resources and diagnostic tools through The server exposes documentation resources and diagnostic tools through
MCP endpoints backed by JSON files generated by the MCP renderer. 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: def __init__(self, mcp_root: Path, name: str) -> None:

5
docforge/servers/mcp_server.pyi
View File

@@ -4,7 +4,10 @@ from typing import Any, Literal
from mcp.server.fastmcp import FastMCP from mcp.server.fastmcp import FastMCP
class MCPServer: 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 mcp_root: Path
app: FastMCP app: FastMCP

3
docs/lib/docforge/cli/api_utils.md
View File

@@ -1,3 +0,0 @@
# Api Utils
::: docforge.cli.api_utils

3
docs/lib/docforge/cli/commands.md
View File

@@ -1,3 +0,0 @@
# Commands
::: docforge.cli.commands

8
docs/lib/docforge/cli/index.md
View File

@@ -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)

3
docs/lib/docforge/cli/main.md
View File

@@ -1,3 +0,0 @@
# Main
::: docforge.cli.main

3
docs/lib/docforge/cli/mcp_utils.md
View File

@@ -1,3 +0,0 @@
# Mcp Utils
::: docforge.cli.mcp_utils

3
docs/lib/docforge/cli/mkdocs_utils.md
View File

@@ -1,3 +0,0 @@
# Mkdocs Utils
::: docforge.cli.mkdocs_utils

9
docs/lib/docforge/index.md
View File

@@ -1,9 +0,0 @@
# Docforge
::: docforge
- [Cli](cli/)
- [Loaders](loaders/)
- [Models](models/)
- [Nav](nav/)
- [Renderers](renderers/)
- [Servers](servers/)

3
docs/lib/docforge/loaders/griffe_loader.md
View File

@@ -1,3 +0,0 @@
# Griffe Loader
::: docforge.loaders.griffe_loader

4
docs/lib/docforge/loaders/index.md
View File

@@ -1,4 +0,0 @@
# Loaders
::: docforge.loaders
- [Griffe Loader](griffe_loader.md)

6
docs/lib/docforge/models/index.md
View File

@@ -1,6 +0,0 @@
# Models
::: docforge.models
- [Module](module.md)
- [Object](object.md)
- [Project](project.md)

3
docs/lib/docforge/models/module.md
View File

@@ -1,3 +0,0 @@
# Module
::: docforge.models.module

3
docs/lib/docforge/models/object.md
View File

@@ -1,3 +0,0 @@
# Object
::: docforge.models.object

3
docs/lib/docforge/models/project.md
View File

@@ -1,3 +0,0 @@
# Project
::: docforge.models.project

7
docs/lib/docforge/nav/index.md
View File

@@ -1,7 +0,0 @@
# Nav
::: docforge.nav
- [Mkdocs](mkdocs.md)
- [Resolver](resolver.md)
- [Spec](spec.md)
- [Wiki](wiki.md)

3
docs/lib/docforge/nav/mkdocs.md
View File

@@ -1,3 +0,0 @@
# Mkdocs
::: docforge.nav.mkdocs

3
docs/lib/docforge/nav/resolver.md
View File

@@ -1,3 +0,0 @@
# Resolver
::: docforge.nav.resolver

3
docs/lib/docforge/nav/spec.md
View File

@@ -1,3 +0,0 @@
# Spec
::: docforge.nav.spec

3
docs/lib/docforge/renderers/base.md
View File

@@ -1,3 +0,0 @@
# Base
::: docforge.renderers.base

6
docs/lib/docforge/renderers/index.md
View File

@@ -1,6 +0,0 @@
# Renderers
::: docforge.renderers
- [Base](base.md)
- [Mcp Renderer](mcp_renderer.md)
- [Mkdocs Renderer](mkdocs_renderer.md)

3
docs/lib/docforge/renderers/mcp_renderer.md
View File

@@ -1,3 +0,0 @@
# Mcp Renderer
::: docforge.renderers.mcp_renderer

3
docs/lib/docforge/renderers/mkdocs_renderer.md
View File

@@ -1,3 +0,0 @@
# Mkdocs Renderer
::: docforge.renderers.mkdocs_renderer

4
docs/lib/docforge/servers/index.md
View File

@@ -1,4 +0,0 @@
# Servers
::: docforge.servers
- [Mcp Server](mcp_server.md)

3
docs/lib/docforge/servers/mcp_server.md
View File

@@ -1,3 +0,0 @@
# Mcp Server
::: docforge.servers.mcp_server

1
docs/lib/index.md
View File

@@ -1,4 +1,3 @@
# docforge # docforge
::: docforge ::: docforge
- [Docforge](docforge/)

0
docs/lib/docforge/nav/wiki.md → docs/lib/nav/wiki.md
View File

2
docs/mcp/index.json
View File

@@ -1,6 +1,6 @@
{ {
"project": "docforge", "project": "docforge",
"type": "docforge-model", "type": "docforge-model",
"modules_count": 23, "modules_count": 24,
"source": "docforge" "source": "docforge"
} }

12
docs/mcp/modules/docforge.cli.api_utils.json
View File

@@ -73,22 +73,22 @@
"name": "load_openapi_spec", "name": "load_openapi_spec",
"kind": "function", "kind": "function",
"path": "docforge.cli.api_utils.load_openapi_spec", "path": "docforge.cli.api_utils.load_openapi_spec",
"signature": "<bound method Function.signature of Function('load_openapi_spec', 33, 63)>", "signature": "<bound method Function.signature of Function('load_openapi_spec', 33, 64)>",
"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": { "derive_metadata": {
"name": "derive_metadata", "name": "derive_metadata",
"kind": "function", "kind": "function",
"path": "docforge.cli.api_utils.derive_metadata", "path": "docforge.cli.api_utils.derive_metadata",
"signature": "<bound method Function.signature of Function('derive_metadata', 66, 89)>", "signature": "<bound method Function.signature of Function('derive_metadata', 67, 91)>",
"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": { "generate_api_sources": {
"name": "generate_api_sources", "name": "generate_api_sources",
"kind": "function", "kind": "function",
"path": "docforge.cli.api_utils.generate_api_sources", "path": "docforge.cli.api_utils.generate_api_sources",
"signature": "<bound method Function.signature of Function('generate_api_sources', 92, 114)>", "signature": "<bound method Function.signature of Function('generate_api_sources', 94, 118)>",
"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": { "Any": {
"name": "Any", "name": "Any",

150
docs/mcp/modules/docforge.cli.commands.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.cli.commands", "module": "docforge.cli.commands",
"content": { "content": {
"path": "docforge.cli.commands", "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": { "objects": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -95,21 +95,21 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.api_utils.load_openapi_spec", "path": "docforge.cli.commands.api_utils.load_openapi_spec",
"signature": "<bound method Alias.signature of Alias('load_openapi_spec', 'docforge.cli.api_utils.load_openapi_spec')>", "signature": "<bound method Alias.signature of Alias('load_openapi_spec', 'docforge.cli.api_utils.load_openapi_spec')>",
"docstring": "Load and validate an OpenAPI specification from a JSON file.\n\nArgs:\n spec_path: Path 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": { "derive_metadata": {
"name": "derive_metadata", "name": "derive_metadata",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.api_utils.derive_metadata", "path": "docforge.cli.commands.api_utils.derive_metadata",
"signature": "<bound method Alias.signature of Alias('derive_metadata', 'docforge.cli.api_utils.derive_metadata')>", "signature": "<bound method Alias.signature of Alias('derive_metadata', 'docforge.cli.api_utils.derive_metadata')>",
"docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec: 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": { "generate_api_sources": {
"name": "generate_api_sources", "name": "generate_api_sources",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.api_utils.generate_api_sources", "path": "docforge.cli.commands.api_utils.generate_api_sources",
"signature": "<bound method Alias.signature of Alias('generate_api_sources', 'docforge.cli.api_utils.generate_api_sources')>", "signature": "<bound method Alias.signature of Alias('generate_api_sources', 'docforge.cli.api_utils.generate_api_sources')>",
"docstring": "Generate swagger-enabled Markdown sources and the spec copy.\n\nThe specification is written as ``openapi.json`` inside ``docs_dir`` and\nan ``index.md`` embedding the swagger UI is generated alongside it.\n\nArgs:\n spec: 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": { "Any": {
"name": "Any", "name": "Any",
@@ -125,7 +125,7 @@
"kind": "module", "kind": "module",
"path": "docforge.cli.commands.mcp_utils", "path": "docforge.cli.commands.mcp_utils",
"signature": "<bound method Alias.signature of Alias('mcp_utils', 'docforge.cli.mcp_utils')>", "signature": "<bound method Alias.signature of Alias('mcp_utils', 'docforge.cli.mcp_utils')>",
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.", "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": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -146,21 +146,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader", "path": "docforge.cli.commands.mcp_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp_utils.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp_utils.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "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": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, 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": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "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", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.discover_module_paths", "path": "docforge.cli.commands.mcp_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp_utils.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp_utils.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, 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": { "MCPRenderer": {
"name": "MCPRenderer", "name": "MCPRenderer",
@@ -199,7 +199,7 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mcp_utils.MCPServer", "path": "docforge.cli.commands.mcp_utils.MCPServer",
"signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.cli.mcp_utils.MCPServer')>", "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.cli.mcp_utils.MCPServer')>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.", "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": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -229,7 +229,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.generate_resources", "path": "docforge.cli.commands.mcp_utils.generate_resources",
"signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp_utils.generate_resources')>", "signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp_utils.generate_resources')>",
"docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n project_name (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": { "serve": {
"name": "serve", "name": "serve",
@@ -245,7 +245,7 @@
"kind": "module", "kind": "module",
"path": "docforge.cli.commands.mkdocs_utils", "path": "docforge.cli.commands.mkdocs_utils",
"signature": "<bound method Alias.signature of Alias('mkdocs_utils', 'docforge.cli.mkdocs_utils')>", "signature": "<bound method Alias.signature of Alias('mkdocs_utils', 'docforge.cli.mkdocs_utils')>",
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.", "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": { "members": {
"os": { "os": {
"name": "os", "name": "os",
@@ -294,21 +294,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "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": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, 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": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "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", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.discover_module_paths", "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs_utils.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs_utils.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, 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": { "MkDocsNavEmitter": {
"name": "MkDocsNavEmitter", "name": "MkDocsNavEmitter",
@@ -331,23 +331,30 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit",
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>", "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: 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": "<bound method Alias.signature of Alias('build_wiki_nav', 'docforge.cli.mkdocs_utils.build_wiki_nav')>",
"docstring": "Derive an MkDocs navigation block from a wiki directory.\n\nReturned paths are relative to the parent of ``wiki_dir`` and carry the\nwiki directory name as their leading component (for example\n``wiki/01_overview.md`` when the wiki lives at ``docs/wiki``). This makes\nthe result directly usable in an MkDocs ``nav`` block with\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries compatible with the MkDocs ``nav`` configuration.\n The list is empty if the wiki contains no Markdown files.\n\nRaises:\n FileNotFoundError:\n If the wiki directory does not exist."
},
"load_nav_spec": { "load_nav_spec": {
"name": "load_nav_spec", "name": "load_nav_spec",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.load_nav_spec", "path": "docforge.cli.commands.mkdocs_utils.load_nav_spec",
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs_utils.load_nav_spec')>", "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs_utils.load_nav_spec')>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path 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": { "resolve_nav": {
"name": "resolve_nav", "name": "resolve_nav",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.resolve_nav", "path": "docforge.cli.commands.mkdocs_utils.resolve_nav",
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs_utils.resolve_nav')>", "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs_utils.resolve_nav')>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: 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": { "MkDocsRenderer": {
"name": "MkDocsRenderer", "name": "MkDocsRenderer",
@@ -368,14 +375,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, 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": { "generate_readme": {
"name": "generate_readme", "name": "generate_readme",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>", "signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\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", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.generate_sources", "path": "docforge.cli.commands.mkdocs_utils.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>",
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (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": { "generate_config": {
"name": "generate_config", "name": "generate_config",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.generate_config", "path": "docforge.cli.commands.mkdocs_utils.generate_config",
"signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs_utils.generate_config')>", "signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs_utils.generate_config')>",
"docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\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": { "build": {
"name": "build", "name": "build",
@@ -414,21 +421,93 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.GriffeLoader", "path": "docforge.cli.commands.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "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": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.GriffeLoader.load_project", "path": "docforge.cli.commands.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, 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": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.GriffeLoader.load_module", "path": "docforge.cli.commands.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance.\n\nRaises:\n ImportError:\n If the module cannot be loaded by Griffe.\n\n KeyError:\n If the loaded module is missing from the module collection.\n\nExample:\n Load a single module:\n\n ```python\n loader = GriffeLoader()\n module = loader.load_module(\"mypackage.submodule\")\n ```"
}
}
},
"DocObject": {
"name": "DocObject",
"kind": "class",
"path": "docforge.cli.commands.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (str | None):\n Callable signature if the object represents a callable.\n\n docstring (str | None):\n Raw docstring text extracted from the source code.\n\n members (dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.",
"members": {
"name": {
"name": "name",
"kind": "attribute",
"path": "docforge.cli.commands.DocObject.name",
"signature": "<bound method Alias.signature of Alias('name', 'docforge.models.object.DocObject.name')>",
"docstring": null
},
"kind": {
"name": "kind",
"kind": "attribute",
"path": "docforge.cli.commands.DocObject.kind",
"signature": "<bound method Alias.signature of Alias('kind', 'docforge.models.object.DocObject.kind')>",
"docstring": null
},
"path": {
"name": "path",
"kind": "attribute",
"path": "docforge.cli.commands.DocObject.path",
"signature": "<bound method Alias.signature of Alias('path', 'docforge.models.object.DocObject.path')>",
"docstring": null
},
"signature": {
"name": "signature",
"kind": "attribute",
"path": "docforge.cli.commands.DocObject.signature",
"signature": "<bound method Alias.signature of Alias('signature', 'docforge.models.object.DocObject.signature')>",
"docstring": null
},
"docstring": {
"name": "docstring",
"kind": "attribute",
"path": "docforge.cli.commands.DocObject.docstring",
"signature": "<bound method Alias.signature of Alias('docstring', 'docforge.models.object.DocObject.docstring')>",
"docstring": null
},
"members": {
"name": "members",
"kind": "attribute",
"path": "docforge.cli.commands.DocObject.members",
"signature": "<bound method Alias.signature of Alias('members', 'docforge.models.object.DocObject.members')>",
"docstring": null
},
"add_member": {
"name": "add_member",
"kind": "function",
"path": "docforge.cli.commands.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member."
},
"get_member": {
"name": "get_member",
"kind": "function",
"path": "docforge.cli.commands.DocObject.get_member",
"signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
"docstring": "Retrieve a member object by name.\n\nArgs:\n name (str):\n Name of the member to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If the member does not exist."
},
"get_all_members": {
"name": "get_all_members",
"kind": "function",
"path": "docforge.cli.commands.DocObject.get_all_members",
"signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members."
} }
} }
}, },
@@ -443,29 +522,22 @@
"name": "build", "name": "build",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.build", "path": "docforge.cli.commands.build",
"signature": "<bound method Function.signature of Function('build', 28, 223)>", "signature": "<bound method Function.signature of Function('build', 38, 260)>",
"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." "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": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.serve", "path": "docforge.cli.commands.serve",
"signature": "<bound method Function.signature of Function('serve', 226, 287)>", "signature": "<bound method Function.signature of Function('serve', 263, 324)>",
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (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." "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": { "tree": {
"name": "tree", "name": "tree",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.tree", "path": "docforge.cli.commands.tree",
"signature": "<bound method Function.signature of Function('tree', 290, 326)>", "signature": "<bound method Function.signature of Function('tree', 327, 363)>",
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (Optional[str]):\n Optional name to display as the project root." "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."
},
"Any": {
"name": "Any",
"kind": "alias",
"path": "docforge.cli.commands.Any",
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
}, },
"Group": { "Group": {
"name": "Group", "name": "Group",

219
docs/mcp/modules/docforge.cli.json
View File

@@ -103,22 +103,22 @@
"name": "load_openapi_spec", "name": "load_openapi_spec",
"kind": "function", "kind": "function",
"path": "docforge.cli.api_utils.load_openapi_spec", "path": "docforge.cli.api_utils.load_openapi_spec",
"signature": "<bound method Function.signature of Function('load_openapi_spec', 33, 63)>", "signature": "<bound method Function.signature of Function('load_openapi_spec', 33, 64)>",
"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": { "derive_metadata": {
"name": "derive_metadata", "name": "derive_metadata",
"kind": "function", "kind": "function",
"path": "docforge.cli.api_utils.derive_metadata", "path": "docforge.cli.api_utils.derive_metadata",
"signature": "<bound method Function.signature of Function('derive_metadata', 66, 89)>", "signature": "<bound method Function.signature of Function('derive_metadata', 67, 91)>",
"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": { "generate_api_sources": {
"name": "generate_api_sources", "name": "generate_api_sources",
"kind": "function", "kind": "function",
"path": "docforge.cli.api_utils.generate_api_sources", "path": "docforge.cli.api_utils.generate_api_sources",
"signature": "<bound method Function.signature of Function('generate_api_sources', 92, 114)>", "signature": "<bound method Function.signature of Function('generate_api_sources', 94, 118)>",
"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": { "Any": {
"name": "Any", "name": "Any",
@@ -134,7 +134,7 @@
"kind": "module", "kind": "module",
"path": "docforge.cli.commands", "path": "docforge.cli.commands",
"signature": null, "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": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -227,21 +227,21 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.api_utils.load_openapi_spec", "path": "docforge.cli.commands.api_utils.load_openapi_spec",
"signature": "<bound method Alias.signature of Alias('load_openapi_spec', 'docforge.cli.api_utils.load_openapi_spec')>", "signature": "<bound method Alias.signature of Alias('load_openapi_spec', 'docforge.cli.api_utils.load_openapi_spec')>",
"docstring": "Load and validate an OpenAPI specification from a JSON file.\n\nArgs:\n spec_path: Path 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": { "derive_metadata": {
"name": "derive_metadata", "name": "derive_metadata",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.api_utils.derive_metadata", "path": "docforge.cli.commands.api_utils.derive_metadata",
"signature": "<bound method Alias.signature of Alias('derive_metadata', 'docforge.cli.api_utils.derive_metadata')>", "signature": "<bound method Alias.signature of Alias('derive_metadata', 'docforge.cli.api_utils.derive_metadata')>",
"docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec: 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": { "generate_api_sources": {
"name": "generate_api_sources", "name": "generate_api_sources",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.api_utils.generate_api_sources", "path": "docforge.cli.commands.api_utils.generate_api_sources",
"signature": "<bound method Alias.signature of Alias('generate_api_sources', 'docforge.cli.api_utils.generate_api_sources')>", "signature": "<bound method Alias.signature of Alias('generate_api_sources', 'docforge.cli.api_utils.generate_api_sources')>",
"docstring": "Generate swagger-enabled Markdown sources and the spec copy.\n\nThe specification is written as ``openapi.json`` inside ``docs_dir`` and\nan ``index.md`` embedding the swagger UI is generated alongside it.\n\nArgs:\n spec: 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": { "Any": {
"name": "Any", "name": "Any",
@@ -257,7 +257,7 @@
"kind": "module", "kind": "module",
"path": "docforge.cli.commands.mcp_utils", "path": "docforge.cli.commands.mcp_utils",
"signature": "<bound method Alias.signature of Alias('mcp_utils', 'docforge.cli.mcp_utils')>", "signature": "<bound method Alias.signature of Alias('mcp_utils', 'docforge.cli.mcp_utils')>",
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.", "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": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -278,21 +278,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader", "path": "docforge.cli.commands.mcp_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp_utils.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp_utils.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "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": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, 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": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "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", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.discover_module_paths", "path": "docforge.cli.commands.mcp_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp_utils.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp_utils.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, 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": { "MCPRenderer": {
"name": "MCPRenderer", "name": "MCPRenderer",
@@ -331,7 +331,7 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mcp_utils.MCPServer", "path": "docforge.cli.commands.mcp_utils.MCPServer",
"signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.cli.mcp_utils.MCPServer')>", "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.cli.mcp_utils.MCPServer')>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.", "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": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -361,7 +361,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.generate_resources", "path": "docforge.cli.commands.mcp_utils.generate_resources",
"signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp_utils.generate_resources')>", "signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp_utils.generate_resources')>",
"docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n project_name (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": { "serve": {
"name": "serve", "name": "serve",
@@ -377,7 +377,7 @@
"kind": "module", "kind": "module",
"path": "docforge.cli.commands.mkdocs_utils", "path": "docforge.cli.commands.mkdocs_utils",
"signature": "<bound method Alias.signature of Alias('mkdocs_utils', 'docforge.cli.mkdocs_utils')>", "signature": "<bound method Alias.signature of Alias('mkdocs_utils', 'docforge.cli.mkdocs_utils')>",
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.", "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": { "members": {
"os": { "os": {
"name": "os", "name": "os",
@@ -426,21 +426,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "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": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, 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": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "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", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.discover_module_paths", "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs_utils.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs_utils.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, 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": { "MkDocsNavEmitter": {
"name": "MkDocsNavEmitter", "name": "MkDocsNavEmitter",
@@ -463,23 +463,30 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit",
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>", "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: 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": "<bound method Alias.signature of Alias('build_wiki_nav', 'docforge.cli.mkdocs_utils.build_wiki_nav')>",
"docstring": "Derive an MkDocs navigation block from a wiki directory.\n\nReturned paths are relative to the parent of ``wiki_dir`` and carry the\nwiki directory name as their leading component (for example\n``wiki/01_overview.md`` when the wiki lives at ``docs/wiki``). This makes\nthe result directly usable in an MkDocs ``nav`` block with\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries compatible with the MkDocs ``nav`` configuration.\n The list is empty if the wiki contains no Markdown files.\n\nRaises:\n FileNotFoundError:\n If the wiki directory does not exist."
},
"load_nav_spec": { "load_nav_spec": {
"name": "load_nav_spec", "name": "load_nav_spec",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.load_nav_spec", "path": "docforge.cli.commands.mkdocs_utils.load_nav_spec",
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs_utils.load_nav_spec')>", "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs_utils.load_nav_spec')>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path 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": { "resolve_nav": {
"name": "resolve_nav", "name": "resolve_nav",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.resolve_nav", "path": "docforge.cli.commands.mkdocs_utils.resolve_nav",
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs_utils.resolve_nav')>", "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs_utils.resolve_nav')>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: 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": { "MkDocsRenderer": {
"name": "MkDocsRenderer", "name": "MkDocsRenderer",
@@ -500,14 +507,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, 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": { "generate_readme": {
"name": "generate_readme", "name": "generate_readme",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>", "signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\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", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.generate_sources", "path": "docforge.cli.commands.mkdocs_utils.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>",
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (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": { "generate_config": {
"name": "generate_config", "name": "generate_config",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.generate_config", "path": "docforge.cli.commands.mkdocs_utils.generate_config",
"signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs_utils.generate_config')>", "signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs_utils.generate_config')>",
"docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\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": { "build": {
"name": "build", "name": "build",
@@ -546,21 +553,93 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.GriffeLoader", "path": "docforge.cli.commands.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "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": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.GriffeLoader.load_project", "path": "docforge.cli.commands.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, 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": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.GriffeLoader.load_module", "path": "docforge.cli.commands.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance.\n\nRaises:\n ImportError:\n If the module cannot be loaded by Griffe.\n\n KeyError:\n If the loaded module is missing from the module collection.\n\nExample:\n Load a single module:\n\n ```python\n loader = GriffeLoader()\n module = loader.load_module(\"mypackage.submodule\")\n ```"
}
}
},
"DocObject": {
"name": "DocObject",
"kind": "class",
"path": "docforge.cli.commands.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (str | None):\n Callable signature if the object represents a callable.\n\n docstring (str | None):\n Raw docstring text extracted from the source code.\n\n members (dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.",
"members": {
"name": {
"name": "name",
"kind": "attribute",
"path": "docforge.cli.commands.DocObject.name",
"signature": "<bound method Alias.signature of Alias('name', 'docforge.models.object.DocObject.name')>",
"docstring": null
},
"kind": {
"name": "kind",
"kind": "attribute",
"path": "docforge.cli.commands.DocObject.kind",
"signature": "<bound method Alias.signature of Alias('kind', 'docforge.models.object.DocObject.kind')>",
"docstring": null
},
"path": {
"name": "path",
"kind": "attribute",
"path": "docforge.cli.commands.DocObject.path",
"signature": "<bound method Alias.signature of Alias('path', 'docforge.models.object.DocObject.path')>",
"docstring": null
},
"signature": {
"name": "signature",
"kind": "attribute",
"path": "docforge.cli.commands.DocObject.signature",
"signature": "<bound method Alias.signature of Alias('signature', 'docforge.models.object.DocObject.signature')>",
"docstring": null
},
"docstring": {
"name": "docstring",
"kind": "attribute",
"path": "docforge.cli.commands.DocObject.docstring",
"signature": "<bound method Alias.signature of Alias('docstring', 'docforge.models.object.DocObject.docstring')>",
"docstring": null
},
"members": {
"name": "members",
"kind": "attribute",
"path": "docforge.cli.commands.DocObject.members",
"signature": "<bound method Alias.signature of Alias('members', 'docforge.models.object.DocObject.members')>",
"docstring": null
},
"add_member": {
"name": "add_member",
"kind": "function",
"path": "docforge.cli.commands.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member."
},
"get_member": {
"name": "get_member",
"kind": "function",
"path": "docforge.cli.commands.DocObject.get_member",
"signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
"docstring": "Retrieve a member object by name.\n\nArgs:\n name (str):\n Name of the member to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If the member does not exist."
},
"get_all_members": {
"name": "get_all_members",
"kind": "function",
"path": "docforge.cli.commands.DocObject.get_all_members",
"signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members."
} }
} }
}, },
@@ -575,29 +654,22 @@
"name": "build", "name": "build",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.build", "path": "docforge.cli.commands.build",
"signature": "<bound method Function.signature of Function('build', 28, 223)>", "signature": "<bound method Function.signature of Function('build', 38, 260)>",
"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." "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": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.serve", "path": "docforge.cli.commands.serve",
"signature": "<bound method Function.signature of Function('serve', 226, 287)>", "signature": "<bound method Function.signature of Function('serve', 263, 324)>",
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (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." "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": { "tree": {
"name": "tree", "name": "tree",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.tree", "path": "docforge.cli.commands.tree",
"signature": "<bound method Function.signature of Function('tree', 290, 326)>", "signature": "<bound method Function.signature of Function('tree', 327, 363)>",
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (Optional[str]):\n Optional name to display as the project root." "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."
},
"Any": {
"name": "Any",
"kind": "alias",
"path": "docforge.cli.commands.Any",
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
}, },
"Group": { "Group": {
"name": "Group", "name": "Group",
@@ -613,7 +685,7 @@
"kind": "module", "kind": "module",
"path": "docforge.cli.mcp_utils", "path": "docforge.cli.mcp_utils",
"signature": null, "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": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -634,21 +706,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.mcp_utils.GriffeLoader", "path": "docforge.cli.mcp_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "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": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.GriffeLoader.load_project", "path": "docforge.cli.mcp_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, 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": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.GriffeLoader.load_module", "path": "docforge.cli.mcp_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "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", "kind": "function",
"path": "docforge.cli.mcp_utils.discover_module_paths", "path": "docforge.cli.mcp_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, 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": { "MCPRenderer": {
"name": "MCPRenderer", "name": "MCPRenderer",
@@ -687,7 +759,7 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.mcp_utils.MCPServer", "path": "docforge.cli.mcp_utils.MCPServer",
"signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.MCPServer')>", "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.MCPServer')>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.", "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": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -716,14 +788,14 @@
"name": "generate_resources", "name": "generate_resources",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.generate_resources", "path": "docforge.cli.mcp_utils.generate_resources",
"signature": "<bound method Function.signature of Function('generate_resources', 16, 42)>", "signature": "<bound method Function.signature of Function('generate_resources', 26, 52)>",
"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": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.serve", "path": "docforge.cli.mcp_utils.serve",
"signature": "<bound method Function.signature of Function('serve', 45, 82)>", "signature": "<bound method Function.signature of Function('serve', 55, 92)>",
"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." "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", "kind": "module",
"path": "docforge.cli.mkdocs_utils", "path": "docforge.cli.mkdocs_utils",
"signature": null, "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": { "members": {
"os": { "os": {
"name": "os", "name": "os",
@@ -782,21 +854,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.mkdocs_utils.GriffeLoader", "path": "docforge.cli.mkdocs_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "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": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, 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": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "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", "kind": "function",
"path": "docforge.cli.mkdocs_utils.discover_module_paths", "path": "docforge.cli.mkdocs_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, 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": { "MkDocsNavEmitter": {
"name": "MkDocsNavEmitter", "name": "MkDocsNavEmitter",
@@ -819,23 +891,30 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit",
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>", "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: 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": "<bound method Alias.signature of Alias('build_wiki_nav', 'docforge.nav.build_wiki_nav')>",
"docstring": "Derive an MkDocs navigation block from a wiki directory.\n\nReturned paths are relative to the parent of ``wiki_dir`` and carry the\nwiki directory name as their leading component (for example\n``wiki/01_overview.md`` when the wiki lives at ``docs/wiki``). This makes\nthe result directly usable in an MkDocs ``nav`` block with\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries compatible with the MkDocs ``nav`` configuration.\n The list is empty if the wiki contains no Markdown files.\n\nRaises:\n FileNotFoundError:\n If the wiki directory does not exist."
},
"load_nav_spec": { "load_nav_spec": {
"name": "load_nav_spec", "name": "load_nav_spec",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.load_nav_spec", "path": "docforge.cli.mkdocs_utils.load_nav_spec",
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.load_nav_spec')>", "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.load_nav_spec')>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path 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": { "resolve_nav": {
"name": "resolve_nav", "name": "resolve_nav",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.resolve_nav", "path": "docforge.cli.mkdocs_utils.resolve_nav",
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolve_nav')>", "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolve_nav')>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: 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": { "MkDocsRenderer": {
"name": "MkDocsRenderer", "name": "MkDocsRenderer",
@@ -856,14 +935,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, 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": { "generate_readme": {
"name": "generate_readme", "name": "generate_readme",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>", "signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\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", "name": "generate_sources",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_sources", "path": "docforge.cli.mkdocs_utils.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 20, 69)>", "signature": "<bound method Function.signature of Function('generate_sources', 34, 83)>",
"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": { "generate_config": {
"name": "generate_config", "name": "generate_config",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_config", "path": "docforge.cli.mkdocs_utils.generate_config",
"signature": "<bound method Function.signature of Function('generate_config', 72, 150)>", "signature": "<bound method Function.signature of Function('generate_config', 86, 186)>",
"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": { "build": {
"name": "build", "name": "build",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.build", "path": "docforge.cli.mkdocs_utils.build",
"signature": "<bound method Function.signature of Function('build', 272, 293)>", "signature": "<bound method Function.signature of Function('build', 313, 334)>",
"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." "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": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.serve", "path": "docforge.cli.mkdocs_utils.serve",
"signature": "<bound method Function.signature of Function('serve', 296, 316)>", "signature": "<bound method Function.signature of Function('serve', 337, 357)>",
"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." "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."
} }
} }

18
docs/mcp/modules/docforge.cli.mcp_utils.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.cli.mcp_utils", "module": "docforge.cli.mcp_utils",
"content": { "content": {
"path": "docforge.cli.mcp_utils", "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": { "objects": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -23,21 +23,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.mcp_utils.GriffeLoader", "path": "docforge.cli.mcp_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "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": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.GriffeLoader.load_project", "path": "docforge.cli.mcp_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, 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": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.GriffeLoader.load_module", "path": "docforge.cli.mcp_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "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", "kind": "function",
"path": "docforge.cli.mcp_utils.discover_module_paths", "path": "docforge.cli.mcp_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, 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": { "MCPRenderer": {
"name": "MCPRenderer", "name": "MCPRenderer",
@@ -76,7 +76,7 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.mcp_utils.MCPServer", "path": "docforge.cli.mcp_utils.MCPServer",
"signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.MCPServer')>", "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.MCPServer')>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.", "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": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -105,14 +105,14 @@
"name": "generate_resources", "name": "generate_resources",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.generate_resources", "path": "docforge.cli.mcp_utils.generate_resources",
"signature": "<bound method Function.signature of Function('generate_resources', 16, 42)>", "signature": "<bound method Function.signature of Function('generate_resources', 26, 52)>",
"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": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.serve", "path": "docforge.cli.mcp_utils.serve",
"signature": "<bound method Function.signature of Function('serve', 45, 82)>", "signature": "<bound method Function.signature of Function('serve', 55, 92)>",
"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." "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."
} }
} }

39
docs/mcp/modules/docforge.cli.mkdocs_utils.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.cli.mkdocs_utils", "module": "docforge.cli.mkdocs_utils",
"content": { "content": {
"path": "docforge.cli.mkdocs_utils", "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": { "objects": {
"os": { "os": {
"name": "os", "name": "os",
@@ -51,21 +51,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.mkdocs_utils.GriffeLoader", "path": "docforge.cli.mkdocs_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "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": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, 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": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "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", "kind": "function",
"path": "docforge.cli.mkdocs_utils.discover_module_paths", "path": "docforge.cli.mkdocs_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, 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": { "MkDocsNavEmitter": {
"name": "MkDocsNavEmitter", "name": "MkDocsNavEmitter",
@@ -88,23 +88,30 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit",
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>", "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: 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": "<bound method Alias.signature of Alias('build_wiki_nav', 'docforge.nav.build_wiki_nav')>",
"docstring": "Derive an MkDocs navigation block from a wiki directory.\n\nReturned paths are relative to the parent of ``wiki_dir`` and carry the\nwiki directory name as their leading component (for example\n``wiki/01_overview.md`` when the wiki lives at ``docs/wiki``). This makes\nthe result directly usable in an MkDocs ``nav`` block with\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries compatible with the MkDocs ``nav`` configuration.\n The list is empty if the wiki contains no Markdown files.\n\nRaises:\n FileNotFoundError:\n If the wiki directory does not exist."
},
"load_nav_spec": { "load_nav_spec": {
"name": "load_nav_spec", "name": "load_nav_spec",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.load_nav_spec", "path": "docforge.cli.mkdocs_utils.load_nav_spec",
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.load_nav_spec')>", "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.load_nav_spec')>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path 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": { "resolve_nav": {
"name": "resolve_nav", "name": "resolve_nav",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.resolve_nav", "path": "docforge.cli.mkdocs_utils.resolve_nav",
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolve_nav')>", "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolve_nav')>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: 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": { "MkDocsRenderer": {
"name": "MkDocsRenderer", "name": "MkDocsRenderer",
@@ -125,14 +132,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, 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": { "generate_readme": {
"name": "generate_readme", "name": "generate_readme",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>", "signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\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", "name": "generate_sources",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_sources", "path": "docforge.cli.mkdocs_utils.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 20, 69)>", "signature": "<bound method Function.signature of Function('generate_sources', 34, 83)>",
"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": { "generate_config": {
"name": "generate_config", "name": "generate_config",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_config", "path": "docforge.cli.mkdocs_utils.generate_config",
"signature": "<bound method Function.signature of Function('generate_config', 72, 150)>", "signature": "<bound method Function.signature of Function('generate_config', 86, 186)>",
"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": { "build": {
"name": "build", "name": "build",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.build", "path": "docforge.cli.mkdocs_utils.build",
"signature": "<bound method Function.signature of Function('build', 272, 293)>", "signature": "<bound method Function.signature of Function('build', 313, 334)>",
"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." "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": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.serve", "path": "docforge.cli.mkdocs_utils.serve",
"signature": "<bound method Function.signature of Function('serve', 296, 316)>", "signature": "<bound method Function.signature of Function('serve', 337, 357)>",
"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." "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."
} }
} }

469
docs/mcp/modules/docforge.json
View File

File diff suppressed because one or more lines are too long

26
docs/mcp/modules/docforge.loaders.griffe_loader.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.loaders.griffe_loader", "module": "docforge.loaders.griffe_loader",
"content": { "content": {
"path": "docforge.loaders.griffe_loader", "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": { "objects": {
"logging": { "logging": {
"name": "logging", "name": "logging",
@@ -51,7 +51,7 @@
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.DocObject", "path": "docforge.loaders.griffe_loader.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -100,7 +100,7 @@
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.DocObject.add_member", "path": "docforge.loaders.griffe_loader.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: 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": { "get_member": {
"name": "get_member", "name": "get_member",
@@ -123,7 +123,7 @@
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.Module", "path": "docforge.loaders.griffe_loader.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
"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": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -174,7 +174,7 @@
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.Project", "path": "docforge.loaders.griffe_loader.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -231,29 +231,29 @@
"name": "discover_module_paths", "name": "discover_module_paths",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.discover_module_paths", "path": "docforge.loaders.griffe_loader.discover_module_paths",
"signature": "<bound method Function.signature of Function('discover_module_paths', 29, 81)>", "signature": "<bound method Function.signature of Function('discover_module_paths', 37, 89)>",
"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."
}, },
"GriffeLoader": { "GriffeLoader": {
"name": "GriffeLoader", "name": "GriffeLoader",
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.GriffeLoader", "path": "docforge.loaders.griffe_loader.GriffeLoader",
"signature": "<bound method Class.signature of Class('GriffeLoader', 84, 288)>", "signature": "<bound method Class.signature of Class('GriffeLoader', 92, 315)>",
"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": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_project", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_project",
"signature": "<bound method Function.signature of Function('load_project', 105, 159)>", "signature": "<bound method Function.signature of Function('load_project', 117, 171)>",
"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": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_module", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_module",
"signature": "<bound method Function.signature of Function('load_module', 161, 179)>", "signature": "<bound method Function.signature of Function('load_module', 173, 206)>",
"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 ```"
} }
} }
} }

34
docs/mcp/modules/docforge.loaders.json
View File

@@ -9,21 +9,21 @@
"kind": "class", "kind": "class",
"path": "docforge.loaders.GriffeLoader", "path": "docforge.loaders.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.griffe_loader.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.griffe_loader.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "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": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.loaders.GriffeLoader.load_project", "path": "docforge.loaders.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, 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": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.loaders.GriffeLoader.load_module", "path": "docforge.loaders.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "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", "kind": "function",
"path": "docforge.loaders.discover_module_paths", "path": "docforge.loaders.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.griffe_loader.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.griffe_loader.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, 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": { "griffe_loader": {
"name": "griffe_loader", "name": "griffe_loader",
"kind": "module", "kind": "module",
"path": "docforge.loaders.griffe_loader", "path": "docforge.loaders.griffe_loader",
"signature": null, "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": { "members": {
"logging": { "logging": {
"name": "logging", "name": "logging",
@@ -88,7 +88,7 @@
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.DocObject", "path": "docforge.loaders.griffe_loader.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -137,7 +137,7 @@
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.DocObject.add_member", "path": "docforge.loaders.griffe_loader.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: 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": { "get_member": {
"name": "get_member", "name": "get_member",
@@ -160,7 +160,7 @@
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.Module", "path": "docforge.loaders.griffe_loader.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
"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": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -211,7 +211,7 @@
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.Project", "path": "docforge.loaders.griffe_loader.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -268,29 +268,29 @@
"name": "discover_module_paths", "name": "discover_module_paths",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.discover_module_paths", "path": "docforge.loaders.griffe_loader.discover_module_paths",
"signature": "<bound method Function.signature of Function('discover_module_paths', 29, 81)>", "signature": "<bound method Function.signature of Function('discover_module_paths', 37, 89)>",
"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."
}, },
"GriffeLoader": { "GriffeLoader": {
"name": "GriffeLoader", "name": "GriffeLoader",
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.GriffeLoader", "path": "docforge.loaders.griffe_loader.GriffeLoader",
"signature": "<bound method Class.signature of Class('GriffeLoader', 84, 288)>", "signature": "<bound method Class.signature of Class('GriffeLoader', 92, 315)>",
"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": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_project", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_project",
"signature": "<bound method Function.signature of Function('load_project', 105, 159)>", "signature": "<bound method Function.signature of Function('load_project', 117, 171)>",
"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": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_module", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_module",
"signature": "<bound method Function.signature of Function('load_module', 161, 179)>", "signature": "<bound method Function.signature of Function('load_module', 173, 206)>",
"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 ```"
} }
} }
} }

54
docs/mcp/modules/docforge.models.json
View File

@@ -9,7 +9,7 @@
"kind": "class", "kind": "class",
"path": "docforge.models.Project", "path": "docforge.models.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.project.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.project.Project')>",
"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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -60,7 +60,7 @@
"kind": "class", "kind": "class",
"path": "docforge.models.Module", "path": "docforge.models.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>",
"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": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -111,7 +111,7 @@
"kind": "class", "kind": "class",
"path": "docforge.models.DocObject", "path": "docforge.models.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -160,7 +160,7 @@
"kind": "function", "kind": "function",
"path": "docforge.models.DocObject.add_member", "path": "docforge.models.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: 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": { "get_member": {
"name": "get_member", "name": "get_member",
@@ -183,7 +183,7 @@
"kind": "module", "kind": "module",
"path": "docforge.models.module", "path": "docforge.models.module",
"signature": null, "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": { "members": {
"Iterable": { "Iterable": {
"name": "Iterable", "name": "Iterable",
@@ -197,7 +197,7 @@
"kind": "class", "kind": "class",
"path": "docforge.models.module.DocObject", "path": "docforge.models.module.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -246,7 +246,7 @@
"kind": "function", "kind": "function",
"path": "docforge.models.module.DocObject.add_member", "path": "docforge.models.module.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: 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": { "get_member": {
"name": "get_member", "name": "get_member",
@@ -268,8 +268,8 @@
"name": "Module", "name": "Module",
"kind": "class", "kind": "class",
"path": "docforge.models.module.Module", "path": "docforge.models.module.Module",
"signature": "<bound method Class.signature of Class('Module', 17, 91)>", "signature": "<bound method Class.signature of Class('Module', 24, 98)>",
"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": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -296,21 +296,21 @@
"name": "add_object", "name": "add_object",
"kind": "function", "kind": "function",
"path": "docforge.models.module.Module.add_object", "path": "docforge.models.module.Module.add_object",
"signature": "<bound method Function.signature of Function('add_object', 55, 63)>", "signature": "<bound method Function.signature of Function('add_object', 62, 70)>",
"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." "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": { "get_object": {
"name": "get_object", "name": "get_object",
"kind": "function", "kind": "function",
"path": "docforge.models.module.Module.get_object", "path": "docforge.models.module.Module.get_object",
"signature": "<bound method Function.signature of Function('get_object', 65, 81)>", "signature": "<bound method Function.signature of Function('get_object', 72, 88)>",
"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." "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": { "get_all_objects": {
"name": "get_all_objects", "name": "get_all_objects",
"kind": "function", "kind": "function",
"path": "docforge.models.module.Module.get_all_objects", "path": "docforge.models.module.Module.get_all_objects",
"signature": "<bound method Function.signature of Function('get_all_objects', 83, 91)>", "signature": "<bound method Function.signature of Function('get_all_objects', 90, 98)>",
"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." "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", "kind": "module",
"path": "docforge.models.object", "path": "docforge.models.object",
"signature": null, "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": { "members": {
"Iterable": { "Iterable": {
"name": "Iterable", "name": "Iterable",
@@ -335,8 +335,8 @@
"name": "DocObject", "name": "DocObject",
"kind": "class", "kind": "class",
"path": "docforge.models.object.DocObject", "path": "docforge.models.object.DocObject",
"signature": "<bound method Class.signature of Class('DocObject', 15, 115)>", "signature": "<bound method Class.signature of Class('DocObject', 23, 124)>",
"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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -384,21 +384,21 @@
"name": "add_member", "name": "add_member",
"kind": "function", "kind": "function",
"path": "docforge.models.object.DocObject.add_member", "path": "docforge.models.object.DocObject.add_member",
"signature": "<bound method Function.signature of Function('add_member', 77, 87)>", "signature": "<bound method Function.signature of Function('add_member', 85, 96)>",
"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": { "get_member": {
"name": "get_member", "name": "get_member",
"kind": "function", "kind": "function",
"path": "docforge.models.object.DocObject.get_member", "path": "docforge.models.object.DocObject.get_member",
"signature": "<bound method Function.signature of Function('get_member', 89, 105)>", "signature": "<bound method Function.signature of Function('get_member', 98, 114)>",
"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." "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": { "get_all_members": {
"name": "get_all_members", "name": "get_all_members",
"kind": "function", "kind": "function",
"path": "docforge.models.object.DocObject.get_all_members", "path": "docforge.models.object.DocObject.get_all_members",
"signature": "<bound method Function.signature of Function('get_all_members', 107, 115)>", "signature": "<bound method Function.signature of Function('get_all_members', 116, 124)>",
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." "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", "kind": "module",
"path": "docforge.models.project", "path": "docforge.models.project",
"signature": null, "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": { "members": {
"Iterable": { "Iterable": {
"name": "Iterable", "name": "Iterable",
@@ -424,7 +424,7 @@
"kind": "class", "kind": "class",
"path": "docforge.models.project.Module", "path": "docforge.models.project.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>",
"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": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -474,8 +474,8 @@
"name": "Project", "name": "Project",
"kind": "class", "kind": "class",
"path": "docforge.models.project.Project", "path": "docforge.models.project.Project",
"signature": "<bound method Class.signature of Class('Project', 16, 88)>", "signature": "<bound method Class.signature of Class('Project', 24, 104)>",
"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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -495,28 +495,28 @@
"name": "add_module", "name": "add_module",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.add_module", "path": "docforge.models.project.Project.add_module",
"signature": "<bound method Function.signature of Function('add_module', 42, 50)>", "signature": "<bound method Function.signature of Function('add_module', 58, 66)>",
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project." "docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
}, },
"get_module": { "get_module": {
"name": "get_module", "name": "get_module",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.get_module", "path": "docforge.models.project.Project.get_module",
"signature": "<bound method Function.signature of Function('get_module', 52, 68)>", "signature": "<bound method Function.signature of Function('get_module', 68, 84)>",
"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." "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": { "get_all_modules": {
"name": "get_all_modules", "name": "get_all_modules",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.get_all_modules", "path": "docforge.models.project.Project.get_all_modules",
"signature": "<bound method Function.signature of Function('get_all_modules', 70, 78)>", "signature": "<bound method Function.signature of Function('get_all_modules', 86, 94)>",
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances." "docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
}, },
"get_module_list": { "get_module_list": {
"name": "get_module_list", "name": "get_module_list",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.get_module_list", "path": "docforge.models.project.Project.get_module_list",
"signature": "<bound method Function.signature of Function('get_module_list', 80, 88)>", "signature": "<bound method Function.signature of Function('get_module_list', 96, 104)>",
"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." "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."
} }
} }

16
docs/mcp/modules/docforge.models.module.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.models.module", "module": "docforge.models.module",
"content": { "content": {
"path": "docforge.models.module", "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": { "objects": {
"Iterable": { "Iterable": {
"name": "Iterable", "name": "Iterable",
@@ -16,7 +16,7 @@
"kind": "class", "kind": "class",
"path": "docforge.models.module.DocObject", "path": "docforge.models.module.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -65,7 +65,7 @@
"kind": "function", "kind": "function",
"path": "docforge.models.module.DocObject.add_member", "path": "docforge.models.module.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: 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": { "get_member": {
"name": "get_member", "name": "get_member",
@@ -87,8 +87,8 @@
"name": "Module", "name": "Module",
"kind": "class", "kind": "class",
"path": "docforge.models.module.Module", "path": "docforge.models.module.Module",
"signature": "<bound method Class.signature of Class('Module', 17, 91)>", "signature": "<bound method Class.signature of Class('Module', 24, 98)>",
"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": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -115,21 +115,21 @@
"name": "add_object", "name": "add_object",
"kind": "function", "kind": "function",
"path": "docforge.models.module.Module.add_object", "path": "docforge.models.module.Module.add_object",
"signature": "<bound method Function.signature of Function('add_object', 55, 63)>", "signature": "<bound method Function.signature of Function('add_object', 62, 70)>",
"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." "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": { "get_object": {
"name": "get_object", "name": "get_object",
"kind": "function", "kind": "function",
"path": "docforge.models.module.Module.get_object", "path": "docforge.models.module.Module.get_object",
"signature": "<bound method Function.signature of Function('get_object', 65, 81)>", "signature": "<bound method Function.signature of Function('get_object', 72, 88)>",
"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." "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": { "get_all_objects": {
"name": "get_all_objects", "name": "get_all_objects",
"kind": "function", "kind": "function",
"path": "docforge.models.module.Module.get_all_objects", "path": "docforge.models.module.Module.get_all_objects",
"signature": "<bound method Function.signature of Function('get_all_objects', 83, 91)>", "signature": "<bound method Function.signature of Function('get_all_objects', 90, 98)>",
"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." "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."
} }
} }

14
docs/mcp/modules/docforge.models.object.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.models.object", "module": "docforge.models.object",
"content": { "content": {
"path": "docforge.models.object", "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": { "objects": {
"Iterable": { "Iterable": {
"name": "Iterable", "name": "Iterable",
@@ -15,8 +15,8 @@
"name": "DocObject", "name": "DocObject",
"kind": "class", "kind": "class",
"path": "docforge.models.object.DocObject", "path": "docforge.models.object.DocObject",
"signature": "<bound method Class.signature of Class('DocObject', 15, 115)>", "signature": "<bound method Class.signature of Class('DocObject', 23, 124)>",
"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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -64,21 +64,21 @@
"name": "add_member", "name": "add_member",
"kind": "function", "kind": "function",
"path": "docforge.models.object.DocObject.add_member", "path": "docforge.models.object.DocObject.add_member",
"signature": "<bound method Function.signature of Function('add_member', 77, 87)>", "signature": "<bound method Function.signature of Function('add_member', 85, 96)>",
"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": { "get_member": {
"name": "get_member", "name": "get_member",
"kind": "function", "kind": "function",
"path": "docforge.models.object.DocObject.get_member", "path": "docforge.models.object.DocObject.get_member",
"signature": "<bound method Function.signature of Function('get_member', 89, 105)>", "signature": "<bound method Function.signature of Function('get_member', 98, 114)>",
"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." "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": { "get_all_members": {
"name": "get_all_members", "name": "get_all_members",
"kind": "function", "kind": "function",
"path": "docforge.models.object.DocObject.get_all_members", "path": "docforge.models.object.DocObject.get_all_members",
"signature": "<bound method Function.signature of Function('get_all_members', 107, 115)>", "signature": "<bound method Function.signature of Function('get_all_members', 116, 124)>",
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." "docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members."
} }
} }

16
docs/mcp/modules/docforge.models.project.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.models.project", "module": "docforge.models.project",
"content": { "content": {
"path": "docforge.models.project", "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": { "objects": {
"Iterable": { "Iterable": {
"name": "Iterable", "name": "Iterable",
@@ -16,7 +16,7 @@
"kind": "class", "kind": "class",
"path": "docforge.models.project.Module", "path": "docforge.models.project.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>",
"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": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -66,8 +66,8 @@
"name": "Project", "name": "Project",
"kind": "class", "kind": "class",
"path": "docforge.models.project.Project", "path": "docforge.models.project.Project",
"signature": "<bound method Class.signature of Class('Project', 16, 88)>", "signature": "<bound method Class.signature of Class('Project', 24, 104)>",
"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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -87,28 +87,28 @@
"name": "add_module", "name": "add_module",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.add_module", "path": "docforge.models.project.Project.add_module",
"signature": "<bound method Function.signature of Function('add_module', 42, 50)>", "signature": "<bound method Function.signature of Function('add_module', 58, 66)>",
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project." "docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
}, },
"get_module": { "get_module": {
"name": "get_module", "name": "get_module",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.get_module", "path": "docforge.models.project.Project.get_module",
"signature": "<bound method Function.signature of Function('get_module', 52, 68)>", "signature": "<bound method Function.signature of Function('get_module', 68, 84)>",
"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." "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": { "get_all_modules": {
"name": "get_all_modules", "name": "get_all_modules",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.get_all_modules", "path": "docforge.models.project.Project.get_all_modules",
"signature": "<bound method Function.signature of Function('get_all_modules', 70, 78)>", "signature": "<bound method Function.signature of Function('get_all_modules', 86, 94)>",
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances." "docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
}, },
"get_module_list": { "get_module_list": {
"name": "get_module_list", "name": "get_module_list",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.get_module_list", "path": "docforge.models.project.Project.get_module_list",
"signature": "<bound method Function.signature of Function('get_module_list', 80, 88)>", "signature": "<bound method Function.signature of Function('get_module_list', 96, 104)>",
"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." "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."
} }
} }

112
docs/mcp/modules/docforge.nav.json
View File

@@ -37,14 +37,14 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.NavSpec.load", "path": "docforge.nav.NavSpec.load",
"signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>", "signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>",
"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": { "all_patterns": {
"name": "all_patterns", "name": "all_patterns",
"kind": "function", "kind": "function",
"path": "docforge.nav.NavSpec.all_patterns", "path": "docforge.nav.NavSpec.all_patterns",
"signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>", "signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>",
"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", "kind": "function",
"path": "docforge.nav.load_nav_spec", "path": "docforge.nav.load_nav_spec",
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.spec.load_nav_spec')>", "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.spec.load_nav_spec')>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path 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": { "ResolvedNav": {
"name": "ResolvedNav", "name": "ResolvedNav",
@@ -81,7 +81,7 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.ResolvedNav.all_files", "path": "docforge.nav.ResolvedNav.all_files",
"signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>", "signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>",
"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", "kind": "function",
"path": "docforge.nav.resolve_nav", "path": "docforge.nav.resolve_nav",
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolver.resolve_nav')>", "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolver.resolve_nav')>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: 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": { "MkDocsNavEmitter": {
"name": "MkDocsNavEmitter", "name": "MkDocsNavEmitter",
@@ -104,16 +104,23 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.MkDocsNavEmitter.emit", "path": "docforge.nav.MkDocsNavEmitter.emit",
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>", "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: 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": "<bound method Alias.signature of Alias('build_wiki_nav', 'docforge.nav.wiki.build_wiki_nav')>",
"docstring": "Derive an MkDocs navigation block from a wiki directory.\n\nReturned paths are relative to the parent of ``wiki_dir`` and carry the\nwiki directory name as their leading component (for example\n``wiki/01_overview.md`` when the wiki lives at ``docs/wiki``). This makes\nthe result directly usable in an MkDocs ``nav`` block with\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries compatible with the MkDocs ``nav`` configuration.\n The list is empty if the wiki contains no Markdown files.\n\nRaises:\n FileNotFoundError:\n If the wiki directory does not exist."
},
"mkdocs": { "mkdocs": {
"name": "mkdocs", "name": "mkdocs",
"kind": "module", "kind": "module",
"path": "docforge.nav.mkdocs", "path": "docforge.nav.mkdocs",
"signature": null, "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": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -155,7 +162,7 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.mkdocs.ResolvedNav.all_files", "path": "docforge.nav.mkdocs.ResolvedNav.all_files",
"signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>", "signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>",
"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", "name": "MkDocsNavEmitter",
"kind": "class", "kind": "class",
"path": "docforge.nav.mkdocs.MkDocsNavEmitter", "path": "docforge.nav.mkdocs.MkDocsNavEmitter",
"signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 15, 81)>", "signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 23, 94)>",
"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.", "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": { "members": {
"emit": { "emit": {
"name": "emit", "name": "emit",
"kind": "function", "kind": "function",
"path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit", "path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit",
"signature": "<bound method Function.signature of Function('emit', 23, 51)>", "signature": "<bound method Function.signature of Function('emit', 31, 61)>",
"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."
} }
} }
} }
@@ -182,7 +189,7 @@
"kind": "module", "kind": "module",
"path": "docforge.nav.resolver", "path": "docforge.nav.resolver",
"signature": null, "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": { "members": {
"glob": { "glob": {
"name": "glob", "name": "glob",
@@ -238,14 +245,14 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.NavSpec.load", "path": "docforge.nav.resolver.NavSpec.load",
"signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>", "signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>",
"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": { "all_patterns": {
"name": "all_patterns", "name": "all_patterns",
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.NavSpec.all_patterns", "path": "docforge.nav.resolver.NavSpec.all_patterns",
"signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>", "signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>",
"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", "name": "ResolvedNav",
"kind": "class", "kind": "class",
"path": "docforge.nav.resolver.ResolvedNav", "path": "docforge.nav.resolver.ResolvedNav",
"signature": "<bound method Class.signature of Class('ResolvedNav', 15, 63)>", "signature": "<bound method Class.signature of Class('ResolvedNav', 23, 76)>",
"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.", "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": { "members": {
"home": { "home": {
@@ -274,8 +281,8 @@
"name": "all_files", "name": "all_files",
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.ResolvedNav.all_files", "path": "docforge.nav.resolver.ResolvedNav.all_files",
"signature": "<bound method Function.signature of Function('all_files', 46, 63)>", "signature": "<bound method Function.signature of Function('all_files', 57, 76)>",
"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."
} }
} }
}, },
@@ -283,8 +290,8 @@
"name": "resolve_nav", "name": "resolve_nav",
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.resolve_nav", "path": "docforge.nav.resolver.resolve_nav",
"signature": "<bound method Function.signature of Function('resolve_nav', 66, 132)>", "signature": "<bound method Function.signature of Function('resolve_nav', 79, 150)>",
"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."
} }
} }
}, },
@@ -293,8 +300,15 @@
"kind": "module", "kind": "module",
"path": "docforge.nav.spec", "path": "docforge.nav.spec",
"signature": null, "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": { "members": {
"annotations": {
"name": "annotations",
"kind": "alias",
"path": "docforge.nav.spec.annotations",
"signature": "<bound method Alias.signature of Alias('annotations', '__future__.annotations')>",
"docstring": null
},
"Path": { "Path": {
"name": "Path", "name": "Path",
"kind": "alias", "kind": "alias",
@@ -313,7 +327,7 @@
"name": "NavSpec", "name": "NavSpec",
"kind": "class", "kind": "class",
"path": "docforge.nav.spec.NavSpec", "path": "docforge.nav.spec.NavSpec",
"signature": "<bound method Class.signature of Class('NavSpec', 14, 119)>", "signature": "<bound method Class.signature of Class('NavSpec', 25, 136)>",
"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``.", "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": { "members": {
"home": { "home": {
@@ -341,15 +355,15 @@
"name": "load", "name": "load",
"kind": "function", "kind": "function",
"path": "docforge.nav.spec.NavSpec.load", "path": "docforge.nav.spec.NavSpec.load",
"signature": "<bound method Function.signature of Function('load', 51, 101)>", "signature": "<bound method Function.signature of Function('load', 65, 117)>",
"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": { "all_patterns": {
"name": "all_patterns", "name": "all_patterns",
"kind": "function", "kind": "function",
"path": "docforge.nav.spec.NavSpec.all_patterns", "path": "docforge.nav.spec.NavSpec.all_patterns",
"signature": "<bound method Function.signature of Function('all_patterns', 103, 119)>", "signature": "<bound method Function.signature of Function('all_patterns', 119, 136)>",
"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."
} }
} }
}, },
@@ -357,8 +371,52 @@
"name": "load_nav_spec", "name": "load_nav_spec",
"kind": "function", "kind": "function",
"path": "docforge.nav.spec.load_nav_spec", "path": "docforge.nav.spec.load_nav_spec",
"signature": "<bound method Function.signature of Function('load_nav_spec', 122, 151)>", "signature": "<bound method Function.signature of Function('load_nav_spec', 139, 170)>",
"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."
}
}
},
"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": "<bound method Alias.signature of Alias('re', 're')>",
"docstring": null
},
"Callable": {
"name": "Callable",
"kind": "alias",
"path": "docforge.nav.wiki.Callable",
"signature": "<bound method Alias.signature of Alias('Callable', 'collections.abc.Callable')>",
"docstring": null
},
"Path": {
"name": "Path",
"kind": "alias",
"path": "docforge.nav.wiki.Path",
"signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
"docstring": null
},
"Any": {
"name": "Any",
"kind": "alias",
"path": "docforge.nav.wiki.Any",
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
},
"build_wiki_nav": {
"name": "build_wiki_nav",
"kind": "function",
"path": "docforge.nav.wiki.build_wiki_nav",
"signature": "<bound method Function.signature of Function('build_wiki_nav', 28, 76)>",
"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."
} }
} }
} }

10
docs/mcp/modules/docforge.nav.mkdocs.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.nav.mkdocs", "module": "docforge.nav.mkdocs",
"content": { "content": {
"path": "docforge.nav.mkdocs", "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": { "objects": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -44,7 +44,7 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.mkdocs.ResolvedNav.all_files", "path": "docforge.nav.mkdocs.ResolvedNav.all_files",
"signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>", "signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>",
"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", "name": "MkDocsNavEmitter",
"kind": "class", "kind": "class",
"path": "docforge.nav.mkdocs.MkDocsNavEmitter", "path": "docforge.nav.mkdocs.MkDocsNavEmitter",
"signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 15, 81)>", "signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 23, 94)>",
"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.", "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": { "members": {
"emit": { "emit": {
"name": "emit", "name": "emit",
"kind": "function", "kind": "function",
"path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit", "path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit",
"signature": "<bound method Function.signature of Function('emit', 23, 51)>", "signature": "<bound method Function.signature of Function('emit', 31, 61)>",
"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."
} }
} }
} }

16
docs/mcp/modules/docforge.nav.resolver.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.nav.resolver", "module": "docforge.nav.resolver",
"content": { "content": {
"path": "docforge.nav.resolver", "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": { "objects": {
"glob": { "glob": {
"name": "glob", "name": "glob",
@@ -58,14 +58,14 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.NavSpec.load", "path": "docforge.nav.resolver.NavSpec.load",
"signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>", "signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>",
"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": { "all_patterns": {
"name": "all_patterns", "name": "all_patterns",
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.NavSpec.all_patterns", "path": "docforge.nav.resolver.NavSpec.all_patterns",
"signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>", "signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>",
"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", "name": "ResolvedNav",
"kind": "class", "kind": "class",
"path": "docforge.nav.resolver.ResolvedNav", "path": "docforge.nav.resolver.ResolvedNav",
"signature": "<bound method Class.signature of Class('ResolvedNav', 15, 63)>", "signature": "<bound method Class.signature of Class('ResolvedNav', 23, 76)>",
"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.", "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": { "members": {
"home": { "home": {
@@ -94,8 +94,8 @@
"name": "all_files", "name": "all_files",
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.ResolvedNav.all_files", "path": "docforge.nav.resolver.ResolvedNav.all_files",
"signature": "<bound method Function.signature of Function('all_files', 46, 63)>", "signature": "<bound method Function.signature of Function('all_files', 57, 76)>",
"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."
} }
} }
}, },
@@ -103,8 +103,8 @@
"name": "resolve_nav", "name": "resolve_nav",
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.resolve_nav", "path": "docforge.nav.resolver.resolve_nav",
"signature": "<bound method Function.signature of Function('resolve_nav', 66, 132)>", "signature": "<bound method Function.signature of Function('resolve_nav', 79, 150)>",
"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."
} }
} }
} }

23
docs/mcp/modules/docforge.nav.spec.json
View File

@@ -2,8 +2,15 @@
"module": "docforge.nav.spec", "module": "docforge.nav.spec",
"content": { "content": {
"path": "docforge.nav.spec", "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": { "objects": {
"annotations": {
"name": "annotations",
"kind": "alias",
"path": "docforge.nav.spec.annotations",
"signature": "<bound method Alias.signature of Alias('annotations', '__future__.annotations')>",
"docstring": null
},
"Path": { "Path": {
"name": "Path", "name": "Path",
"kind": "alias", "kind": "alias",
@@ -22,7 +29,7 @@
"name": "NavSpec", "name": "NavSpec",
"kind": "class", "kind": "class",
"path": "docforge.nav.spec.NavSpec", "path": "docforge.nav.spec.NavSpec",
"signature": "<bound method Class.signature of Class('NavSpec', 14, 119)>", "signature": "<bound method Class.signature of Class('NavSpec', 25, 136)>",
"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``.", "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": { "members": {
"home": { "home": {
@@ -50,15 +57,15 @@
"name": "load", "name": "load",
"kind": "function", "kind": "function",
"path": "docforge.nav.spec.NavSpec.load", "path": "docforge.nav.spec.NavSpec.load",
"signature": "<bound method Function.signature of Function('load', 51, 101)>", "signature": "<bound method Function.signature of Function('load', 65, 117)>",
"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": { "all_patterns": {
"name": "all_patterns", "name": "all_patterns",
"kind": "function", "kind": "function",
"path": "docforge.nav.spec.NavSpec.all_patterns", "path": "docforge.nav.spec.NavSpec.all_patterns",
"signature": "<bound method Function.signature of Function('all_patterns', 103, 119)>", "signature": "<bound method Function.signature of Function('all_patterns', 119, 136)>",
"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."
} }
} }
}, },
@@ -66,8 +73,8 @@
"name": "load_nav_spec", "name": "load_nav_spec",
"kind": "function", "kind": "function",
"path": "docforge.nav.spec.load_nav_spec", "path": "docforge.nav.spec.load_nav_spec",
"signature": "<bound method Function.signature of Function('load_nav_spec', 122, 151)>", "signature": "<bound method Function.signature of Function('load_nav_spec', 139, 170)>",
"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."
} }
} }
} }

44
docs/mcp/modules/docforge.nav.wiki.json Normal file
View File

@@ -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": "<bound method Alias.signature of Alias('re', 're')>",
"docstring": null
},
"Callable": {
"name": "Callable",
"kind": "alias",
"path": "docforge.nav.wiki.Callable",
"signature": "<bound method Alias.signature of Alias('Callable', 'collections.abc.Callable')>",
"docstring": null
},
"Path": {
"name": "Path",
"kind": "alias",
"path": "docforge.nav.wiki.Path",
"signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
"docstring": null
},
"Any": {
"name": "Any",
"kind": "alias",
"path": "docforge.nav.wiki.Any",
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
},
"build_wiki_nav": {
"name": "build_wiki_nav",
"kind": "function",
"path": "docforge.nav.wiki.build_wiki_nav",
"signature": "<bound method Function.signature of Function('build_wiki_nav', 28, 76)>",
"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."
}
}
}
}

2
docs/mcp/modules/docforge.renderers.base.json
View File

@@ -23,7 +23,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.base.Project", "path": "docforge.renderers.base.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"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": { "members": {
"name": { "name": {
"name": "name", "name": "name",

26
docs/mcp/modules/docforge.renderers.json
View File

@@ -23,14 +23,14 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.MkDocsRenderer.generate_sources", "path": "docforge.renderers.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, 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": { "generate_readme": {
"name": "generate_readme", "name": "generate_readme",
"kind": "function", "kind": "function",
"path": "docforge.renderers.MkDocsRenderer.generate_readme", "path": "docforge.renderers.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>", "signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\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", "kind": "class",
"path": "docforge.renderers.base.Project", "path": "docforge.renderers.base.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -203,7 +203,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.DocObject", "path": "docforge.renderers.mcp_renderer.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -252,7 +252,7 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.DocObject.add_member", "path": "docforge.renderers.mcp_renderer.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: 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": { "get_member": {
"name": "get_member", "name": "get_member",
@@ -275,7 +275,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.Module", "path": "docforge.renderers.mcp_renderer.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
"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": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -326,7 +326,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.Project", "path": "docforge.renderers.mcp_renderer.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -423,7 +423,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mkdocs_renderer.Module", "path": "docforge.renderers.mkdocs_renderer.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
"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": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -474,7 +474,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mkdocs_renderer.Project", "path": "docforge.renderers.mkdocs_renderer.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -524,7 +524,7 @@
"name": "MkDocsRenderer", "name": "MkDocsRenderer",
"kind": "class", "kind": "class",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
"signature": "<bound method Class.signature of Class('MkDocsRenderer', 23, 307)>", "signature": "<bound method Class.signature of Class('MkDocsRenderer', 23, 306)>",
"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.", "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": { "members": {
"name": { "name": {
@@ -539,14 +539,14 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 37, 78)>", "signature": "<bound method Function.signature of Function('generate_sources', 37, 78)>",
"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": { "generate_readme": {
"name": "generate_readme", "name": "generate_readme",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme",
"signature": "<bound method Function.signature of Function('generate_readme', 80, 145)>", "signature": "<bound method Function.signature of Function('generate_readme', 80, 144)>",
"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`."
} }
} }
} }

8
docs/mcp/modules/docforge.renderers.mcp_renderer.json
View File

@@ -23,7 +23,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.DocObject", "path": "docforge.renderers.mcp_renderer.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -72,7 +72,7 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.DocObject.add_member", "path": "docforge.renderers.mcp_renderer.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: 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": { "get_member": {
"name": "get_member", "name": "get_member",
@@ -95,7 +95,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.Module", "path": "docforge.renderers.mcp_renderer.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
"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": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -146,7 +146,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.Project", "path": "docforge.renderers.mcp_renderer.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"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": { "members": {
"name": { "name": {
"name": "name", "name": "name",

12
docs/mcp/modules/docforge.renderers.mkdocs_renderer.json
View File

@@ -16,7 +16,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mkdocs_renderer.Module", "path": "docforge.renderers.mkdocs_renderer.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
"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": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -67,7 +67,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mkdocs_renderer.Project", "path": "docforge.renderers.mkdocs_renderer.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"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": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -117,7 +117,7 @@
"name": "MkDocsRenderer", "name": "MkDocsRenderer",
"kind": "class", "kind": "class",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
"signature": "<bound method Class.signature of Class('MkDocsRenderer', 23, 307)>", "signature": "<bound method Class.signature of Class('MkDocsRenderer', 23, 306)>",
"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.", "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": { "members": {
"name": { "name": {
@@ -132,14 +132,14 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 37, 78)>", "signature": "<bound method Function.signature of Function('generate_sources', 37, 78)>",
"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": { "generate_readme": {
"name": "generate_readme", "name": "generate_readme",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme",
"signature": "<bound method Function.signature of Function('generate_readme', 80, 145)>", "signature": "<bound method Function.signature of Function('generate_readme', 80, 144)>",
"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`."
} }
} }
} }

10
docs/mcp/modules/docforge.servers.json
View File

@@ -9,7 +9,7 @@
"kind": "class", "kind": "class",
"path": "docforge.servers.MCPServer", "path": "docforge.servers.MCPServer",
"signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.mcp_server.MCPServer')>", "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.mcp_server.MCPServer')>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.", "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": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -39,7 +39,7 @@
"kind": "module", "kind": "module",
"path": "docforge.servers.mcp_server", "path": "docforge.servers.mcp_server",
"signature": null, "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": { "members": {
"annotations": { "annotations": {
"name": "annotations", "name": "annotations",
@@ -87,8 +87,8 @@
"name": "MCPServer", "name": "MCPServer",
"kind": "class", "kind": "class",
"path": "docforge.servers.mcp_server.MCPServer", "path": "docforge.servers.mcp_server.MCPServer",
"signature": "<bound method Class.signature of Class('MCPServer', 19, 134)>", "signature": "<bound method Class.signature of Class('MCPServer', 29, 152)>",
"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": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -108,7 +108,7 @@
"name": "run", "name": "run",
"kind": "function", "kind": "function",
"path": "docforge.servers.mcp_server.MCPServer.run", "path": "docforge.servers.mcp_server.MCPServer.run",
"signature": "<bound method Function.signature of Function('run', 122, 134)>", "signature": "<bound method Function.signature of Function('run', 140, 152)>",
"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`." "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`."
} }
} }

8
docs/mcp/modules/docforge.servers.mcp_server.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.servers.mcp_server", "module": "docforge.servers.mcp_server",
"content": { "content": {
"path": "docforge.servers.mcp_server", "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": { "objects": {
"annotations": { "annotations": {
"name": "annotations", "name": "annotations",
@@ -50,8 +50,8 @@
"name": "MCPServer", "name": "MCPServer",
"kind": "class", "kind": "class",
"path": "docforge.servers.mcp_server.MCPServer", "path": "docforge.servers.mcp_server.MCPServer",
"signature": "<bound method Class.signature of Class('MCPServer', 19, 134)>", "signature": "<bound method Class.signature of Class('MCPServer', 29, 152)>",
"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": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -71,7 +71,7 @@
"name": "run", "name": "run",
"kind": "function", "kind": "function",
"path": "docforge.servers.mcp_server.MCPServer.run", "path": "docforge.servers.mcp_server.MCPServer.run",
"signature": "<bound method Function.signature of Function('run', 122, 134)>", "signature": "<bound method Function.signature of Function('run', 140, 152)>",
"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`." "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`."
} }
} }

50
docs/mcp/nav.json
View File

@@ -1,94 +1,98 @@
[ [
{ {
"module": "docforge", "module": "docforge",
"resource": "doc://modules/docforge" "resource": "docs://modules/docforge"
}, },
{ {
"module": "docforge.cli", "module": "docforge.cli",
"resource": "doc://modules/docforge.cli" "resource": "docs://modules/docforge.cli"
}, },
{ {
"module": "docforge.cli.api_utils", "module": "docforge.cli.api_utils",
"resource": "doc://modules/docforge.cli.api_utils" "resource": "docs://modules/docforge.cli.api_utils"
}, },
{ {
"module": "docforge.cli.commands", "module": "docforge.cli.commands",
"resource": "doc://modules/docforge.cli.commands" "resource": "docs://modules/docforge.cli.commands"
}, },
{ {
"module": "docforge.cli.main", "module": "docforge.cli.main",
"resource": "doc://modules/docforge.cli.main" "resource": "docs://modules/docforge.cli.main"
}, },
{ {
"module": "docforge.cli.mcp_utils", "module": "docforge.cli.mcp_utils",
"resource": "doc://modules/docforge.cli.mcp_utils" "resource": "docs://modules/docforge.cli.mcp_utils"
}, },
{ {
"module": "docforge.cli.mkdocs_utils", "module": "docforge.cli.mkdocs_utils",
"resource": "doc://modules/docforge.cli.mkdocs_utils" "resource": "docs://modules/docforge.cli.mkdocs_utils"
}, },
{ {
"module": "docforge.loaders", "module": "docforge.loaders",
"resource": "doc://modules/docforge.loaders" "resource": "docs://modules/docforge.loaders"
}, },
{ {
"module": "docforge.loaders.griffe_loader", "module": "docforge.loaders.griffe_loader",
"resource": "doc://modules/docforge.loaders.griffe_loader" "resource": "docs://modules/docforge.loaders.griffe_loader"
}, },
{ {
"module": "docforge.models", "module": "docforge.models",
"resource": "doc://modules/docforge.models" "resource": "docs://modules/docforge.models"
}, },
{ {
"module": "docforge.models.module", "module": "docforge.models.module",
"resource": "doc://modules/docforge.models.module" "resource": "docs://modules/docforge.models.module"
}, },
{ {
"module": "docforge.models.object", "module": "docforge.models.object",
"resource": "doc://modules/docforge.models.object" "resource": "docs://modules/docforge.models.object"
}, },
{ {
"module": "docforge.models.project", "module": "docforge.models.project",
"resource": "doc://modules/docforge.models.project" "resource": "docs://modules/docforge.models.project"
}, },
{ {
"module": "docforge.nav", "module": "docforge.nav",
"resource": "doc://modules/docforge.nav" "resource": "docs://modules/docforge.nav"
}, },
{ {
"module": "docforge.nav.mkdocs", "module": "docforge.nav.mkdocs",
"resource": "doc://modules/docforge.nav.mkdocs" "resource": "docs://modules/docforge.nav.mkdocs"
}, },
{ {
"module": "docforge.nav.resolver", "module": "docforge.nav.resolver",
"resource": "doc://modules/docforge.nav.resolver" "resource": "docs://modules/docforge.nav.resolver"
}, },
{ {
"module": "docforge.nav.spec", "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", "module": "docforge.renderers",
"resource": "doc://modules/docforge.renderers" "resource": "docs://modules/docforge.renderers"
}, },
{ {
"module": "docforge.renderers.base", "module": "docforge.renderers.base",
"resource": "doc://modules/docforge.renderers.base" "resource": "docs://modules/docforge.renderers.base"
}, },
{ {
"module": "docforge.renderers.mcp_renderer", "module": "docforge.renderers.mcp_renderer",
"resource": "doc://modules/docforge.renderers.mcp_renderer" "resource": "docs://modules/docforge.renderers.mcp_renderer"
}, },
{ {
"module": "docforge.renderers.mkdocs_renderer", "module": "docforge.renderers.mkdocs_renderer",
"resource": "doc://modules/docforge.renderers.mkdocs_renderer" "resource": "docs://modules/docforge.renderers.mkdocs_renderer"
}, },
{ {
"module": "docforge.servers", "module": "docforge.servers",
"resource": "doc://modules/docforge.servers" "resource": "docs://modules/docforge.servers"
}, },
{ {
"module": "docforge.servers.mcp_server", "module": "docforge.servers.mcp_server",
"resource": "doc://modules/docforge.servers.mcp_server" "resource": "docs://modules/docforge.servers.mcp_server"
} }
] ]

10
docs/wiki/01_overview.md
View File

@@ -11,7 +11,7 @@ and assembles a single MkDocs site from all available material.
| `lib` | GSDFC docstrings | `docs/lib/**` rendered markdown | | `lib` | GSDFC docstrings | `docs/lib/**` rendered markdown |
| `api` | OpenAPI JSON spec | `docs/api/**` rendered markdown | | `api` | OpenAPI JSON spec | `docs/api/**` rendered markdown |
| `wiki` | Hand-written markdown | `docs/wiki/**` (unchanged) | | `wiki` | Hand-written markdown | `docs/wiki/**` (unchanged) |
| `mcp` | Griffe + renderers | `docs/mcp/**` structured files | | `mcp` | GSDFC docstrings + renderers | `docs/mcp/**` structured JSON |
## Combined build ## 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`. 3. The wiki `index.md` becomes the site `Home`.
Hand-written wiki content is never overwritten or regenerated — only its Hand-written wiki content is never overwritten or regenerated — only its
navigation is derived automatically. 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).

10
docs/wiki/02_architecture.md
View File

@@ -7,8 +7,7 @@ bottom through the CLI.
The `docforge/loaders` package wraps `griffe` to extract modules, functions, The `docforge/loaders` package wraps `griffe` to extract modules, functions,
classes, and Google-style docstring sections. Loaded data is normalized into classes, and Google-style docstring sections. Loaded data is normalized into
the object model under `docforge/models` (`Module`, `Object`, `Project`, the object model under `docforge/models` (`Project`, `Module`, `DocObject`).
`Field`).
## Navigation ## Navigation
@@ -23,6 +22,13 @@ file structure via `build_wiki_nav`.
- `MkDocsRenderer` → `docs/lib/**` reference markdown - `MkDocsRenderer` → `docs/lib/**` reference markdown
- `MCPRenderer` → `docs/mcp/**` structured documentation - `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 ## CLI
`docforge/cli` wires it all together: `docforge/cli` wires it all together:

15
docs/wiki/03_conventions.md
View File

@@ -6,6 +6,19 @@ All documented source uses the Google-Styled Doc-Forge Convention (GSDFC):
`Args:`, `Returns:`, `Raises:`, and `Attributes:` sections with properly typed `Args:`, `Returns:`, `Raises:`, and `Attributes:` sections with properly typed
signatures. 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 ## `.pyi` stubs
Every module ships a matching `.pyi` stub kept in sync with the `.py` 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 ## Wiki pages
- Hand-written markdown lives in `docs/wiki/**` and is never generated. - 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: - Nested directories become nested navigation groups:
`05_development/01_environment.md` → group *Development*. `05_development/01_environment.md` → group *Development*.
- `index.md` is the site `Home` at the root, and a section root inside a - `index.md` is the site `Home` at the root, and a section root inside a

14
docs/wiki/04_iterative_workflow.md
View File

@@ -8,11 +8,14 @@ A docs build runs through the CLI in a single pass.
# Library reference only # Library reference only
doc-forge build --mkdocs --module docforge 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 doc-forge build --wiki --mkdocs --module docforge
# Wiki only — no module required # Wiki only — no module required
doc-forge build --wiki --site-name docforge doc-forge build --wiki --site-name docforge
# MCP structured bundle
doc-forge build --mcp --module docforge
``` ```
## What a combined build does ## What a combined build does
@@ -29,5 +32,12 @@ doc-forge build --wiki --site-name docforge
```bash ```bash
doc-forge build --wiki --mkdocs --module docforge 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
``` ```

5
docs/wiki/05_development/01_environment.md
View File

@@ -8,7 +8,7 @@ python -m venv .venv
pip install -e . pip install -e .
``` ```
Requires Python 3.11+. Requires Python 3.10+ (per `pyproject.toml`).
## Dependencies ## Dependencies
@@ -17,4 +17,5 @@ Development extras include:
- `pytest`, `pytest-cov` — test suite and coverage - `pytest`, `pytest-cov` — test suite and coverage
- `ruff` — lint and format checking - `ruff` — lint and format checking
- `black` — auto-formatting - `black` — auto-formatting
- `mypy` — strict typing checks - `mypy` — strict typing checks
- `pydoclint` — docstring ↔ signature consistency checks

1
docs/wiki/05_development/02_quality_gates.md
View File

@@ -7,6 +7,7 @@ Run all checks before pushing:
.venv\Scripts\python.exe -m ruff check docforge tests .venv\Scripts\python.exe -m ruff check docforge tests
.venv\Scripts\python.exe -m black --check docforge tests .venv\Scripts\python.exe -m black --check docforge tests
.venv\Scripts\python.exe -m mypy docforge .venv\Scripts\python.exe -m mypy docforge
.venv\Scripts\pydoclint.exe docforge
``` ```
## Test layout ## Test layout

108
docs/wiki/05_development/03_gsdfc_guide.md Normal file
View File

@@ -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.

51
docs/wiki/05_development/04_mcp_guide.md Normal file
View File

@@ -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.

7
docs/wiki/index.md
View File

@@ -22,17 +22,20 @@ OpenAPI-based API docs.
| Section | Description | | Section | Description |
|----------------------------------------------| -------------------------------------------------- | |----------------------------------------------| -------------------------------------------------- |
| [Overview](01_overview.md) | What docforge is and how it fits the pipeline | | [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 | | [Conventions](03_conventions.md) | GSDFC, `.pyi` stubs, and template conventions |
| [Iterative Workflow](04_iterative_workflow.md) | How a docs build runs end to end | | [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 | | [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 ## 🔗 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/` - **Wiki Kind:** hand-written content lives in `docs/wiki/`
- **MCP Bundle:** generated by `doc-forge build --mcp --module docforge` into `docs/mcp/`
--- ---

2
mkdocs.yml
View File

@@ -77,6 +77,8 @@ nav:
- Development: - Development:
- Environment: wiki/05_development/01_environment.md - Environment: wiki/05_development/01_environment.md
- Quality Gates: wiki/05_development/02_quality_gates.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: - Loaders:
- lib/loaders/index.md - lib/loaders/index.md
- lib/loaders/griffe_loader.md - lib/loaders/griffe_loader.md

9
pyproject.toml
View File

@@ -83,6 +83,7 @@ dev = [
"black>=23.0.0", "black>=23.0.0",
"ruff>=0.3.0", "ruff>=0.3.0",
"mypy>=1.8.0", "mypy>=1.8.0",
"pydoclint>=0.9.1",
"build>=1.0.0", "build>=1.0.0",
"twine>=4.0.0", "twine>=4.0.0",
"pre-commit>=3.4.0", "pre-commit>=3.4.0",
@@ -188,6 +189,14 @@ module = [
ignore_missing_imports = true 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] [tool.coverage.run]
source = ["docforge"] source = ["docforge"]
omit = [ omit = [