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
```
## Include a hand-written wiki in the MkDocs site:
```bash
doc-forge build --wiki --mkdocs --module my_package
```
## Build wiki pages only (no module required):
```bash
doc-forge build --wiki --site-name my_package
```
## Serve MkDocs locally:
```bash
@@ -130,7 +142,9 @@ GSDFC defines how docstrings must be written so they render correctly in MkDocs
- Use **Markdown headings** at package and module level.
- Use **Google-style structured sections** at class, function, and method level.
- Use type hints in signatures instead of duplicating types in prose.
- Use type hints in signatures.
- Use parenthesized types in prose entries (`name (Type):`) that match the
signature types. This keeps docstrings self-contained and machine-parseable.
- Write summaries in imperative form.
- Sections are separated by `---`
@@ -190,7 +204,10 @@ Example:
engine.run()
```
Avoid fenced code blocks inside structured sections.
Avoid fenced code blocks inside argument descriptions and other prose lines.
Inside `Example:` sections, fenced `python` code blocks are allowed and must be
indented four spaces, matching the examples below.
---

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
```
## Include a hand-written wiki in the MkDocs site:
```bash
doc-forge build --wiki --mkdocs --module my_package
```
## Build wiki pages only (no module required):
```bash
doc-forge build --wiki --site-name my_package
```
## Serve MkDocs locally:
```bash
@@ -129,7 +141,9 @@ GSDFC defines how docstrings must be written so they render correctly in MkDocs
- Use **Markdown headings** at package and module level.
- Use **Google-style structured sections** at class, function, and method level.
- Use type hints in signatures instead of duplicating types in prose.
- Use type hints in signatures.
- Use parenthesized types in prose entries (`name (Type):`) that match the
signature types. This keeps docstrings self-contained and machine-parseable.
- Write summaries in imperative form.
- Sections are separated by `---`
@@ -189,7 +203,10 @@ Example:
engine.run()
```
Avoid fenced code blocks inside structured sections.
Avoid fenced code blocks inside argument descriptions and other prose lines.
Inside `Example:` sections, fenced `python` code blocks are allowed and must be
indented four spaces, matching the examples below.
---

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

40
docforge/cli/commands.py
View File

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

5
docforge/cli/commands.pyi
View File

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

12
docforge/cli/mcp_utils.py
View File

@@ -2,6 +2,16 @@
# Summary
Utilities for working with MCP in the doc-forge CLI.
---
Notes:
- `generate_resources` produces the bundle consumed by `MCPServer`:
`index.json`, `nav.json`, and per-module resources under `modules/`.
- Resource URIs use the `docs://` scheme: `docs://index`, `docs://nav`,
and `docs://modules/{module}`.
---
"""
from pathlib import Path
@@ -26,7 +36,7 @@ def generate_resources(module: str, project_name: str | None, out_dir: Path) ->
Python module import path used as the entry point for
documentation generation.
project_name (Optional[str]):
project_name (str | None):
Optional override for the project name used in generated
documentation metadata.

46
docforge/cli/mkdocs_utils.py
View File

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

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

3
docforge/loaders/griffe_loader.pyi
View File

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

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

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

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
doc-forge to represent a documented codebase. A `Project` aggregates multiple
modules and provides access to them through a unified interface.
---
Notes:
- Modules are keyed by their dotted import path.
- Objects are renderer-agnostic; the same model feeds every renderer.
---
"""
from collections.abc import Iterable
@@ -24,7 +32,7 @@ class Project:
name (str):
Name of the project.
modules (Dict[str, Module]):
modules (dict[str, Module]):
Mapping of module paths to `Module` instances.
"""
@@ -35,6 +43,14 @@ class Project:
Args:
name (str):
Name used to identify the documentation project.
Example:
Create a project and register a module:
```python
project = Project("mypackage")
project.add_module(module)
```
"""
self.name = name
self.modules: dict[str, Module] = {}

27
docforge/nav/mkdocs.py
View File

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

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

39
docforge/nav/spec.py
View File

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

14
docforge/nav/wiki.py
View File

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

32
docforge/nav/wiki.pyi
View File

@@ -1,3 +1,4 @@
from collections.abc import Callable
from pathlib import Path
from typing import Any
@@ -5,11 +6,36 @@ def build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]:
"""
Derive an MkDocs navigation block from a wiki directory.
Args:
wiki_dir (Path):
Path to the hand-written wiki directory.
Returns:
Wiki navigation entries compatible with the MkDocs
`nav` configuration.
list[dict[str, Any]]:
Wiki navigation entries compatible with the MkDocs `nav`
configuration.
Raises:
FileNotFoundError: if the wiki directory does not exist
FileNotFoundError:
If the wiki directory does not exist.
"""
...
def _render_entries(
base_dir: Path,
rel: Callable[[Path], str],
) -> list[dict[str, Any]]:
"""
Render navigation entries for the children of a wiki directory.
Args:
base_dir (Path):
Directory whose children are rendered.
rel (Callable[[Path], str]):
Callable converting a wiki file path into a docs-relative path.
Returns:
list[dict[str, Any]]:
Navigation entries for `base_dir` in natural sort order.
"""
...

8
docforge/renderers/mcp_renderer.py
View File

@@ -49,7 +49,7 @@ class MCPRenderer:
nav.append(
{
"module": module.path,
"resource": f"doc://modules/{module.path}",
"resource": f"docs://modules/{module.path}",
}
)
@@ -101,7 +101,7 @@ class MCPRenderer:
Module instance to convert.
Returns:
Dict:
dict:
Dictionary representing the module and its documented objects.
"""
data: dict = {
@@ -124,7 +124,7 @@ class MCPRenderer:
Documentation object to convert.
Returns:
Dict:
dict:
Dictionary describing the object and any nested members.
"""
data: dict = {
@@ -149,7 +149,7 @@ class MCPRenderer:
Serialize data to formatted JSON.
Args:
data (Dict):
data (dict):
Dictionary to serialize.
Returns:

19
docforge/renderers/mkdocs_renderer.py
View File

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

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
documentation bundles through the Model Context Protocol (MCP).
---
Notes:
- The served bundle is generated offline by `MCPRenderer`.
- Missing resources are reported as structured error dictionaries rather
than raising exceptions.
- The server exposes read-only resources and a single health-check tool.
---
"""
from __future__ import annotations
@@ -22,6 +32,14 @@ class MCPServer:
The server exposes documentation resources and diagnostic tools through
MCP endpoints backed by JSON files generated by the MCP renderer.
Attributes:
mcp_root (Path):
Directory containing the generated MCP documentation bundle.
app (FastMCP):
Underlying FastMCP application instance that registers resources
and tools.
"""
def __init__(self, mcp_root: Path, name: str) -> None:

5
docforge/servers/mcp_server.pyi
View File

@@ -4,7 +4,10 @@ from typing import Any, Literal
from mcp.server.fastmcp import FastMCP
class MCPServer:
"""MCP server for serving documentation."""
"""MCP server serving a pre-generated documentation bundle.
Exposes read-only documentation resources and a health-check tool.
"""
mcp_root: Path
app: FastMCP

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

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",
"type": "docforge-model",
"modules_count": 23,
"modules_count": 24,
"source": "docforge"
}

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

@@ -73,22 +73,22 @@
"name": "load_openapi_spec",
"kind": "function",
"path": "docforge.cli.api_utils.load_openapi_spec",
"signature": "<bound method Function.signature of Function('load_openapi_spec', 33, 63)>",
"docstring": "Load and validate an OpenAPI specification from a JSON file.\n\nArgs:\n spec_path: Path to the OpenAPI JSON specification file.\n\nReturns:\n dict:\n The parsed OpenAPI specification.\n\nRaises:\n click.ClickException:\n If the file cannot be read or the ``info`` block is invalid."
"signature": "<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):\n Path to the OpenAPI JSON specification file.\n\nReturns:\n dict:\n The parsed OpenAPI specification.\n\nRaises:\n click.ClickException:\n If the file cannot be read or the ``info`` block is invalid."
},
"derive_metadata": {
"name": "derive_metadata",
"kind": "function",
"path": "docforge.cli.api_utils.derive_metadata",
"signature": "<bound method Function.signature of Function('derive_metadata', 66, 89)>",
"docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec: Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec."
"signature": "<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 (dict):\n Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec."
},
"generate_api_sources": {
"name": "generate_api_sources",
"kind": "function",
"path": "docforge.cli.api_utils.generate_api_sources",
"signature": "<bound method Function.signature of Function('generate_api_sources', 92, 114)>",
"docstring": "Generate swagger-enabled Markdown sources and the spec copy.\n\nThe specification is written as ``openapi.json`` inside ``docs_dir`` and\nan ``index.md`` embedding the swagger UI is generated alongside it.\n\nArgs:\n spec: Parsed OpenAPI specification.\n docs_dir: Directory (for example ``docs/api``) where the swagger\n sources are written."
"signature": "<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 (dict):\n Parsed OpenAPI specification.\n docs_dir (Path):\n Directory (for example ``docs/api``) where the swagger\n sources are written."
},
"Any": {
"name": "Any",

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

@@ -2,7 +2,7 @@
"module": "docforge.cli.commands",
"content": {
"path": "docforge.cli.commands",
"docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.",
"docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.\n\n---\n\nNotes:\n - The `build` command validates requested modes before generating anything.\n - `--mkdocs`, `--api`, and `--wiki` share a single MkDocs build; `--mcp`\n generates a machine-readable bundle independently.\n\n---",
"objects": {
"Path": {
"name": "Path",
@@ -95,21 +95,21 @@
"kind": "function",
"path": "docforge.cli.commands.api_utils.load_openapi_spec",
"signature": "<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": {
"name": "derive_metadata",
"kind": "function",
"path": "docforge.cli.commands.api_utils.derive_metadata",
"signature": "<bound method Alias.signature of Alias('derive_metadata', 'docforge.cli.api_utils.derive_metadata')>",
"docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec: Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec."
"docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec (dict):\n Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec."
},
"generate_api_sources": {
"name": "generate_api_sources",
"kind": "function",
"path": "docforge.cli.commands.api_utils.generate_api_sources",
"signature": "<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": {
"name": "Any",
@@ -125,7 +125,7 @@
"kind": "module",
"path": "docforge.cli.commands.mcp_utils",
"signature": "<bound method Alias.signature of Alias('mcp_utils', 'docforge.cli.mcp_utils')>",
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.",
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.\n\n---\n\nNotes:\n - `generate_resources` produces the bundle consumed by `MCPServer`:\n `index.json`, `nav.json`, and per-module resources under `modules/`.\n - Resource URIs use the `docs://` scheme: `docs://index`, `docs://nav`,\n and `docs://modules/{module}`.\n\n---",
"members": {
"Path": {
"name": "Path",
@@ -146,21 +146,21 @@
"kind": "class",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader",
"signature": "<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": {
"load_project": {
"name": "load_project",
"kind": "function",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
},
"load_module": {
"name": "load_module",
"kind": "function",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module",
"signature": "<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",
"path": "docforge.cli.commands.mcp_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp_utils.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path | None):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n list[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
},
"MCPRenderer": {
"name": "MCPRenderer",
@@ -199,7 +199,7 @@
"kind": "class",
"path": "docforge.cli.commands.mcp_utils.MCPServer",
"signature": "<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": {
"mcp_root": {
"name": "mcp_root",
@@ -229,7 +229,7 @@
"kind": "function",
"path": "docforge.cli.commands.mcp_utils.generate_resources",
"signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp_utils.generate_resources')>",
"docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n project_name (Optional[str]):\n Optional override for the project name used in generated\n documentation metadata.\n\n out_dir (Path):\n Directory where MCP resources (index.json, nav.json, and module data)\n will be written."
"docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n project_name (str | None):\n Optional override for the project name used in generated\n documentation metadata.\n\n out_dir (Path):\n Directory where MCP resources (index.json, nav.json, and module data)\n will be written."
},
"serve": {
"name": "serve",
@@ -245,7 +245,7 @@
"kind": "module",
"path": "docforge.cli.commands.mkdocs_utils",
"signature": "<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": {
"os": {
"name": "os",
@@ -294,21 +294,21 @@
"kind": "class",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.\n\nAttributes:\n _loader (_GriffeLoader):\n Internal Griffe loader with dedicated module and line collections.",
"members": {
"load_project": {
"name": "load_project",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
},
"load_module": {
"name": "load_module",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module",
"signature": "<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",
"path": "docforge.cli.commands.mkdocs_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs_utils.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path | None):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n list[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
},
"MkDocsNavEmitter": {
"name": "MkDocsNavEmitter",
@@ -331,23 +331,30 @@
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit",
"signature": "<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": {
"name": "load_nav_spec",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.load_nav_spec",
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs_utils.load_nav_spec')>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid."
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path (Path):\n Path to the navigation specification file.\n\nReturns:\n NavSpec:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid."
},
"resolve_nav": {
"name": "resolve_nav",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.resolve_nav",
"signature": "<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": {
"name": "MkDocsRenderer",
@@ -368,14 +375,14 @@
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder."
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool | None):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<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",
"path": "docforge.cli.commands.mkdocs_utils.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>",
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``."
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``."
},
"generate_config": {
"name": "generate_config",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.generate_config",
"signature": "<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": {
"name": "build",
@@ -414,21 +421,93 @@
"kind": "class",
"path": "docforge.cli.commands.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.\n\nAttributes:\n _loader (_GriffeLoader):\n Internal Griffe loader with dedicated module and line collections.",
"members": {
"load_project": {
"name": "load_project",
"kind": "function",
"path": "docforge.cli.commands.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
},
"load_module": {
"name": "load_module",
"kind": "function",
"path": "docforge.cli.commands.GriffeLoader.load_module",
"signature": "<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",
"kind": "function",
"path": "docforge.cli.commands.build",
"signature": "<bound method Function.signature of Function('build', 28, 223)>",
"docstring": "Build documentation artifacts.\n\nThis command performs the full documentation build pipeline:\nstyle of the selected platform, generates renderer-specific\ndocumentation sources, and optionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites for library reference docs\n- Swagger-enabled API docs generated from an OpenAPI spec\n- MCP structured documentation resources\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs library documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (Optional[str]):\n Python module import path to document.\n\n openapi_spec (Optional[Path]):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (Optional[str]):\n Optional override for the project name.\n\n site_name (Optional[str]):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Optional[Path]):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
"signature": "<bound method Function.signature of Function('build', 38, 260)>",
"docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds or serves the final output.\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites for library reference docs\n- Swagger-enabled API docs generated from an OpenAPI spec\n- Hand-written wiki pages included in the MkDocs site\n- MCP structured documentation resources\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` are combined into a single MkDocs\n build, while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs library documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Include a hand-written wiki directory in the MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
},
"serve": {
"name": "serve",
"kind": "function",
"path": "docforge.cli.commands.serve",
"signature": "<bound method Function.signature of Function('serve', 226, 287)>",
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (Optional[str]):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided."
"signature": "<bound method Function.signature of Function('serve', 263, 324)>",
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided."
},
"tree": {
"name": "tree",
"kind": "function",
"path": "docforge.cli.commands.tree",
"signature": "<bound method Function.signature of Function('tree', 290, 326)>",
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (Optional[str]):\n Optional name to display as the project root."
},
"Any": {
"name": "Any",
"kind": "alias",
"path": "docforge.cli.commands.Any",
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
"signature": "<bound method Function.signature of Function('tree', 327, 363)>",
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (str | None):\n Optional name to display as the project root."
},
"Group": {
"name": "Group",

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

@@ -103,22 +103,22 @@
"name": "load_openapi_spec",
"kind": "function",
"path": "docforge.cli.api_utils.load_openapi_spec",
"signature": "<bound method Function.signature of Function('load_openapi_spec', 33, 63)>",
"docstring": "Load and validate an OpenAPI specification from a JSON file.\n\nArgs:\n spec_path: Path to the OpenAPI JSON specification file.\n\nReturns:\n dict:\n The parsed OpenAPI specification.\n\nRaises:\n click.ClickException:\n If the file cannot be read or the ``info`` block is invalid."
"signature": "<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):\n Path to the OpenAPI JSON specification file.\n\nReturns:\n dict:\n The parsed OpenAPI specification.\n\nRaises:\n click.ClickException:\n If the file cannot be read or the ``info`` block is invalid."
},
"derive_metadata": {
"name": "derive_metadata",
"kind": "function",
"path": "docforge.cli.api_utils.derive_metadata",
"signature": "<bound method Function.signature of Function('derive_metadata', 66, 89)>",
"docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec: Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec."
"signature": "<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 (dict):\n Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec."
},
"generate_api_sources": {
"name": "generate_api_sources",
"kind": "function",
"path": "docforge.cli.api_utils.generate_api_sources",
"signature": "<bound method Function.signature of Function('generate_api_sources', 92, 114)>",
"docstring": "Generate swagger-enabled Markdown sources and the spec copy.\n\nThe specification is written as ``openapi.json`` inside ``docs_dir`` and\nan ``index.md`` embedding the swagger UI is generated alongside it.\n\nArgs:\n spec: Parsed OpenAPI specification.\n docs_dir: Directory (for example ``docs/api``) where the swagger\n sources are written."
"signature": "<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 (dict):\n Parsed OpenAPI specification.\n docs_dir (Path):\n Directory (for example ``docs/api``) where the swagger\n sources are written."
},
"Any": {
"name": "Any",
@@ -134,7 +134,7 @@
"kind": "module",
"path": "docforge.cli.commands",
"signature": null,
"docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.",
"docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.\n\n---\n\nNotes:\n - The `build` command validates requested modes before generating anything.\n - `--mkdocs`, `--api`, and `--wiki` share a single MkDocs build; `--mcp`\n generates a machine-readable bundle independently.\n\n---",
"members": {
"Path": {
"name": "Path",
@@ -227,21 +227,21 @@
"kind": "function",
"path": "docforge.cli.commands.api_utils.load_openapi_spec",
"signature": "<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": {
"name": "derive_metadata",
"kind": "function",
"path": "docforge.cli.commands.api_utils.derive_metadata",
"signature": "<bound method Alias.signature of Alias('derive_metadata', 'docforge.cli.api_utils.derive_metadata')>",
"docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec: Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec."
"docstring": "Derive MkDocs site metadata from an OpenAPI spec ``info`` block.\n\nArgs:\n spec (dict):\n Parsed OpenAPI specification.\n\nReturns:\n OpenAPIMetadata:\n Site name, description, and author derived from the spec."
},
"generate_api_sources": {
"name": "generate_api_sources",
"kind": "function",
"path": "docforge.cli.commands.api_utils.generate_api_sources",
"signature": "<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": {
"name": "Any",
@@ -257,7 +257,7 @@
"kind": "module",
"path": "docforge.cli.commands.mcp_utils",
"signature": "<bound method Alias.signature of Alias('mcp_utils', 'docforge.cli.mcp_utils')>",
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.",
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.\n\n---\n\nNotes:\n - `generate_resources` produces the bundle consumed by `MCPServer`:\n `index.json`, `nav.json`, and per-module resources under `modules/`.\n - Resource URIs use the `docs://` scheme: `docs://index`, `docs://nav`,\n and `docs://modules/{module}`.\n\n---",
"members": {
"Path": {
"name": "Path",
@@ -278,21 +278,21 @@
"kind": "class",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader",
"signature": "<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": {
"load_project": {
"name": "load_project",
"kind": "function",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
},
"load_module": {
"name": "load_module",
"kind": "function",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module",
"signature": "<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",
"path": "docforge.cli.commands.mcp_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp_utils.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path | None):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n list[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
},
"MCPRenderer": {
"name": "MCPRenderer",
@@ -331,7 +331,7 @@
"kind": "class",
"path": "docforge.cli.commands.mcp_utils.MCPServer",
"signature": "<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": {
"mcp_root": {
"name": "mcp_root",
@@ -361,7 +361,7 @@
"kind": "function",
"path": "docforge.cli.commands.mcp_utils.generate_resources",
"signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp_utils.generate_resources')>",
"docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n project_name (Optional[str]):\n Optional override for the project name used in generated\n documentation metadata.\n\n out_dir (Path):\n Directory where MCP resources (index.json, nav.json, and module data)\n will be written."
"docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n project_name (str | None):\n Optional override for the project name used in generated\n documentation metadata.\n\n out_dir (Path):\n Directory where MCP resources (index.json, nav.json, and module data)\n will be written."
},
"serve": {
"name": "serve",
@@ -377,7 +377,7 @@
"kind": "module",
"path": "docforge.cli.commands.mkdocs_utils",
"signature": "<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": {
"os": {
"name": "os",
@@ -426,21 +426,21 @@
"kind": "class",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.\n\nAttributes:\n _loader (_GriffeLoader):\n Internal Griffe loader with dedicated module and line collections.",
"members": {
"load_project": {
"name": "load_project",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
},
"load_module": {
"name": "load_module",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module",
"signature": "<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",
"path": "docforge.cli.commands.mkdocs_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs_utils.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path | None):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n list[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
},
"MkDocsNavEmitter": {
"name": "MkDocsNavEmitter",
@@ -463,23 +463,30 @@
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit",
"signature": "<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": {
"name": "load_nav_spec",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.load_nav_spec",
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs_utils.load_nav_spec')>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid."
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path (Path):\n Path to the navigation specification file.\n\nReturns:\n NavSpec:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid."
},
"resolve_nav": {
"name": "resolve_nav",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.resolve_nav",
"signature": "<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": {
"name": "MkDocsRenderer",
@@ -500,14 +507,14 @@
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder."
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool | None):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<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",
"path": "docforge.cli.commands.mkdocs_utils.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>",
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``."
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``."
},
"generate_config": {
"name": "generate_config",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.generate_config",
"signature": "<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": {
"name": "build",
@@ -546,21 +553,93 @@
"kind": "class",
"path": "docforge.cli.commands.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.\n\nAttributes:\n _loader (_GriffeLoader):\n Internal Griffe loader with dedicated module and line collections.",
"members": {
"load_project": {
"name": "load_project",
"kind": "function",
"path": "docforge.cli.commands.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
},
"load_module": {
"name": "load_module",
"kind": "function",
"path": "docforge.cli.commands.GriffeLoader.load_module",
"signature": "<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",
"kind": "function",
"path": "docforge.cli.commands.build",
"signature": "<bound method Function.signature of Function('build', 28, 223)>",
"docstring": "Build documentation artifacts.\n\nThis command performs the full documentation build pipeline:\nstyle of the selected platform, generates renderer-specific\ndocumentation sources, and optionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites for library reference docs\n- Swagger-enabled API docs generated from an OpenAPI spec\n- MCP structured documentation resources\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs library documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (Optional[str]):\n Python module import path to document.\n\n openapi_spec (Optional[Path]):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (Optional[str]):\n Optional override for the project name.\n\n site_name (Optional[str]):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Optional[Path]):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
"signature": "<bound method Function.signature of Function('build', 38, 260)>",
"docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds or serves the final output.\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites for library reference docs\n- Swagger-enabled API docs generated from an OpenAPI spec\n- Hand-written wiki pages included in the MkDocs site\n- MCP structured documentation resources\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` are combined into a single MkDocs\n build, while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs library documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Include a hand-written wiki directory in the MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
},
"serve": {
"name": "serve",
"kind": "function",
"path": "docforge.cli.commands.serve",
"signature": "<bound method Function.signature of Function('serve', 226, 287)>",
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (Optional[str]):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided."
"signature": "<bound method Function.signature of Function('serve', 263, 324)>",
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided."
},
"tree": {
"name": "tree",
"kind": "function",
"path": "docforge.cli.commands.tree",
"signature": "<bound method Function.signature of Function('tree', 290, 326)>",
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (Optional[str]):\n Optional name to display as the project root."
},
"Any": {
"name": "Any",
"kind": "alias",
"path": "docforge.cli.commands.Any",
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
"signature": "<bound method Function.signature of Function('tree', 327, 363)>",
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (str | None):\n Optional name to display as the project root."
},
"Group": {
"name": "Group",
@@ -613,7 +685,7 @@
"kind": "module",
"path": "docforge.cli.mcp_utils",
"signature": null,
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.",
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.\n\n---\n\nNotes:\n - `generate_resources` produces the bundle consumed by `MCPServer`:\n `index.json`, `nav.json`, and per-module resources under `modules/`.\n - Resource URIs use the `docs://` scheme: `docs://index`, `docs://nav`,\n and `docs://modules/{module}`.\n\n---",
"members": {
"Path": {
"name": "Path",
@@ -634,21 +706,21 @@
"kind": "class",
"path": "docforge.cli.mcp_utils.GriffeLoader",
"signature": "<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": {
"load_project": {
"name": "load_project",
"kind": "function",
"path": "docforge.cli.mcp_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
},
"load_module": {
"name": "load_module",
"kind": "function",
"path": "docforge.cli.mcp_utils.GriffeLoader.load_module",
"signature": "<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",
"path": "docforge.cli.mcp_utils.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": {
"name": "MCPRenderer",
@@ -687,7 +759,7 @@
"kind": "class",
"path": "docforge.cli.mcp_utils.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": {
"mcp_root": {
"name": "mcp_root",
@@ -716,14 +788,14 @@
"name": "generate_resources",
"kind": "function",
"path": "docforge.cli.mcp_utils.generate_resources",
"signature": "<bound method Function.signature of Function('generate_resources', 16, 42)>",
"docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n project_name (Optional[str]):\n Optional override for the project name used in generated\n documentation metadata.\n\n out_dir (Path):\n Directory where MCP resources (index.json, nav.json, and module data)\n will be written."
"signature": "<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 (str | None):\n Optional override for the project name used in generated\n documentation metadata.\n\n out_dir (Path):\n Directory where MCP resources (index.json, nav.json, and module data)\n will be written."
},
"serve": {
"name": "serve",
"kind": "function",
"path": "docforge.cli.mcp_utils.serve",
"signature": "<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."
}
}
@@ -733,7 +805,7 @@
"kind": "module",
"path": "docforge.cli.mkdocs_utils",
"signature": null,
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.",
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A single generated `mkdocs.yml` serves lib, api, and wiki content with\n merged navigation. Wiki navigation, when enabled, precedes every other\n group and its `index.md` becomes the site `Home`.\n\n---",
"members": {
"os": {
"name": "os",
@@ -782,21 +854,21 @@
"kind": "class",
"path": "docforge.cli.mkdocs_utils.GriffeLoader",
"signature": "<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": {
"load_project": {
"name": "load_project",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
},
"load_module": {
"name": "load_module",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module",
"signature": "<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",
"path": "docforge.cli.mkdocs_utils.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": {
"name": "MkDocsNavEmitter",
@@ -819,23 +891,30 @@
"kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit",
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: 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": {
"name": "load_nav_spec",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.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": {
"name": "resolve_nav",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.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": {
"name": "MkDocsRenderer",
@@ -856,14 +935,14 @@
"kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder."
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool | None):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<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",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 20, 69)>",
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``."
"signature": "<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 (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``."
},
"generate_config": {
"name": "generate_config",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_config",
"signature": "<bound method Function.signature of Function('generate_config', 72, 150)>",
"docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Optional[Path]):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Optional[Iterable[str]]):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib`` or ``api``),\n merged on top of the shared ``mkdocs.common.yml`` template.\n\n site_description (Optional[str]):\n Optional site description written into the configuration.\n\n site_author (Optional[str]):\n Optional site author written into the configuration.\n\nRaises:\n click.FileError:\n If the navigation specification or template file cannot be found."
"signature": "<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 (and, when a wiki directory is provided, from the wiki\nfile structure).\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories\nand hand-written wiki content under a ``wiki/`` subdirectory.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Iterable[str] | None):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib``, ``api``, or\n ``wiki``), merged on top of the shared ``mkdocs.common.yml``\n template.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n wiki_dir (Path | None):\n Optional path to a hand-written wiki directory (for example\n ``docs/wiki``). When provided, the site navigation is derived\n from the wiki file structure and placed before the navigation\n groups defined in ``nav_file``.\n\nRaises:\n click.FileError:\n If the navigation specification, template, or wiki directory\n cannot be found."
},
"build": {
"name": "build",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.build",
"signature": "<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."
},
"serve": {
"name": "serve",
"kind": "function",
"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."
}
}

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

@@ -2,7 +2,7 @@
"module": "docforge.cli.mcp_utils",
"content": {
"path": "docforge.cli.mcp_utils",
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.",
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.\n\n---\n\nNotes:\n - `generate_resources` produces the bundle consumed by `MCPServer`:\n `index.json`, `nav.json`, and per-module resources under `modules/`.\n - Resource URIs use the `docs://` scheme: `docs://index`, `docs://nav`,\n and `docs://modules/{module}`.\n\n---",
"objects": {
"Path": {
"name": "Path",
@@ -23,21 +23,21 @@
"kind": "class",
"path": "docforge.cli.mcp_utils.GriffeLoader",
"signature": "<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": {
"load_project": {
"name": "load_project",
"kind": "function",
"path": "docforge.cli.mcp_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
},
"load_module": {
"name": "load_module",
"kind": "function",
"path": "docforge.cli.mcp_utils.GriffeLoader.load_module",
"signature": "<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",
"path": "docforge.cli.mcp_utils.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": {
"name": "MCPRenderer",
@@ -76,7 +76,7 @@
"kind": "class",
"path": "docforge.cli.mcp_utils.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": {
"mcp_root": {
"name": "mcp_root",
@@ -105,14 +105,14 @@
"name": "generate_resources",
"kind": "function",
"path": "docforge.cli.mcp_utils.generate_resources",
"signature": "<bound method Function.signature of Function('generate_resources', 16, 42)>",
"docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n project_name (Optional[str]):\n Optional override for the project name used in generated\n documentation metadata.\n\n out_dir (Path):\n Directory where MCP resources (index.json, nav.json, and module data)\n will be written."
"signature": "<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 (str | None):\n Optional override for the project name used in generated\n documentation metadata.\n\n out_dir (Path):\n Directory where MCP resources (index.json, nav.json, and module data)\n will be written."
},
"serve": {
"name": "serve",
"kind": "function",
"path": "docforge.cli.mcp_utils.serve",
"signature": "<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."
}
}

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

@@ -2,7 +2,7 @@
"module": "docforge.cli.mkdocs_utils",
"content": {
"path": "docforge.cli.mkdocs_utils",
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.",
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A single generated `mkdocs.yml` serves lib, api, and wiki content with\n merged navigation. Wiki navigation, when enabled, precedes every other\n group and its `index.md` becomes the site `Home`.\n\n---",
"objects": {
"os": {
"name": "os",
@@ -51,21 +51,21 @@
"kind": "class",
"path": "docforge.cli.mkdocs_utils.GriffeLoader",
"signature": "<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": {
"load_project": {
"name": "load_project",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
},
"load_module": {
"name": "load_module",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module",
"signature": "<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",
"path": "docforge.cli.mkdocs_utils.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": {
"name": "MkDocsNavEmitter",
@@ -88,23 +88,30 @@
"kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit",
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: 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": {
"name": "load_nav_spec",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.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": {
"name": "resolve_nav",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.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": {
"name": "MkDocsRenderer",
@@ -125,14 +132,14 @@
"kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder."
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool | None):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<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",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 20, 69)>",
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``."
"signature": "<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 (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``."
},
"generate_config": {
"name": "generate_config",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_config",
"signature": "<bound method Function.signature of Function('generate_config', 72, 150)>",
"docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Optional[Path]):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Optional[Iterable[str]]):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib`` or ``api``),\n merged on top of the shared ``mkdocs.common.yml`` template.\n\n site_description (Optional[str]):\n Optional site description written into the configuration.\n\n site_author (Optional[str]):\n Optional site author written into the configuration.\n\nRaises:\n click.FileError:\n If the navigation specification or template file cannot be found."
"signature": "<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 (and, when a wiki directory is provided, from the wiki\nfile structure).\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories\nand hand-written wiki content under a ``wiki/`` subdirectory.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Iterable[str] | None):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib``, ``api``, or\n ``wiki``), merged on top of the shared ``mkdocs.common.yml``\n template.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n wiki_dir (Path | None):\n Optional path to a hand-written wiki directory (for example\n ``docs/wiki``). When provided, the site navigation is derived\n from the wiki file structure and placed before the navigation\n groups defined in ``nav_file``.\n\nRaises:\n click.FileError:\n If the navigation specification, template, or wiki directory\n cannot be found."
},
"build": {
"name": "build",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.build",
"signature": "<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."
},
"serve": {
"name": "serve",
"kind": "function",
"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."
}
}

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",
"content": {
"path": "docforge.loaders.griffe_loader",
"docstring": "# Summary\n\nUtilities for loading and introspecting Python modules using Griffe.\n\nThis module provides the `GriffeLoader` class and helper utilities used to\ndiscover Python modules, introspect their structure, and convert the results\ninto doc-forge documentation models.",
"docstring": "# Summary\n\nUtilities for loading and introspecting Python modules using Griffe.\n\nThis module provides the `GriffeLoader` class and helper utilities used to\ndiscover Python modules, introspect their structure, and convert the results\ninto doc-forge documentation models.\n\n---\n\nNotes:\n - All analysis is static; analyzed modules are never executed.\n - Private members (names starting with `_`) are skipped during conversion.\n\n---",
"objects": {
"logging": {
"name": "logging",
@@ -51,7 +51,7 @@
"kind": "class",
"path": "docforge.loaders.griffe_loader.DocObject",
"signature": "<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": {
"name": {
"name": "name",
@@ -100,7 +100,7 @@
"kind": "function",
"path": "docforge.loaders.griffe_loader.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": {
"name": "get_member",
@@ -123,7 +123,7 @@
"kind": "class",
"path": "docforge.loaders.griffe_loader.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": {
"path": {
"name": "path",
@@ -174,7 +174,7 @@
"kind": "class",
"path": "docforge.loaders.griffe_loader.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": {
"name": {
"name": "name",
@@ -231,29 +231,29 @@
"name": "discover_module_paths",
"kind": "function",
"path": "docforge.loaders.griffe_loader.discover_module_paths",
"signature": "<bound method Function.signature of Function('discover_module_paths', 29, 81)>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
"signature": "<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 | None):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n list[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
},
"GriffeLoader": {
"name": "GriffeLoader",
"kind": "class",
"path": "docforge.loaders.griffe_loader.GriffeLoader",
"signature": "<bound method Class.signature of Class('GriffeLoader', 84, 288)>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.",
"signature": "<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.\n\nAttributes:\n _loader (_GriffeLoader):\n Internal Griffe loader with dedicated module and line collections.",
"members": {
"load_project": {
"name": "load_project",
"kind": "function",
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_project",
"signature": "<bound method Function.signature of Function('load_project', 105, 159)>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
"signature": "<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 | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
},
"load_module": {
"name": "load_module",
"kind": "function",
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_module",
"signature": "<bound method Function.signature of Function('load_module', 161, 179)>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance."
"signature": "<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.\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",
"path": "docforge.loaders.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": {
"load_project": {
"name": "load_project",
"kind": "function",
"path": "docforge.loaders.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": {
"name": "load_module",
"kind": "function",
"path": "docforge.loaders.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",
"path": "docforge.loaders.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": {
"name": "griffe_loader",
"kind": "module",
"path": "docforge.loaders.griffe_loader",
"signature": null,
"docstring": "# Summary\n\nUtilities for loading and introspecting Python modules using Griffe.\n\nThis module provides the `GriffeLoader` class and helper utilities used to\ndiscover Python modules, introspect their structure, and convert the results\ninto doc-forge documentation models.",
"docstring": "# Summary\n\nUtilities for loading and introspecting Python modules using Griffe.\n\nThis module provides the `GriffeLoader` class and helper utilities used to\ndiscover Python modules, introspect their structure, and convert the results\ninto doc-forge documentation models.\n\n---\n\nNotes:\n - All analysis is static; analyzed modules are never executed.\n - Private members (names starting with `_`) are skipped during conversion.\n\n---",
"members": {
"logging": {
"name": "logging",
@@ -88,7 +88,7 @@
"kind": "class",
"path": "docforge.loaders.griffe_loader.DocObject",
"signature": "<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": {
"name": {
"name": "name",
@@ -137,7 +137,7 @@
"kind": "function",
"path": "docforge.loaders.griffe_loader.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": {
"name": "get_member",
@@ -160,7 +160,7 @@
"kind": "class",
"path": "docforge.loaders.griffe_loader.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": {
"path": {
"name": "path",
@@ -211,7 +211,7 @@
"kind": "class",
"path": "docforge.loaders.griffe_loader.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": {
"name": {
"name": "name",
@@ -268,29 +268,29 @@
"name": "discover_module_paths",
"kind": "function",
"path": "docforge.loaders.griffe_loader.discover_module_paths",
"signature": "<bound method Function.signature of Function('discover_module_paths', 29, 81)>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
"signature": "<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 | None):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n list[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
},
"GriffeLoader": {
"name": "GriffeLoader",
"kind": "class",
"path": "docforge.loaders.griffe_loader.GriffeLoader",
"signature": "<bound method Class.signature of Class('GriffeLoader', 84, 288)>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.",
"signature": "<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.\n\nAttributes:\n _loader (_GriffeLoader):\n Internal Griffe loader with dedicated module and line collections.",
"members": {
"load_project": {
"name": "load_project",
"kind": "function",
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_project",
"signature": "<bound method Function.signature of Function('load_project', 105, 159)>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
"signature": "<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 | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
},
"load_module": {
"name": "load_module",
"kind": "function",
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_module",
"signature": "<bound method Function.signature of Function('load_module', 161, 179)>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance."
"signature": "<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.\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",
"path": "docforge.models.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": {
"name": {
"name": "name",
@@ -60,7 +60,7 @@
"kind": "class",
"path": "docforge.models.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": {
"path": {
"name": "path",
@@ -111,7 +111,7 @@
"kind": "class",
"path": "docforge.models.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": {
"name": {
"name": "name",
@@ -160,7 +160,7 @@
"kind": "function",
"path": "docforge.models.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": {
"name": "get_member",
@@ -183,7 +183,7 @@
"kind": "module",
"path": "docforge.models.module",
"signature": null,
"docstring": "# Summary\n\nDocumentation model representing a Python module or package.\n\nThis module defines the `Module` class used in the doc-forge documentation\nmodel. A `Module` acts as a container for top-level documented objects\n(classes, functions, variables, and other members) discovered during\nintrospection.",
"docstring": "# Summary\n\nDocumentation model representing a Python module or package.\n\nThis module defines the `Module` class used in the doc-forge documentation\nmodel. A `Module` acts as a container for top-level documented objects\n(classes, functions, variables, and other members) discovered during\nintrospection.\n\n---\n\nNotes:\n - Only public members are stored; private names are filtered by the loader.\n\n---",
"members": {
"Iterable": {
"name": "Iterable",
@@ -197,7 +197,7 @@
"kind": "class",
"path": "docforge.models.module.DocObject",
"signature": "<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": {
"name": {
"name": "name",
@@ -246,7 +246,7 @@
"kind": "function",
"path": "docforge.models.module.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": {
"name": "get_member",
@@ -268,8 +268,8 @@
"name": "Module",
"kind": "class",
"path": "docforge.models.module.Module",
"signature": "<bound method Class.signature of Class('Module', 17, 91)>",
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
"signature": "<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 (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
"members": {
"path": {
"name": "path",
@@ -296,21 +296,21 @@
"name": "add_object",
"kind": "function",
"path": "docforge.models.module.Module.add_object",
"signature": "<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."
},
"get_object": {
"name": "get_object",
"kind": "function",
"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."
},
"get_all_objects": {
"name": "get_all_objects",
"kind": "function",
"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."
}
}
@@ -322,7 +322,7 @@
"kind": "module",
"path": "docforge.models.object",
"signature": null,
"docstring": "# Summary\n\nDocumentation model representing individual Python objects.\n\nThis module defines the `DocObject` class, the fundamental recursive unit of\nthe doc-forge documentation model. Each `DocObject` represents a Python\nentity such as a class, function, method, or attribute, and may contain nested\nmembers that form a hierarchical documentation structure.",
"docstring": "# Summary\n\nDocumentation model representing individual Python objects.\n\nThis module defines the `DocObject` class, the fundamental recursive unit of\nthe doc-forge documentation model. Each `DocObject` represents a Python\nentity such as a class, function, method, or attribute, and may contain nested\nmembers that form a hierarchical documentation structure.\n\n---\n\nNotes:\n - `DocObject` instances form a tree mirroring the Python import hierarchy.\n - Objects are renderer-agnostic and may be consumed by any renderer.\n\n---",
"members": {
"Iterable": {
"name": "Iterable",
@@ -335,8 +335,8 @@
"name": "DocObject",
"kind": "class",
"path": "docforge.models.object.DocObject",
"signature": "<bound method Class.signature of Class('DocObject', 15, 115)>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.",
"signature": "<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 (str | None):\n Callable signature if the object represents a callable.\n\n docstring (str | None):\n Raw docstring text extracted from the source code.\n\n members (dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.",
"members": {
"name": {
"name": "name",
@@ -384,21 +384,21 @@
"name": "add_member",
"kind": "function",
"path": "docforge.models.object.DocObject.add_member",
"signature": "<bound method Function.signature of Function('add_member', 77, 87)>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: Documentation object to add as a member."
"signature": "<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 (DocObject):\n Documentation object to add as a member."
},
"get_member": {
"name": "get_member",
"kind": "function",
"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."
},
"get_all_members": {
"name": "get_all_members",
"kind": "function",
"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."
}
}
@@ -410,7 +410,7 @@
"kind": "module",
"path": "docforge.models.project",
"signature": null,
"docstring": "# Summary\n\nDocumentation model representing a project.\n\nThis module defines the `Project` class, the top-level container used by\ndoc-forge to represent a documented codebase. A `Project` aggregates multiple\nmodules and provides access to them through a unified interface.",
"docstring": "# Summary\n\nDocumentation model representing a project.\n\nThis module defines the `Project` class, the top-level container used by\ndoc-forge to represent a documented codebase. A `Project` aggregates multiple\nmodules and provides access to them through a unified interface.\n\n---\n\nNotes:\n - Modules are keyed by their dotted import path.\n - Objects are renderer-agnostic; the same model feeds every renderer.\n\n---",
"members": {
"Iterable": {
"name": "Iterable",
@@ -424,7 +424,7 @@
"kind": "class",
"path": "docforge.models.project.Module",
"signature": "<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": {
"path": {
"name": "path",
@@ -474,8 +474,8 @@
"name": "Project",
"kind": "class",
"path": "docforge.models.project.Project",
"signature": "<bound method Class.signature of Class('Project', 16, 88)>",
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (Dict[str, Module]):\n Mapping of module paths to `Module` instances.",
"signature": "<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.",
"members": {
"name": {
"name": "name",
@@ -495,28 +495,28 @@
"name": "add_module",
"kind": "function",
"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."
},
"get_module": {
"name": "get_module",
"kind": "function",
"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."
},
"get_all_modules": {
"name": "get_all_modules",
"kind": "function",
"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."
},
"get_module_list": {
"name": "get_module_list",
"kind": "function",
"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."
}
}

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

@@ -2,7 +2,7 @@
"module": "docforge.models.module",
"content": {
"path": "docforge.models.module",
"docstring": "# Summary\n\nDocumentation model representing a Python module or package.\n\nThis module defines the `Module` class used in the doc-forge documentation\nmodel. A `Module` acts as a container for top-level documented objects\n(classes, functions, variables, and other members) discovered during\nintrospection.",
"docstring": "# Summary\n\nDocumentation model representing a Python module or package.\n\nThis module defines the `Module` class used in the doc-forge documentation\nmodel. A `Module` acts as a container for top-level documented objects\n(classes, functions, variables, and other members) discovered during\nintrospection.\n\n---\n\nNotes:\n - Only public members are stored; private names are filtered by the loader.\n\n---",
"objects": {
"Iterable": {
"name": "Iterable",
@@ -16,7 +16,7 @@
"kind": "class",
"path": "docforge.models.module.DocObject",
"signature": "<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": {
"name": {
"name": "name",
@@ -65,7 +65,7 @@
"kind": "function",
"path": "docforge.models.module.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": {
"name": "get_member",
@@ -87,8 +87,8 @@
"name": "Module",
"kind": "class",
"path": "docforge.models.module.Module",
"signature": "<bound method Class.signature of Class('Module', 17, 91)>",
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
"signature": "<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 (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
"members": {
"path": {
"name": "path",
@@ -115,21 +115,21 @@
"name": "add_object",
"kind": "function",
"path": "docforge.models.module.Module.add_object",
"signature": "<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."
},
"get_object": {
"name": "get_object",
"kind": "function",
"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."
},
"get_all_objects": {
"name": "get_all_objects",
"kind": "function",
"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."
}
}

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

@@ -2,7 +2,7 @@
"module": "docforge.models.object",
"content": {
"path": "docforge.models.object",
"docstring": "# Summary\n\nDocumentation model representing individual Python objects.\n\nThis module defines the `DocObject` class, the fundamental recursive unit of\nthe doc-forge documentation model. Each `DocObject` represents a Python\nentity such as a class, function, method, or attribute, and may contain nested\nmembers that form a hierarchical documentation structure.",
"docstring": "# Summary\n\nDocumentation model representing individual Python objects.\n\nThis module defines the `DocObject` class, the fundamental recursive unit of\nthe doc-forge documentation model. Each `DocObject` represents a Python\nentity such as a class, function, method, or attribute, and may contain nested\nmembers that form a hierarchical documentation structure.\n\n---\n\nNotes:\n - `DocObject` instances form a tree mirroring the Python import hierarchy.\n - Objects are renderer-agnostic and may be consumed by any renderer.\n\n---",
"objects": {
"Iterable": {
"name": "Iterable",
@@ -15,8 +15,8 @@
"name": "DocObject",
"kind": "class",
"path": "docforge.models.object.DocObject",
"signature": "<bound method Class.signature of Class('DocObject', 15, 115)>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.",
"signature": "<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 (str | None):\n Callable signature if the object represents a callable.\n\n docstring (str | None):\n Raw docstring text extracted from the source code.\n\n members (dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.",
"members": {
"name": {
"name": "name",
@@ -64,21 +64,21 @@
"name": "add_member",
"kind": "function",
"path": "docforge.models.object.DocObject.add_member",
"signature": "<bound method Function.signature of Function('add_member', 77, 87)>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: Documentation object to add as a member."
"signature": "<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 (DocObject):\n Documentation object to add as a member."
},
"get_member": {
"name": "get_member",
"kind": "function",
"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."
},
"get_all_members": {
"name": "get_all_members",
"kind": "function",
"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."
}
}

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

@@ -2,7 +2,7 @@
"module": "docforge.models.project",
"content": {
"path": "docforge.models.project",
"docstring": "# Summary\n\nDocumentation model representing a project.\n\nThis module defines the `Project` class, the top-level container used by\ndoc-forge to represent a documented codebase. A `Project` aggregates multiple\nmodules and provides access to them through a unified interface.",
"docstring": "# Summary\n\nDocumentation model representing a project.\n\nThis module defines the `Project` class, the top-level container used by\ndoc-forge to represent a documented codebase. A `Project` aggregates multiple\nmodules and provides access to them through a unified interface.\n\n---\n\nNotes:\n - Modules are keyed by their dotted import path.\n - Objects are renderer-agnostic; the same model feeds every renderer.\n\n---",
"objects": {
"Iterable": {
"name": "Iterable",
@@ -16,7 +16,7 @@
"kind": "class",
"path": "docforge.models.project.Module",
"signature": "<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": {
"path": {
"name": "path",
@@ -66,8 +66,8 @@
"name": "Project",
"kind": "class",
"path": "docforge.models.project.Project",
"signature": "<bound method Class.signature of Class('Project', 16, 88)>",
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (Dict[str, Module]):\n Mapping of module paths to `Module` instances.",
"signature": "<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.",
"members": {
"name": {
"name": "name",
@@ -87,28 +87,28 @@
"name": "add_module",
"kind": "function",
"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."
},
"get_module": {
"name": "get_module",
"kind": "function",
"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."
},
"get_all_modules": {
"name": "get_all_modules",
"kind": "function",
"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."
},
"get_module_list": {
"name": "get_module_list",
"kind": "function",
"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."
}
}

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

@@ -37,14 +37,14 @@
"kind": "function",
"path": "docforge.nav.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": {
"name": "all_patterns",
"kind": "function",
"path": "docforge.nav.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",
"path": "docforge.nav.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": {
"name": "ResolvedNav",
@@ -81,7 +81,7 @@
"kind": "function",
"path": "docforge.nav.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",
"path": "docforge.nav.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": {
"name": "MkDocsNavEmitter",
@@ -104,16 +104,23 @@
"kind": "function",
"path": "docforge.nav.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": {
"name": "mkdocs",
"kind": "module",
"path": "docforge.nav.mkdocs",
"signature": null,
"docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.",
"docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.\n\n---\n\nNotes:\n - The emitted structure is a list of dictionaries, one per top-level nav\n entry, matching the MkDocs ``nav`` YAML format.\n\n---",
"members": {
"Path": {
"name": "Path",
@@ -155,7 +162,7 @@
"kind": "function",
"path": "docforge.nav.mkdocs.ResolvedNav.all_files",
"signature": "<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",
"kind": "class",
"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.",
"members": {
"emit": {
"name": "emit",
"kind": "function",
"path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit",
"signature": "<bound method Function.signature of Function('emit', 23, 51)>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages."
"signature": "<bound method Function.signature of Function('emit', 31, 61)>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav (ResolvedNav):\n Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n list[dict[str, Any]]:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages."
}
}
}
@@ -182,7 +189,7 @@
"kind": "module",
"path": "docforge.nav.resolver",
"signature": null,
"docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.",
"docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.\n\n---\n\nNotes:\n - Glob resolution is recursive and returns paths in sorted order.\n - Unmatched patterns raise ``FileNotFoundError`` to fail fast on typos.\n\n---",
"members": {
"glob": {
"name": "glob",
@@ -238,14 +245,14 @@
"kind": "function",
"path": "docforge.nav.resolver.NavSpec.load",
"signature": "<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": {
"name": "all_patterns",
"kind": "function",
"path": "docforge.nav.resolver.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",
"kind": "class",
"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.",
"members": {
"home": {
@@ -274,8 +281,8 @@
"name": "all_files",
"kind": "function",
"path": "docforge.nav.resolver.ResolvedNav.all_files",
"signature": "<bound method Function.signature of Function('all_files', 46, 63)>",
"docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution."
"signature": "<bound method Function.signature of Function('all_files', 57, 76)>",
"docstring": "Iterate over all files referenced by the navigation structure.\n\nYields:\n Path:\n A documentation file referenced by the navigation, including\n the home page when defined.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution."
}
}
},
@@ -283,8 +290,8 @@
"name": "resolve_nav",
"kind": "function",
"path": "docforge.nav.resolver.resolve_nav",
"signature": "<bound method Function.signature of Function('resolve_nav', 66, 132)>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files."
"signature": "<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 (NavSpec):\n Navigation specification describing documentation layout.\n docs_root (Path):\n Root directory containing documentation Markdown files.\n\nReturns:\n ResolvedNav:\n A `ResolvedNav` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files."
}
}
},
@@ -293,8 +300,15 @@
"kind": "module",
"path": "docforge.nav.spec",
"signature": null,
"docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).",
"docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).\n\n---\n\nNotes:\n - The spec file supports an optional ``icon`` mapping for MkDocs theme\n customization.\n - All file references in ``groups`` are relative to the documentation root.\n\n---",
"members": {
"annotations": {
"name": "annotations",
"kind": "alias",
"path": "docforge.nav.spec.annotations",
"signature": "<bound method Alias.signature of Alias('annotations', '__future__.annotations')>",
"docstring": null
},
"Path": {
"name": "Path",
"kind": "alias",
@@ -313,7 +327,7 @@
"name": "NavSpec",
"kind": "class",
"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``.",
"members": {
"home": {
@@ -341,15 +355,15 @@
"name": "load",
"kind": "function",
"path": "docforge.nav.spec.NavSpec.load",
"signature": "<bound method Function.signature of Function('load', 51, 101)>",
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification."
"signature": "<bound method Function.signature of Function('load', 65, 117)>",
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path (Path):\n Filesystem path to the navigation specification file.\n\nReturns:\n NavSpec:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification."
},
"all_patterns": {
"name": "all_patterns",
"kind": "function",
"path": "docforge.nav.spec.NavSpec.all_patterns",
"signature": "<bound method Function.signature of Function('all_patterns', 103, 119)>",
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries."
"signature": "<bound method Function.signature of Function('all_patterns', 119, 136)>",
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n list[str]:\n A list containing the home document (if defined) and all\n group pattern entries."
}
}
},
@@ -357,8 +371,52 @@
"name": "load_nav_spec",
"kind": "function",
"path": "docforge.nav.spec.load_nav_spec",
"signature": "<bound method Function.signature of Function('load_nav_spec', 122, 151)>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid."
"signature": "<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):\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",
"content": {
"path": "docforge.nav.mkdocs",
"docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.",
"docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.\n\n---\n\nNotes:\n - The emitted structure is a list of dictionaries, one per top-level nav\n entry, matching the MkDocs ``nav`` YAML format.\n\n---",
"objects": {
"Path": {
"name": "Path",
@@ -44,7 +44,7 @@
"kind": "function",
"path": "docforge.nav.mkdocs.ResolvedNav.all_files",
"signature": "<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",
"kind": "class",
"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.",
"members": {
"emit": {
"name": "emit",
"kind": "function",
"path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit",
"signature": "<bound method Function.signature of Function('emit', 23, 51)>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages."
"signature": "<bound method Function.signature of Function('emit', 31, 61)>",
"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",
"content": {
"path": "docforge.nav.resolver",
"docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.",
"docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.\n\n---\n\nNotes:\n - Glob resolution is recursive and returns paths in sorted order.\n - Unmatched patterns raise ``FileNotFoundError`` to fail fast on typos.\n\n---",
"objects": {
"glob": {
"name": "glob",
@@ -58,14 +58,14 @@
"kind": "function",
"path": "docforge.nav.resolver.NavSpec.load",
"signature": "<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": {
"name": "all_patterns",
"kind": "function",
"path": "docforge.nav.resolver.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",
"kind": "class",
"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.",
"members": {
"home": {
@@ -94,8 +94,8 @@
"name": "all_files",
"kind": "function",
"path": "docforge.nav.resolver.ResolvedNav.all_files",
"signature": "<bound method Function.signature of Function('all_files', 46, 63)>",
"docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution."
"signature": "<bound method Function.signature of Function('all_files', 57, 76)>",
"docstring": "Iterate over all files referenced by the navigation structure.\n\nYields:\n Path:\n A documentation file referenced by the navigation, including\n the home page when defined.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution."
}
}
},
@@ -103,8 +103,8 @@
"name": "resolve_nav",
"kind": "function",
"path": "docforge.nav.resolver.resolve_nav",
"signature": "<bound method Function.signature of Function('resolve_nav', 66, 132)>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files."
"signature": "<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 (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",
"content": {
"path": "docforge.nav.spec",
"docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).",
"docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).\n\n---\n\nNotes:\n - The spec file supports an optional ``icon`` mapping for MkDocs theme\n customization.\n - All file references in ``groups`` are relative to the documentation root.\n\n---",
"objects": {
"annotations": {
"name": "annotations",
"kind": "alias",
"path": "docforge.nav.spec.annotations",
"signature": "<bound method Alias.signature of Alias('annotations', '__future__.annotations')>",
"docstring": null
},
"Path": {
"name": "Path",
"kind": "alias",
@@ -22,7 +29,7 @@
"name": "NavSpec",
"kind": "class",
"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``.",
"members": {
"home": {
@@ -50,15 +57,15 @@
"name": "load",
"kind": "function",
"path": "docforge.nav.spec.NavSpec.load",
"signature": "<bound method Function.signature of Function('load', 51, 101)>",
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification."
"signature": "<bound method Function.signature of Function('load', 65, 117)>",
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path (Path):\n Filesystem path to the navigation specification file.\n\nReturns:\n NavSpec:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification."
},
"all_patterns": {
"name": "all_patterns",
"kind": "function",
"path": "docforge.nav.spec.NavSpec.all_patterns",
"signature": "<bound method Function.signature of Function('all_patterns', 103, 119)>",
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries."
"signature": "<bound method Function.signature of Function('all_patterns', 119, 136)>",
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n list[str]:\n A list containing the home document (if defined) and all\n group pattern entries."
}
}
},
@@ -66,8 +73,8 @@
"name": "load_nav_spec",
"kind": "function",
"path": "docforge.nav.spec.load_nav_spec",
"signature": "<bound method Function.signature of Function('load_nav_spec', 122, 151)>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid."
"signature": "<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):\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",
"path": "docforge.renderers.base.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": {
"name": {
"name": "name",

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

@@ -23,14 +23,14 @@
"kind": "function",
"path": "docforge.renderers.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": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.renderers.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",
"path": "docforge.renderers.base.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": {
"name": {
"name": "name",
@@ -203,7 +203,7 @@
"kind": "class",
"path": "docforge.renderers.mcp_renderer.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": {
"name": {
"name": "name",
@@ -252,7 +252,7 @@
"kind": "function",
"path": "docforge.renderers.mcp_renderer.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": {
"name": "get_member",
@@ -275,7 +275,7 @@
"kind": "class",
"path": "docforge.renderers.mcp_renderer.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": {
"path": {
"name": "path",
@@ -326,7 +326,7 @@
"kind": "class",
"path": "docforge.renderers.mcp_renderer.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": {
"name": {
"name": "name",
@@ -423,7 +423,7 @@
"kind": "class",
"path": "docforge.renderers.mkdocs_renderer.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": {
"path": {
"name": "path",
@@ -474,7 +474,7 @@
"kind": "class",
"path": "docforge.renderers.mkdocs_renderer.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": {
"name": {
"name": "name",
@@ -524,7 +524,7 @@
"name": "MkDocsRenderer",
"kind": "class",
"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.",
"members": {
"name": {
@@ -539,14 +539,14 @@
"kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
"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": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme",
"signature": "<bound method Function.signature of Function('generate_readme', 80, 145)>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project (Project):\n Project model containing documentation metadata.\n\n docs_dir (Path):\n Directory containing generated documentation sources.\n\n module_is_source (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`."
"signature": "<bound method Function.signature of Function('generate_readme', 80, 144)>",
"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",
"path": "docforge.renderers.mcp_renderer.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": {
"name": {
"name": "name",
@@ -72,7 +72,7 @@
"kind": "function",
"path": "docforge.renderers.mcp_renderer.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": {
"name": "get_member",
@@ -95,7 +95,7 @@
"kind": "class",
"path": "docforge.renderers.mcp_renderer.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": {
"path": {
"name": "path",
@@ -146,7 +146,7 @@
"kind": "class",
"path": "docforge.renderers.mcp_renderer.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": {
"name": {
"name": "name",

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

@@ -16,7 +16,7 @@
"kind": "class",
"path": "docforge.renderers.mkdocs_renderer.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": {
"path": {
"name": "path",
@@ -67,7 +67,7 @@
"kind": "class",
"path": "docforge.renderers.mkdocs_renderer.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": {
"name": {
"name": "name",
@@ -117,7 +117,7 @@
"name": "MkDocsRenderer",
"kind": "class",
"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.",
"members": {
"name": {
@@ -132,14 +132,14 @@
"kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
"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": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme",
"signature": "<bound method Function.signature of Function('generate_readme', 80, 145)>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project (Project):\n Project model containing documentation metadata.\n\n docs_dir (Path):\n Directory containing generated documentation sources.\n\n module_is_source (Optional[bool]):\n Whether the module is treated as the project source root.\n\n readme_dir (Optional[Path]):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`."
"signature": "<bound method Function.signature of Function('generate_readme', 80, 144)>",
"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",
"path": "docforge.servers.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": {
"mcp_root": {
"name": "mcp_root",
@@ -39,7 +39,7 @@
"kind": "module",
"path": "docforge.servers.mcp_server",
"signature": null,
"docstring": "# Summary\n\nMCP server implementation.\n\nThis module defines the `MCPServer` class, which serves pre-generated\ndocumentation bundles through the Model Context Protocol (MCP).",
"docstring": "# Summary\n\nMCP server implementation.\n\nThis module defines the `MCPServer` class, which serves pre-generated\ndocumentation bundles through the Model Context Protocol (MCP).\n\n---\n\nNotes:\n - The served bundle is generated offline by `MCPRenderer`.\n - Missing resources are reported as structured error dictionaries rather\n than raising exceptions.\n - The server exposes read-only resources and a single health-check tool.\n\n---",
"members": {
"annotations": {
"name": "annotations",
@@ -87,8 +87,8 @@
"name": "MCPServer",
"kind": "class",
"path": "docforge.servers.mcp_server.MCPServer",
"signature": "<bound method Class.signature of Class('MCPServer', 19, 134)>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.",
"signature": "<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.\n\nAttributes:\n mcp_root (Path):\n Directory containing the generated MCP documentation bundle.\n\n app (FastMCP):\n Underlying FastMCP application instance that registers resources\n and tools.",
"members": {
"mcp_root": {
"name": "mcp_root",
@@ -108,7 +108,7 @@
"name": "run",
"kind": "function",
"path": "docforge.servers.mcp_server.MCPServer.run",
"signature": "<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`."
}
}

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

@@ -2,7 +2,7 @@
"module": "docforge.servers.mcp_server",
"content": {
"path": "docforge.servers.mcp_server",
"docstring": "# Summary\n\nMCP server implementation.\n\nThis module defines the `MCPServer` class, which serves pre-generated\ndocumentation bundles through the Model Context Protocol (MCP).",
"docstring": "# Summary\n\nMCP server implementation.\n\nThis module defines the `MCPServer` class, which serves pre-generated\ndocumentation bundles through the Model Context Protocol (MCP).\n\n---\n\nNotes:\n - The served bundle is generated offline by `MCPRenderer`.\n - Missing resources are reported as structured error dictionaries rather\n than raising exceptions.\n - The server exposes read-only resources and a single health-check tool.\n\n---",
"objects": {
"annotations": {
"name": "annotations",
@@ -50,8 +50,8 @@
"name": "MCPServer",
"kind": "class",
"path": "docforge.servers.mcp_server.MCPServer",
"signature": "<bound method Class.signature of Class('MCPServer', 19, 134)>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.",
"signature": "<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.\n\nAttributes:\n mcp_root (Path):\n Directory containing the generated MCP documentation bundle.\n\n app (FastMCP):\n Underlying FastMCP application instance that registers resources\n and tools.",
"members": {
"mcp_root": {
"name": "mcp_root",
@@ -71,7 +71,7 @@
"name": "run",
"kind": "function",
"path": "docforge.servers.mcp_server.MCPServer.run",
"signature": "<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`."
}
}

50
docs/mcp/nav.json
View File

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

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 |
| `api` | OpenAPI JSON spec | `docs/api/**` rendered markdown |
| `wiki` | Hand-written markdown | `docs/wiki/**` (unchanged) |
| `mcp` | Griffe + renderers | `docs/mcp/**` structured files |
| `mcp` | GSDFC docstrings + renderers | `docs/mcp/**` structured JSON |
## Combined build
@@ -22,4 +22,10 @@ One `mkdocs.yml` and one MkDocs build serve all kinds:
3. The wiki `index.md` becomes the site `Home`.
Hand-written wiki content is never overwritten or regenerated — only its
navigation is derived automatically.
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,
classes, and Google-style docstring sections. Loaded data is normalized into
the object model under `docforge/models` (`Module`, `Object`, `Project`,
`Field`).
the object model under `docforge/models` (`Project`, `Module`, `DocObject`).
## Navigation
@@ -23,6 +22,13 @@ file structure via `build_wiki_nav`.
- `MkDocsRenderer` → `docs/lib/**` reference markdown
- `MCPRenderer` → `docs/mcp/**` structured documentation
## Servers
`docforge/servers` serves generated artifacts over live protocols:
- `MCPServer` → serves a pre-generated `docs/mcp/**` bundle through MCP
resources (`docs://index`, `docs://nav`, `docs://modules/{module}`)
## CLI
`docforge/cli` wires it all together:

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
signatures.
The authoritative GSDFC specification lives in the `docforge/__init__.py`
package docstring, which is exported verbatim into
`docs/mcp/modules/docforge.json`, so the MCP bundle is self-documenting.
Key rules:
- Use parenthesized types in prose entries (`name (Type):`) that match the
signature types.
- Use `# Summary`, `# Examples`, and `# Notes` sections at module level.
- Use `Args:`, `Returns:`, `Raises:`, `Yields:`, `Notes:`, and `Example:`
sections at function and method level.
- Always update the matching `.pyi` stub alongside the `.py` implementation.
## `.pyi` stubs
Every module ships a matching `.pyi` stub kept in sync with the `.py`
@@ -14,7 +27,7 @@ implementation. When signatures change, update both files.
## Wiki pages
- Hand-written markdown lives in `docs/wiki/**` and is never generated.
- File names use a numeric prefix: `01_overview.md`, `02_components.md`.
- File names use a numeric prefix: `01_overview.md`, `02_architecture.md`.
- Nested directories become nested navigation groups:
`05_development/01_environment.md` → group *Development*.
- `index.md` is the site `Home` at the root, and a section root inside a

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
doc-forge build --mkdocs --module docforge
# Wik + library combined (single MkDocs build)
# Wiki + library combined (single MkDocs build)
doc-forge build --wiki --mkdocs --module docforge
# Wiki only — no module required
doc-forge build --wiki --site-name docforge
# MCP structured bundle
doc-forge build --mcp --module docforge
```
## What a combined build does
@@ -29,5 +32,12 @@ doc-forge build --wiki --site-name docforge
```bash
doc-forge build --wiki --mkdocs --module docforge
doc-forge serve --mkdocs-yml mkdocs.yml
doc-forge serve --mkdocs --mkdocs-yml mkdocs.yml
```
## Serve the MCP bundle
```bash
doc-forge build --mcp --module docforge
doc-forge serve --mcp --module docforge
```

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

@@ -8,7 +8,7 @@ python -m venv .venv
pip install -e .
```
Requires Python 3.11+.
Requires Python 3.10+ (per `pyproject.toml`).
## Dependencies
@@ -17,4 +17,5 @@ Development extras include:
- `pytest`, `pytest-cov` — test suite and coverage
- `ruff` — lint and format checking
- `black` — auto-formatting
- `mypy` — strict typing checks
- `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 black --check docforge tests
.venv\Scripts\python.exe -m mypy docforge
.venv\Scripts\pydoclint.exe docforge
```
## 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 |
|----------------------------------------------| -------------------------------------------------- |
| [Overview](01_overview.md) | What docforge is and how it fits the pipeline |
| [Architecture](02_architecture.md) | Loaders, models, nav, renderers, CLI |
| [Architecture](02_architecture.md) | Loaders, models, nav, renderers, CLI, servers |
| [Conventions](03_conventions.md) | GSDFC, `.pyi` stubs, and template conventions |
| [Iterative Workflow](04_iterative_workflow.md) | How a docs build runs end to end |
| [Development](05_development/01_environment.md) | Environment setup and quality gates |
| [Docstring Guide](05_development/03_gsdfc_guide.md) | How to write GSDFC-conformant docstrings |
| [MCP Guide](05_development/04_mcp_guide.md) | Building, serving, and consuming the MCP bundle |
---
## 🔗 Related Resources
- **Source Code:** `C:\Users\vishe\WorkSpace\code\aetos\doc-forge`
- **Source Code:** the `doc-forge` repository
- **Wiki Kind:** hand-written content lives in `docs/wiki/`
- **MCP Bundle:** generated by `doc-forge build --mcp --module docforge` into `docs/mcp/`
---

2
mkdocs.yml
View File

@@ -77,6 +77,8 @@ nav:
- Development:
- Environment: wiki/05_development/01_environment.md
- Quality Gates: wiki/05_development/02_quality_gates.md
- Gsdfc Guide: wiki/05_development/03_gsdfc_guide.md
- Mcp Guide: wiki/05_development/04_mcp_guide.md
- Loaders:
- lib/loaders/index.md
- lib/loaders/griffe_loader.md

9
pyproject.toml
View File

@@ -83,6 +83,7 @@ dev = [
"black>=23.0.0",
"ruff>=0.3.0",
"mypy>=1.8.0",
"pydoclint>=0.9.1",
"build>=1.0.0",
"twine>=4.0.0",
"pre-commit>=3.4.0",
@@ -188,6 +189,14 @@ module = [
ignore_missing_imports = true
[tool.pydoclint]
style = "google"
exclude = '\.pyi$|tests/'
allow-init-docstring = true
skip-checking-raises = true
check-class-attributes = false
[tool.coverage.run]
source = ["docforge"]
omit = [