From b1f5ce092a6b1ba1ed2a60e44453237f45bac243 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Tue, 15 Sep 2026 16:53:19 +0530 Subject: [PATCH] updated hexa and docforge docs --- doc-forge/lib/cli/api_utils/index.html | 2 +- .../lib/docforge/cli/api_utils/index.html | 1515 -------- .../lib/docforge/cli/commands/index.html | 1766 ---------- doc-forge/lib/docforge/cli/index.html | 1156 ------ doc-forge/lib/docforge/cli/main/index.html | 1165 ------ .../lib/docforge/cli/mcp_utils/index.html | 1346 ------- .../lib/docforge/cli/mkdocs_utils/index.html | 2001 ----------- doc-forge/lib/docforge/index.html | 3134 ----------------- .../docforge/loaders/griffe_loader/index.html | 1672 --------- doc-forge/lib/docforge/loaders/index.html | 1686 --------- doc-forge/lib/docforge/models/index.html | 2418 ------------- .../lib/docforge/models/module/index.html | 1520 -------- .../lib/docforge/models/object/index.html | 1610 --------- .../lib/docforge/models/project/index.html | 1559 -------- doc-forge/lib/docforge/nav/index.html | 2283 ------------ doc-forge/lib/docforge/nav/mkdocs/index.html | 1288 ------- .../lib/docforge/nav/resolver/index.html | 1519 -------- doc-forge/lib/docforge/nav/spec/index.html | 1626 --------- doc-forge/lib/docforge/nav/wiki/index.html | 1273 ------- .../lib/docforge/renderers/base/index.html | 1422 -------- doc-forge/lib/docforge/renderers/index.html | 1601 --------- .../renderers/mcp_renderer/index.html | 1277 ------- .../renderers/mkdocs_renderer/index.html | 1427 -------- doc-forge/lib/docforge/servers/index.html | 1357 ------- .../docforge/servers/mcp_server/index.html | 1365 ------- doc-forge/lib/index.html | 34 +- .../lib/loaders/griffe_loader/index.html | 2 + doc-forge/lib/objects.inv | Bin 1305 -> 1255 bytes doc-forge/lib/search/search_index.json | 2 +- doc-forge/lib/sitemap.xml.gz | Bin 127 -> 127 bytes hexa/lib/404.html | 146 +- hexa/lib/check_matches/index.html | 295 +- hexa/lib/cli/index.html | 176 +- hexa/lib/container/index.html | 318 +- hexa/lib/design/index.html | 369 +- hexa/lib/generate_abc/index.html | 268 +- hexa/lib/generate_yaml/index.html | 268 +- hexa/lib/hexa/check_matches/index.html | 1123 ------ hexa/lib/hexa/cli/index.html | 1044 ------ hexa/lib/hexa/container/index.html | 1126 ------ hexa/lib/hexa/generate_abc/index.html | 1123 ------ hexa/lib/hexa/generate_yaml/index.html | 1123 ------ hexa/lib/hexa/index.html | 1407 -------- hexa/lib/hexa/model/index.html | 1310 ------- hexa/lib/hexa/parse_abc/index.html | 1121 ------ hexa/lib/hexa/parse_yaml/index.html | 1170 ------ hexa/lib/index.html | 888 +++-- hexa/lib/model/index.html | 496 ++- hexa/lib/objects.inv | Bin 496 -> 454 bytes hexa/lib/parse_abc/index.html | 280 +- hexa/lib/parse_yaml/index.html | 377 +- hexa/lib/philosophy/index.html | 285 +- hexa/lib/search/search_index.json | 2 +- hexa/lib/sitemap.xml.gz | Bin 127 -> 127 bytes .../modules/docforge.cli.api_utils.json | 43 +- .../modules/docforge.cli.commands.json | 246 +- mcp/doc-forge/modules/docforge.cli.json | 422 +-- mcp/doc-forge/modules/docforge.cli.main.json | 4 +- .../modules/docforge.cli.mcp_utils.json | 40 +- .../modules/docforge.cli.mkdocs_utils.json | 89 +- mcp/doc-forge/modules/docforge.json | 1057 ++---- .../docforge.loaders.griffe_loader.json | 100 +- mcp/doc-forge/modules/docforge.loaders.json | 108 +- mcp/doc-forge/modules/docforge.models.json | 129 +- .../modules/docforge.models.module.json | 35 +- .../modules/docforge.models.object.json | 15 +- .../modules/docforge.models.project.json | 31 +- mcp/doc-forge/modules/docforge.nav.json | 154 +- .../modules/docforge.nav.mkdocs.json | 26 +- .../modules/docforge.nav.resolver.json | 39 +- mcp/doc-forge/modules/docforge.nav.spec.json | 29 +- mcp/doc-forge/modules/docforge.nav.wiki.json | 30 +- .../modules/docforge.renderers.base.json | 34 +- mcp/doc-forge/modules/docforge.renderers.json | 162 +- .../docforge.renderers.mcp_renderer.json | 73 +- .../docforge.renderers.mkdocs_renderer.json | 41 +- mcp/doc-forge/modules/docforge.servers.json | 54 +- .../modules/docforge.servers.mcp_server.json | 46 +- 78 files changed, 2653 insertions(+), 54095 deletions(-) delete mode 100644 doc-forge/lib/docforge/cli/api_utils/index.html delete mode 100644 doc-forge/lib/docforge/cli/commands/index.html delete mode 100644 doc-forge/lib/docforge/cli/index.html delete mode 100644 doc-forge/lib/docforge/cli/main/index.html delete mode 100644 doc-forge/lib/docforge/cli/mcp_utils/index.html delete mode 100644 doc-forge/lib/docforge/cli/mkdocs_utils/index.html delete mode 100644 doc-forge/lib/docforge/index.html delete mode 100644 doc-forge/lib/docforge/loaders/griffe_loader/index.html delete mode 100644 doc-forge/lib/docforge/loaders/index.html delete mode 100644 doc-forge/lib/docforge/models/index.html delete mode 100644 doc-forge/lib/docforge/models/module/index.html delete mode 100644 doc-forge/lib/docforge/models/object/index.html delete mode 100644 doc-forge/lib/docforge/models/project/index.html delete mode 100644 doc-forge/lib/docforge/nav/index.html delete mode 100644 doc-forge/lib/docforge/nav/mkdocs/index.html delete mode 100644 doc-forge/lib/docforge/nav/resolver/index.html delete mode 100644 doc-forge/lib/docforge/nav/spec/index.html delete mode 100644 doc-forge/lib/docforge/nav/wiki/index.html delete mode 100644 doc-forge/lib/docforge/renderers/base/index.html delete mode 100644 doc-forge/lib/docforge/renderers/index.html delete mode 100644 doc-forge/lib/docforge/renderers/mcp_renderer/index.html delete mode 100644 doc-forge/lib/docforge/renderers/mkdocs_renderer/index.html delete mode 100644 doc-forge/lib/docforge/servers/index.html delete mode 100644 doc-forge/lib/docforge/servers/mcp_server/index.html delete mode 100644 hexa/lib/hexa/check_matches/index.html delete mode 100644 hexa/lib/hexa/cli/index.html delete mode 100644 hexa/lib/hexa/container/index.html delete mode 100644 hexa/lib/hexa/generate_abc/index.html delete mode 100644 hexa/lib/hexa/generate_yaml/index.html delete mode 100644 hexa/lib/hexa/index.html delete mode 100644 hexa/lib/hexa/model/index.html delete mode 100644 hexa/lib/hexa/parse_abc/index.html delete mode 100644 hexa/lib/hexa/parse_yaml/index.html diff --git a/doc-forge/lib/cli/api_utils/index.html b/doc-forge/lib/cli/api_utils/index.html index cc0a0ef..1aa2177 100644 --- a/doc-forge/lib/cli/api_utils/index.html +++ b/doc-forge/lib/cli/api_utils/index.html @@ -1400,7 +1400,7 @@ site author.

OpenAPIMetadata - OpenAPIMetadata + OpenAPIMetadata
diff --git a/doc-forge/lib/docforge/cli/api_utils/index.html b/doc-forge/lib/docforge/cli/api_utils/index.html deleted file mode 100644 index 74ea405..0000000 --- a/doc-forge/lib/docforge/cli/api_utils/index.html +++ /dev/null @@ -1,1515 +0,0 @@ - - - - - - - - - - - - - - - - - - - Api Utils - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Api Utils

- - -
- - - -

- docforge.cli.api_utils - - -

- -
- -

Summary

-

Utilities for building API documentation from an OpenAPI specification.

- - - -
- - - - - - -

Classes

- -
- - - -

- OpenAPIMetadata - - - - dataclass - - -

-
1
-2
-3
-4
-5
OpenAPIMetadata(
-    site_name: str,
-    site_description: str | None,
-    site_author: str | None,
-)
-
- -
- - -

Metadata derived from the info block of an OpenAPI specification.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
site_name - str - -
-

Spec title, used as the MkDocs site name.

-
-
site_description - str | None - -
-

Spec description, used as the site description.

-
-
site_author - str | None - -
-

Contact name (fallback: contact email), used as the -site author.

-
-
- - - - -
- - - - - - - - - - - -
- -
- -
-

Functions

- -
- - -

- derive_metadata - - -

-
1
derive_metadata(spec: dict[Any, Any]) -> OpenAPIMetadata
-
- -
- -

Derive MkDocs site metadata from an OpenAPI spec info block.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
spec - dict - -
-

Parsed OpenAPI specification.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
OpenAPIMetadata - OpenAPIMetadata - -
-

Site name, description, and author derived from the spec.

-
-
- -
- -
- -
- - -

- generate_api_sources - - -

-
1
-2
-3
generate_api_sources(
-    spec: dict[Any, Any], docs_dir: Path
-) -> None
-
- -
- -

Generate swagger-enabled Markdown sources and the spec copy.

-

The specification is written as openapi.json inside docs_dir and -an index.md embedding the swagger UI is generated alongside it.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
spec - dict - -
-

Parsed OpenAPI specification.

-
- 		- required -
docs_dir - Path - -
-

Directory (for example docs/api) where the swagger -sources are written.

-
- 		- required -
- -
- -
- -
- - -

- load_openapi_spec - - -

-
1
load_openapi_spec(spec_path: Path) -> dict[Any, Any]
-
- -
- -

Load and validate an OpenAPI specification from a JSON file.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
spec_path - Path - -
-

Path to the OpenAPI JSON specification file.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
dict - dict[Any, Any] - -
-

The parsed OpenAPI specification.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- ClickException - -
-

If the file cannot be read or the info block is invalid.

-
-
- -
- -
- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/cli/commands/index.html b/doc-forge/lib/docforge/cli/commands/index.html deleted file mode 100644 index 40701af..0000000 --- a/doc-forge/lib/docforge/cli/commands/index.html +++ /dev/null @@ -1,1766 +0,0 @@ - - - - - - - - - - - - - - - - - - - Commands - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Commands

- - -
- - - -

- docforge.cli.commands - - -

- -
- -

Summary

-

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 each emit their own MkDocs config and - build (docs/mkdocs.{kind}.yml into site/{kind}); --mcp generates a - machine-readable bundle independently.
    • -
-
- - - -
- - - - - - -

Classes

-

Functions

- -
- - -

- build - - -

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
build(
-    mcp: bool,
-    mkdocs: bool,
-    api: bool,
-    wiki: bool,
-    refresh: bool,
-    module_is_source: bool,
-    module: str | None,
-    openapi_spec: Path | None,
-    project_name: str | None,
-    site_name: str | None,
-    docs_dir: Path,
-    wiki_dir: Path,
-    nav_file: Path,
-    template: Path | None,
-    out_dir: Path,
-) -> None
-
- -
- -

Build documentation artifacts.

-

This command runs the full documentation pipeline: it loads Python -modules, generates renderer-specific documentation sources, and -optionally builds the final output.

-

Depending on the selected options, the build can target:

-
    -
  • A lib MkDocs site (--mkdocs) for library reference docs
    • -
  • A swagger-enabled API MkDocs site (--api) built from an OpenAPI spec
    • -
  • A wiki MkDocs site (--wiki) built from hand-written markdown
    • -
  • MCP structured documentation resources (--mcp)
    • -
-

Each enabled site kind produces its own MkDocs configuration -(docs/mkdocs.{kind}.yml) and its own build (site/{kind}).

- - -
- Notes -
    -
  • At least one of --mcp, --mkdocs, --wiki, or --api must be - provided.
    • -
  • --mkdocs, --api, and --wiki emit independent MkDocs builds, - while --mcp emits a machine-readable bundle.
    • -
  • Configuration files are generated only when absent; an existing - docs/mkdocs.{kind}.yml is used as-is. Pass --refresh to - rebaseline it from the templates.
    • -
-
- -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
mcp - bool - -
-

Enable MCP documentation generation.

-
- 		- required -
mkdocs - bool - -
-

Enable the lib MkDocs documentation generation.

-
- 		- required -
api - bool - -
-

Enable API documentation generation from an OpenAPI spec.

-
- 		- required -
wiki - bool - -
-

Build a hand-written wiki directory as its own MkDocs site.

-
- 		- required -
refresh - bool - -
-

Regenerate docs/mkdocs.{kind}.yml from templates even when -it already exists. By default, existing configs are used as-is.

-
- 		- required -
module_is_source - bool - -
-

Treat the specified module directory as the project root.

-
- 		- required -
module - str | None - -
-

Python module import path to document.

-
- 		- required -
openapi_spec - Path | None - -
-

Path to the OpenAPI JSON specification used for API docs.

-
- 		- required -
project_name - str | None - -
-

Optional override for the project name.

-
- 		- required -
site_name - str | None - -
-

Display name for the lib and wiki MkDocs sites.

-
- 		- required -
docs_dir - Path - -
-

Shared documentation root used for generated sources.

-
- 		- required -
wiki_dir - Path - -
-

Directory containing hand-written wiki markdown files.

-
- 		- required -
nav_file - Path - -
-

Path to the navigation specification file.

-
- 		- required -
template - Path | None - -
-

Optional custom MkDocs configuration template.

-
- 		- required -
out_dir - Path - -
-

Output directory for generated MCP resources.

-
- 		- required -
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- UsageError - -
-

If required options are missing or conflicting.

-
-
- -
- -
- -
- - -

- serve - - -

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
serve(
-    mcp: bool,
-    mkdocs: bool,
-    lib: bool,
-    api: bool,
-    wiki: bool,
-    module: str | None,
-    mkdocs_yml: Path,
-    out_dir: Path,
-) -> None
-
- -
- -

Serve generated documentation locally.

-

Depending on the selected mode, this command starts either:

-
    -
  • A MkDocs development server for browsing a site, or
    • -
  • An MCP server exposing structured documentation resources
    • -
-

The kind flags (--lib, --api, --wiki) select the generated -per-kind config (docs/mkdocs.{kind}.yml); --mkdocs serves the config -passed via --mkdocs-yml.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
mcp - bool - -
-

Serve documentation using the MCP server.

-
- 		- required -
mkdocs - bool - -
-

Serve the MkDocs development site from --mkdocs-yml.

-
- 		- required -
lib - bool - -
-

Serve the lib MkDocs site.

-
- 		- required -
api - bool - -
-

Serve the API MkDocs site.

-
- 		- required -
wiki - bool - -
-

Serve the wiki MkDocs site.

-
- 		- required -
module - str | None - -
-

Python module import path to serve via MCP.

-
- 		- required -
mkdocs_yml - Path - -
-

Path to the MkDocs configuration file.

-
- 		- required -
out_dir - Path - -
-

Root directory containing MCP documentation resources.

-
- 		- required -
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- UsageError - -
-

If invalid or conflicting options are provided.

-
-
- -
- -
- -
- - -

- tree - - -

-
1
tree(module: str, project_name: str | None) -> None
-
- -
- -

Display the documentation object tree for a module.

-

This command introspects the specified module and prints a -hierarchical representation of the discovered documentation -objects, including modules, classes, functions, and members.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
module - str - -
-

Python module import path to introspect.

-
- 		- required -
project_name - str | None - -
-

Optional name to display as the project root.

-
- 		- required -
- -
- -
- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/cli/index.html b/doc-forge/lib/docforge/cli/index.html deleted file mode 100644 index 41abfd5..0000000 --- a/doc-forge/lib/docforge/cli/index.html +++ /dev/null @@ -1,1156 +0,0 @@ - - - - - - - - - - - - - - - - - - - Cli - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Cli

- - -
- - - -

- docforge.cli - - -

- -
- -

Summary

-

Command line interface entry point for doc-forge.

-

This module exposes the primary CLI entry function used by the -doc-forge command. The actual command implementation resides in -docforge.cli.main, while this module provides a stable import path -for external tools and the package entry point configuration.

-

The CLI is responsible for orchestrating documentation workflows such as -generating renderer sources, building documentation sites, exporting -machine-readable documentation bundles, and starting development or MCP -servers.

-
-

Typical usage

-

The CLI is normally invoked through the installed command:

-
1
doc-forge <command> [options]
-
-

Programmatic invocation is also possible:

-

Example:

-
1
-2
-3
-4
```python
-from docforge.cli import main
-main()
-```
-
-
- - - -
- - - - - - - - - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/cli/main/index.html b/doc-forge/lib/docforge/cli/main/index.html deleted file mode 100644 index 56bea4c..0000000 --- a/doc-forge/lib/docforge/cli/main/index.html +++ /dev/null @@ -1,1165 +0,0 @@ - - - - - - - - - - - - - - - - - - - Main - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Main

- - -
- - - -

- docforge.cli.main - - -

- -
- -

Summary

-

Command-line entry point for the doc-forge CLI.

-

This module exposes the executable entry point that initializes the -Click command group defined in docforge.cli.commands.

- - - -
- - - - - - - -

Functions

- -
- - -

- main - - -

-
1
main() -> None
-
- -
- -

Run the doc-forge command-line interface.

-

This function initializes and executes the Click CLI application. -It is used as the console entry point when invoking doc-forge -from the command line.

- -
- -
- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/cli/mcp_utils/index.html b/doc-forge/lib/docforge/cli/mcp_utils/index.html deleted file mode 100644 index b7bf597..0000000 --- a/doc-forge/lib/docforge/cli/mcp_utils/index.html +++ /dev/null @@ -1,1346 +0,0 @@ - - - - - - - - - - - - - - - - - - - Mcp Utils - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Mcp Utils

- - -
- - - -

- docforge.cli.mcp_utils - - -

- -
- -

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}.
    • -
-
- - - -
- - - - - - -

Classes

-

Functions

- -
- - -

- generate_resources - - -

-
1
-2
-3
generate_resources(
-    module: str, project_name: str | None, out_dir: Path
-) -> None
-
- -
- -

Generate MCP documentation resources from a Python module.

-

The function performs project introspection, builds the internal -documentation model, and renders MCP-compatible JSON resources -to the specified output directory.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
module - str - -
-

Python module import path used as the entry point for -documentation generation.

-
- 		- required -
project_name - str | None - -
-

Optional override for the project name used in generated -documentation metadata.

-
- 		- required -
out_dir - Path - -
-

Directory where MCP resources (index.json, nav.json, and module data) -will be written.

-
- 		- required -
- -
- -
- -
- - -

- serve - - -

-
1
serve(module: str, mcp_root: Path) -> None
-
- -
- -

Start an MCP server for a pre-generated documentation bundle.

-

The server exposes documentation resources such as project metadata, -navigation structure, and module documentation through MCP endpoints.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
module - str - -
-

Python module import path used to identify the served -documentation instance.

-
- 		- required -
mcp_root - Path - -
-

Path to the directory containing the MCP documentation -bundle (index.json, nav.json, and modules/).

-
- 		- required -
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- ClickException - -
-

If the MCP documentation bundle is missing required files or directories.

-
-
- -
- -
- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/cli/mkdocs_utils/index.html b/doc-forge/lib/docforge/cli/mkdocs_utils/index.html deleted file mode 100644 index 9819716..0000000 --- a/doc-forge/lib/docforge/cli/mkdocs_utils/index.html +++ /dev/null @@ -1,2001 +0,0 @@ - - - - - - - - - - - - - - - - - - - Mkdocs Utils - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Mkdocs Utils

- - -
- - - -

- docforge.cli.mkdocs_utils - - -

- -
- -

Summary

-

Utilities for working with MkDocs in the doc-forge CLI.

-
- - -
- Notes -
    -
  • A separate mkdocs.{kind}.yml configuration and build is emitted per - enabled kind (lib, api, wiki), each scoped to its own docs_dir and - written into its own site_dir (site/lib, site/api, site/wiki).
    • -
  • Navigation blocks are re-rooted per kind: the wiki navigation drops its - leading wiki/ scope and the resolved nav spec drops its lib/ scope.
    • -
-
- - - -
- - - - - - -

Classes

-

Functions

- -
- - -

- build_configs - - -

-
1
build_configs(yml_paths: Iterable[Path]) -> None
-
- -
- -

Build the MkDocs documentation site for every given configuration.

-

Each configuration file is loaded and built in turn, producing the -per-kind static sites (site/lib, site/api, site/wiki).

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
yml_paths - Iterable[Path] - -
-

Configuration files to build, in order.

-
- 		- required -
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- ClickException - -
-

If a configuration file does not exist.

-
-
- -
- -
- -
- - -

- build_lib_nav - - -

-
1
-2
-3
build_lib_nav(
-    nav_file: Path, docs_root: Path
-) -> tuple[list[dict[str, Any]], dict[str, str] | None]
-
- -
- -

Build the re-rooted navigation block for a lib site.

-

The navigation specification is resolved against the shared documentation -root and every resulting path is re-rooted relative to the lib -subdirectory by stripping its leading lib/ scope component.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
nav_file - Path - -
-

Path to the docforge.nav.yml navigation specification.

-
- 		- required -
docs_root - Path - -
-

Shared documentation root containing the lib sources.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- tuple[list[dict[str, Any]], dict[str, str] | None] - -
-

tuple[list[dict[str, Any]], dict[str, str] | None]: -The re-rooted navigation block and the optional theme icon -mapping from the specification.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- FileError - -
-

If the navigation specification cannot be found.

-
-
- -
- -
- -
- - -

- build_wiki_nav_block - - -

-
1
-2
-3
build_wiki_nav_block(
-    wiki_dir: Path,
-) -> list[dict[str, Any]]
-
- -
- -

Build the re-rooted navigation block for a wiki site.

-

The wiki navigation derived from the wiki file structure is re-rooted -relative to the wiki directory itself by stripping the leading wiki/ -scope component.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
wiki_dir - Path - -
-

Path to the hand-written wiki directory, for example docs/wiki.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- list[dict[str, Any]] - -
-

list[dict[str, Any]]: -Navigation entries relative to the wiki directory.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- FileError - -
-

If the wiki directory does not exist.

-
-
- -
- -
- -
- - -

- generate_site_config - - -

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
generate_site_config(
-    kind: str,
-    kind_root: Path,
-    nav_block: list[dict[str, Any]],
-    out: Path,
-    site_name: str,
-    docs_dir: str,
-    site_dir: str,
-    template: Path | None = None,
-    site_description: str | None = None,
-    site_author: str | None = None,
-    theme_icon: dict[str, str] | None = None,
-) -> None
-
- -
- -

Generate a per-kind mkdocs.{kind}.yml configuration file.

-

The configuration is created by merging the shared mkdocs.common.yml -template with the fragment contributed by the kind (lib, api, or -wiki). Both docs_dir and site_dir are written relative to the -configuration file's directory: the kind's sources when expressed as a -sibling path (for example lib) and the per-kind site output (for -example ../site/lib).

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
kind - str - -
-

Documentation kind, one of lib, api, or wiki.

-
- 		- required -
kind_root - Path - -
-

Directory scoped to the kind (for example docs/lib) that -serves as the MkDocs docs_dir.

-
- 		- required -
nav_block - list[dict[str, Any]] - -
-

Re-rooted navigation entries for the kind's site.

-
- 		- required -
out - Path - -
-

Destination path where the generated mkdocs.{kind}.yml file -is written.

-
- 		- required -
site_name - str - -
-

Display name for the generated documentation site.

-
- 		- required -
docs_dir - str - -
-

MkDocs docs_dir value, relative to the configuration -file's directory.

-
- 		- required -
site_dir - str - -
-

MkDocs site_dir value, relative to the configuration -file's directory.

-
- 		- required -
template - Path | None - -
-

Optional path to a fully custom MkDocs configuration template -that replaces the built-in templates entirely.

-
- 		- None -
site_description - str | None - -
-

Optional site description written into the configuration.

-
- 		- None -
site_author - str | None - -
-

Optional site author written into the configuration.

-
- 		- None -
theme_icon - dict[str, str] | None - -
-

Optional mapping of theme icon entries injected as -theme.icon.

-
- 		- None -
- -
- -
- -
- - -

- generate_sources - - -

-
1
-2
-3
-4
-5
-6
-7
generate_sources(
-    module: str,
-    docs_dir: Path,
-    project_name: str | None = None,
-    module_is_source: bool | None = None,
-    readme_dir: Path | None = None,
-) -> None
-
- -
- -

Generate MkDocs Markdown sources for a Python module.

-

This function introspects the specified module, builds the internal -documentation model, and renders Markdown documentation files for -use with MkDocs.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
module - str - -
-

Python module import path used as the entry point for -documentation generation.

-
- 		- required -
docs_dir - Path - -
-

Directory where the generated Markdown files will be written.

-
- 		- required -
project_name - str | None - -
-

Optional override for the project name used in documentation metadata.

-
- 		- None -
module_is_source - bool | None - -
-

If True, treat the specified module directory as the project root -rather than a nested module.

-
- 		- None -
readme_dir - Path | None - -
-

Directory where the generated README.md should be written. If not -provided, defaults to the parent of docs_dir.

-
- 		- None -
- -
- -
- -
- - -

- load_spec_icon - - -

-
1
load_spec_icon(nav_file: Path) -> dict[str, str] | None
-
- -
- -

Load the theme icon mapping from a navigation specification.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
nav_file - Path - -
-

Path to the navigation specification file.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- dict[str, str] | None - -
-

dict[str, str] | None: -The icon mapping, or None when the specification file is -absent or cannot be parsed.

-
-
- -
- -
- -
- - -

- serve - - -

-
1
serve(mkdocs_yml: Path) -> None
-
- -
- -

Start an MkDocs development server with live reload.

-

The server watches documentation files and automatically reloads -the site when changes are detected.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
mkdocs_yml - Path - -
-

Path to the mkdocs.yml configuration file.

-
- 		- required -
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- ClickException - -
-

If the configuration file does not exist.

-
-
- -
- -
- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/index.html b/doc-forge/lib/docforge/index.html deleted file mode 100644 index d4da5fb..0000000 --- a/doc-forge/lib/docforge/index.html +++ /dev/null @@ -1,3134 +0,0 @@ - - - - - - - - - - - - - - - - - - - Docforge - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Docforge

- - -
- - - -

- docforge - - -

- -
- -

Summary

-

Renderer-agnostic Python documentation compiler that converts Python docstrings -into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).

-

doc-forge statically analyzes source code, builds a semantic model of modules, -classes, functions, and attributes, and renders that model into documentation -outputs without executing user code.

-
-

Installation

-

Install using pip:

-
1
pip install doc-forge
-
-
-

CLI usage

-

Each site kind (lib, api, wiki) is built independently into site/{kind}.

-

Build the library reference from a Python package:

-
1
doc-forge build --mkdocs --module my_package
-
-

Build the API reference from an OpenAPI spec:

-
1
doc-forge build --api --openapi-spec spec.json
-
-

Build the hand-written wiki:

-
1
doc-forge build --wiki --site-name my_package
-
-

Generate MCP JSON documentation:

-
1
doc-forge build --mcp --module my_package
-
-

Build several kinds in one pass:

-
1
doc-forge build --mcp --mkdocs --wiki --module my_package
-
-

Each enabled kind gets its own MkDocs config (docs/mkdocs.{lib,api,wiki}.yml) -and its own site under site/.

-

Serve a site locally:

-
1
-2
-3
-4
-5
doc-forge serve --wiki        # preview from docs/mkdocs.wiki.yml
-doc-forge serve --lib
-doc-forge serve --api
-# or any config directly:
-doc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml
-
-

Serve MCP locally:

-
1
doc-forge serve --mcp --module my_package
-
-
-

Core concepts

-

Loader

-

Extracts symbols, signatures, and docstrings using static analysis.

-

Semantic model

-

Structured, renderer-agnostic representation of the API.

-

Renderer

-

Converts the semantic model into output formats such as MkDocs or MCP JSON.

-

Symbol

-

Any documentable object

-
    -
  • module
    • -
  • class
    • -
  • function
    • -
  • method
    • -
  • property
    • -
  • attribute
    • -
-
-

Architecture

-

doc-forge follows a compiler architecture:

-

Front-end:

-

Static analysis of modules, classes, functions, type hints, and docstrings.

-

Middle-end:

-

Builds a semantic model describing symbols and relationships.

-

Back-end:

-

Renders documentation using interchangeable renderers.

-

This architecture ensures deterministic documentation generation.

-
-

Rendering pipeline

-

Typical flow:

-
1
-2
-3
-4
-5
-6
-7
-8
-9
Python package
-    |
-Loader (static analysis)
-    |
-Semantic model
-    |
-Renderer
-    |
-MkDocs site or MCP JSON
-
-
-

Google-Styled Doc-Forge Convention (GSDFC)

-

GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.

-
    -
  • Docstrings are the single source of truth.
    • -
  • doc-forge compiles docstrings but does not generate documentation content.
    • -
  • Documentation follows the Python import hierarchy.
    • -
  • Every public symbol should have a complete and accurate docstring.
    • -
-
-

General rules

-
    -
  • Use Markdown headings at package and module level.
    • -
  • Use Google-style structured sections at class, function, and method level.
    • -
  • 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 ---
    • -
-
-

Notes subsection grouping

-

Group related information using labeled subsections.

-

Example:

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
Notes:
-    **Guarantees:**
-
-        - deterministic behavior
-
-    **Lifecycle:**
-
-        - created during initialization
-        - reused across executions
-
-    **Thread safety:**
-
-        - safe for concurrent reads
-
-
-

Example formatting

-
    -
  • Use indentation for examples.
    • -
  • Indent section contents using four spaces.
    • -
  • Use code blocks for example code.
    • -
- - -
- Example -

Single example:

-
1
-2
-3
-4
-5
-6
Example:
-
-    ```python
-    foo = Foo("example")
-    process(foo, multiplier=2)
-    ```
-
-

Multiple examples:

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
Example:
-    Create foo:
-
-        ```python
-        foo = Foo("example")
-        ```
-
-    Run engine:
-
-        ```python
-        engine = BarEngine([foo])
-        engine.run()
-        ```
-
-

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.

-
-

Separator rules

-

Use horizontal separators only at docstring root level to separate sections:

-
1
---
-
-

Allowed locations:

-
    -
  • package docstrings
    • -
  • module docstrings
    • -
  • major documentation sections
    • -
-

Do not use separators inside code sections.

-
-

Package docstrings

-

Package docstrings act as the documentation home page.

-

Recommended sections:

-
1
-2
-3
-4
-5
-6
-7
-8
-9
# Summary
-# Installation
-# Quick start
-# CLI usage
-# Core concepts
-# Architecture
-# Rendering pipeline
-# Examples
-# Notes
-
- - -
- Example -

Package Doc String:

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
-25
-26
-27
-28
-29
-30
'''
-# Summary
-
-Foo-bar processing framework.
-
-Provides tools for defining Foo objects and executing Bar pipelines.
-
----
-
-# Installation
-
-```bash
-pip install foo-bar
-```
-
----
-
-# Quick start
-
-```python
-from foobar import Foo, BarEngine
-
-foo = Foo("example")
-engine = BarEngine([foo])
-
-result = engine.run()
-```
-
----
-'''
-
-
-

Module docstrings

-

Module docstrings describe a subsystem.

-

Recommended sections:

-
1
-2
-3
# Summary
-# Examples
-# Notes
-
- - -
- Example -

Module Doc String:

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
'''
-# Summary
-
-Foo execution subsystem.
-
-Provides utilities for executing Foo objects through Bar stages.
-
----
-
-Example:
-
-    ```python
-    from foobar.engine import BarEngine
-    from foobar.foo import Foo
-
-    foo = Foo("example")
-
-    engine = BarEngine([foo])
-    engine.run()
-    ```
-
----
-'''
-
-
-

Class docstrings

-

Class docstrings define object responsibility, lifecycle, and attributes.

-

Recommended sections:

-
1
-2
-3
-4
Attributes:
-Notes:
-Example:
-Raises:
-
- - -
- Example -

Simple Foo:

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
-25
-26
-27
-28
-29
class Foo:
-    '''
-    Represents a unit of work.
-
-    Attributes:
-        name (str):
-            Identifier of the foo instance.
-
-        value (int):
-            Numeric value associated with foo.
-
-    Notes:
-        Guarantees:
-
-            - instances are immutable after creation
-
-        Lifecycle:
-
-            - create instance
-            - pass to processing engine
-
-    Example:
-        Create and inspect a Foo:
-
-            ```python
-            foo = Foo("example", value=42)
-            print(foo.name)
-            ```
-    '''
-
-

Complex Bar:

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
class BarEngine:
-    '''
-    Executes Foo objects through Bar stages.
-
-    Attributes:
-        foos (tuple[Foo, ...]):
-            Foo instances managed by the engine.
-
-    Notes:
-        Guarantees:
-
-            - deterministic execution order
-
-    Example:
-        Run engine:
-
-            ```python
-            foo1 = Foo("a")
-            foo2 = Foo("b")
-
-            engine = BarEngine([foo1, foo2])
-            engine.run()
-            ```
-    '''
-
-
-

Function and method docstrings

-

Function docstrings define API contracts.

-

Recommended sections:

-
1
-2
-3
-4
-5
-6
Args:
-Returns:
-Raises:
-Yields:
-Notes:
-Example:
-
- - -
- Example -

Simple process method:

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
-25
-26
-27
-28
-29
-30
-31
-32
-33
-34
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.
-
-    Notes:
-        Guarantees:
-
-            - foo is not modified
-
-    Example:
-        Process foo:
-
-            ```python
-            foo = Foo("example", value=10)
-
-            result = process(foo, multiplier=2)
-            print(result)
-            ```
-    '''
-
-

Multiple Examples:

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
-25
-26
-27
-28
-29
-30
-31
-32
def combine(foo_a: Foo, foo_b: Foo) -> Foo:
-    '''
-    Combine two Foo instances.
-
-    Args:
-        foo_a (Foo):
-            First foo.
-
-        foo_b (Foo):
-            Second foo.
-
-    Returns:
-        Foo:
-            Combined foo.
-
-    Example:
-        Basic usage:
-
-            ```python
-            foo1 = Foo("a")
-            foo2 = Foo("b")
-
-            combined = combine(foo1, foo2)
-            ```
-
-        Pipeline usage:
-
-            ```python
-            engine = BarEngine([foo1, foo2])
-            engine.run()
-            ```
-    '''
-
-
-

Property docstrings

-

Properties must document return values.

- - -
- Example -

Property Doc String:

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
-18
```python
-@property
-def foos(self) -> tuple[Foo, ...]:
-    '''
-    Return contained Foo instances.
-
-    Returns:
-        tuple[Foo, ...]:
-            Stored foo objects.
-
-    Example:
-        ```python
-        container = FooContainer()
-
-        foos = container.foos
-        ```
-    '''
-```
-
-
-

Attribute documentation

-

Document attributes in class docstrings using Attributes:.

- - -
- Example -

Attribute Doc String:

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
```python
-'''
-Represents a processing stage.
-
-Attributes:
-    id (str):
-        Unique identifier.
-
-    enabled (bool):
-        Whether the stage is active.
-'''
-```
-
-
-

Parsing guarantees

-

GSDFC ensures doc-forge can deterministically extract:

-
    -
  • symbol kind (module, class, function, property, attribute)
    • -
  • symbol name
    • -
  • parameters
    • -
  • return values
    • -
  • attributes
    • -
  • examples
    • -
  • structured Notes subsections
    • -
-

This enables:

-
    -
  • reliable MkDocs rendering
    • -
  • deterministic MCP export
    • -
  • accurate AI semantic interpretation
    • -
-
- - -
- Notes -
    -
  • doc-forge never executes analyzed modules.
    • -
  • Documentation is generated entirely through static analysis.
    • -
-
- - -
- - - - - - -

Classes

- -
- - - -

- GriffeLoader - - -

-
1
GriffeLoader()
-
- -
- - -

Load Python modules using Griffe and convert them into doc-forge models.

-

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:

- - - - - - - - - - - - - - - -
NameTypeDescription
_loader - GriffeLoader - -
-

Internal Griffe loader with dedicated module and line collections.

-
-
- -

Initialize the Griffe-backed loader.

-

Creates an internal Griffe loader instance with dedicated collections -for modules and source lines.

- - - - -
- - - - - - - -
Functions
- -
- - -
- load_module - - -
-
1
load_module(path: str) -> Module
-
- -
- -

Load and convert a single Python module.

-

The module is introspected using Griffe and then transformed into -a doc-forge Module model.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - str - -
-

Dotted import path of the module.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
Module - Module - -
-

A populated Module instance.

-
-
- - -

Raises:

- - - - - - - - - - - - - - - - - -
TypeDescription
- 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:

-
1
-2
-3
-4
```python
-loader = GriffeLoader()
-module = loader.load_module("mypackage.submodule")
-```
-
-
-
- -
- -
- - -
- load_project - - -
-
1
-2
-3
-4
-5
load_project(
-    module_paths: list[str],
-    project_name: str | None = None,
-    skip_import_errors: bool | None = None,
-) -> Project
-
- -
- -

Load multiple modules and assemble them into a Project model.

-

Each module path is introspected and converted into a Module -instance. All modules are then aggregated into a single Project -object.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
module_paths - list[str] - -
-

List of dotted module import paths to load.

-
- 		- required -
project_name - str | None - -
-

Optional override for the project name. Defaults to the top-level -name of the first module.

-
- 		- None -
skip_import_errors - bool | None - -
-

If True, modules that fail to load will be skipped instead of raising an error.

-
- 		- None -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
Project - Project - -
-

A populated Project instance containing the loaded modules.

-
-
- - -

Raises:

- - - - - - - - - - - - - - - - - -
TypeDescription
- ValueError - -
-

If no module paths are provided.

-
-
- ImportError - -
-

If a module fails to load and skip_import_errors is False.

-
-
- -
- -
- - - -
- -
- -
- -
- - - -

- MCPRenderer - - -

- - -
- - -

Renderer that generates MCP-compatible documentation resources.

-

This renderer converts doc-forge project models into structured JSON -resources suitable for consumption by systems implementing the Model -Context Protocol (MCP).

- - - - -
- - - - - - - -
Functions
- -
- - -
- generate_sources - - -
-
1
generate_sources(project: Project, out_dir: Path) -> None
-
- -
- -

Generate MCP documentation resources for a project.

-

The renderer serializes each module into a JSON resource and produces -supporting metadata files such as nav.json and index.json.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
project - Project - -
-

Documentation project model to render.

-
- 		- required -
out_dir - Path - -
-

Directory where MCP resources will be written.

-
- 		- required -
- -
- -
- - - -
- -
- -
- -
- - - -

- MkDocsRenderer - - -

- - -
- - -

Renderer that produces Markdown documentation for MkDocs.

-

Generated pages use mkdocstrings directives to reference Python modules, -allowing MkDocs to render API documentation dynamically.

- - - - -
- - - - - - - -
Functions
- -
- - -
- generate_readme - - -
-
1
-2
-3
-4
-5
-6
generate_readme(
-    project: Project,
-    docs_dir: Path,
-    module_is_source: bool | None = None,
-    readme_dir: Path | None = None,
-) -> None
-
- -
- -

Generate a README.md file from the root module docstring.

- - -
- Notes -
    -
  • If module_is_source is True, README.md is written to the - project root directory.
    • -
  • If False, README generation is currently not implemented.
    • -
-
- -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
project - Project - -
-

Project model containing documentation metadata.

-
- 		- required -
docs_dir - Path - -
-

Directory containing generated documentation sources.

-
- 		- required -
module_is_source - bool | None - -
-

Whether the module is treated as the project source root.

-
- 		- None -
readme_dir - Path | None - -
-

Directory where the generated README.md should be written. -Defaults to the parent of docs_dir.

-
- 		- None -
- -
- -
- -
- - -
- generate_sources - - -
-
1
-2
-3
-4
-5
generate_sources(
-    project: Project,
-    out_dir: Path,
-    module_is_source: bool | None = None,
-) -> None
-
- -
- -

Generate Markdown documentation files for a project.

-

This method renders a documentation structure from the provided -project model and writes the resulting Markdown files to the -specified output directory.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
project - Project - -
-

Project model containing modules to document.

-
- 		- required -
out_dir - Path - -
-

Directory where generated Markdown files will be written.

-
- 		- required -
module_is_source - bool | None - -
-

If True, treat the specified module as the documentation root -rather than nesting it inside a folder.

-
- 		- None -
- -
- -
- - - -
- -
- -
-

Functions

- -
- - -

- discover_module_paths - - -

-
1
-2
-3
discover_module_paths(
-    module_name: str, project_root: Path | None = None
-) -> list[str]
-
- -
- -

Discover Python modules within a package directory.

-

The function scans the filesystem for .py files inside the specified -package and converts them into dotted module import paths.

-

Discovery rules:

-
    -
  • Directories containing __init__.py are treated as packages.
    • -
  • Each .py file is treated as a module.
    • -
  • Results are returned as dotted import paths.
    • -
- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
module_name - str - -
-

Top-level package name to discover modules from.

-
- 		- required -
project_root - Path | None - -
-

Root directory used to resolve module paths. If not provided, the -current working directory is used.

-
- 		- None -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- list[str] - -
-

list[str]: -A sorted list of unique dotted module import paths.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- FileNotFoundError - -
-

If the specified package directory does not exist.

-
-
- -
- -
- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/loaders/griffe_loader/index.html b/doc-forge/lib/docforge/loaders/griffe_loader/index.html deleted file mode 100644 index 5f7be77..0000000 --- a/doc-forge/lib/docforge/loaders/griffe_loader/index.html +++ /dev/null @@ -1,1672 +0,0 @@ - - - - - - - - - - - - - - - - - - - Griffe Loader - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Griffe Loader

- - -
- - - -

- docforge.loaders.griffe_loader - - -

- -
- -

Summary

-

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

Classes

- -
- - - -

- GriffeLoader - - -

-
1
GriffeLoader()
-
- -
- - -

Load Python modules using Griffe and convert them into doc-forge models.

-

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:

- - - - - - - - - - - - - - - -
NameTypeDescription
_loader - GriffeLoader - -
-

Internal Griffe loader with dedicated module and line collections.

-
-
- -

Initialize the Griffe-backed loader.

-

Creates an internal Griffe loader instance with dedicated collections -for modules and source lines.

- - - - -
- - - - - - - -
Functions
- -
- - -
- load_module - - -
-
1
load_module(path: str) -> Module
-
- -
- -

Load and convert a single Python module.

-

The module is introspected using Griffe and then transformed into -a doc-forge Module model.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - str - -
-

Dotted import path of the module.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
Module - Module - -
-

A populated Module instance.

-
-
- - -

Raises:

- - - - - - - - - - - - - - - - - -
TypeDescription
- 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:

-
1
-2
-3
-4
```python
-loader = GriffeLoader()
-module = loader.load_module("mypackage.submodule")
-```
-
-
-
- -
- -
- - -
- load_project - - -
-
1
-2
-3
-4
-5
load_project(
-    module_paths: list[str],
-    project_name: str | None = None,
-    skip_import_errors: bool | None = None,
-) -> Project
-
- -
- -

Load multiple modules and assemble them into a Project model.

-

Each module path is introspected and converted into a Module -instance. All modules are then aggregated into a single Project -object.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
module_paths - list[str] - -
-

List of dotted module import paths to load.

-
- 		- required -
project_name - str | None - -
-

Optional override for the project name. Defaults to the top-level -name of the first module.

-
- 		- None -
skip_import_errors - bool | None - -
-

If True, modules that fail to load will be skipped instead of raising an error.

-
- 		- None -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
Project - Project - -
-

A populated Project instance containing the loaded modules.

-
-
- - -

Raises:

- - - - - - - - - - - - - - - - - -
TypeDescription
- ValueError - -
-

If no module paths are provided.

-
-
- ImportError - -
-

If a module fails to load and skip_import_errors is False.

-
-
- -
- -
- - - -
- -
- -
-

Functions

- -
- - -

- discover_module_paths - - -

-
1
-2
-3
discover_module_paths(
-    module_name: str, project_root: Path | None = None
-) -> list[str]
-
- -
- -

Discover Python modules within a package directory.

-

The function scans the filesystem for .py files inside the specified -package and converts them into dotted module import paths.

-

Discovery rules:

-
    -
  • Directories containing __init__.py are treated as packages.
    • -
  • Each .py file is treated as a module.
    • -
  • Results are returned as dotted import paths.
    • -
- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
module_name - str - -
-

Top-level package name to discover modules from.

-
- 		- required -
project_root - Path | None - -
-

Root directory used to resolve module paths. If not provided, the -current working directory is used.

-
- 		- None -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- list[str] - -
-

list[str]: -A sorted list of unique dotted module import paths.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- FileNotFoundError - -
-

If the specified package directory does not exist.

-
-
- -
- -
- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/loaders/index.html b/doc-forge/lib/docforge/loaders/index.html deleted file mode 100644 index 596762a..0000000 --- a/doc-forge/lib/docforge/loaders/index.html +++ /dev/null @@ -1,1686 +0,0 @@ - - - - - - - - - - - - - - - - - - - Loaders - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Loaders

- - -
- - - -

- docforge.loaders - - -

- -
- -

Summary

-

Loader layer for doc-forge.

-

The docforge.loaders package is responsible for discovering Python modules -and extracting documentation data using static analysis.

-
-

Overview

-

This layer converts Python source code into an intermediate documentation -model used by doc-forge. It performs module discovery, introspection, and -initial filtering before the data is passed to the core documentation models.

-

Core capabilities include:

-
    -
  • Module discovery – Locate Python modules and packages within a project.
    • -
  • Static introspection – Parse docstrings, signatures, and object - hierarchies using the griffe library without executing the code.
    • -
  • Public API filtering – Exclude private members (names prefixed with - _) to produce clean public documentation structures.
    • -
-
- - - -
- - - - - - -

Classes

- -
- - - -

- GriffeLoader - - -

-
1
GriffeLoader()
-
- -
- - -

Load Python modules using Griffe and convert them into doc-forge models.

-

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:

- - - - - - - - - - - - - - - -
NameTypeDescription
_loader - GriffeLoader - -
-

Internal Griffe loader with dedicated module and line collections.

-
-
- -

Initialize the Griffe-backed loader.

-

Creates an internal Griffe loader instance with dedicated collections -for modules and source lines.

- - - - -
- - - - - - - -
Functions
- -
- - -
- load_module - - -
-
1
load_module(path: str) -> Module
-
- -
- -

Load and convert a single Python module.

-

The module is introspected using Griffe and then transformed into -a doc-forge Module model.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - str - -
-

Dotted import path of the module.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
Module - Module - -
-

A populated Module instance.

-
-
- - -

Raises:

- - - - - - - - - - - - - - - - - -
TypeDescription
- 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:

-
1
-2
-3
-4
```python
-loader = GriffeLoader()
-module = loader.load_module("mypackage.submodule")
-```
-
-
-
- -
- -
- - -
- load_project - - -
-
1
-2
-3
-4
-5
load_project(
-    module_paths: list[str],
-    project_name: str | None = None,
-    skip_import_errors: bool | None = None,
-) -> Project
-
- -
- -

Load multiple modules and assemble them into a Project model.

-

Each module path is introspected and converted into a Module -instance. All modules are then aggregated into a single Project -object.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
module_paths - list[str] - -
-

List of dotted module import paths to load.

-
- 		- required -
project_name - str | None - -
-

Optional override for the project name. Defaults to the top-level -name of the first module.

-
- 		- None -
skip_import_errors - bool | None - -
-

If True, modules that fail to load will be skipped instead of raising an error.

-
- 		- None -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
Project - Project - -
-

A populated Project instance containing the loaded modules.

-
-
- - -

Raises:

- - - - - - - - - - - - - - - - - -
TypeDescription
- ValueError - -
-

If no module paths are provided.

-
-
- ImportError - -
-

If a module fails to load and skip_import_errors is False.

-
-
- -
- -
- - - -
- -
- -
-

Functions

- -
- - -

- discover_module_paths - - -

-
1
-2
-3
discover_module_paths(
-    module_name: str, project_root: Path | None = None
-) -> list[str]
-
- -
- -

Discover Python modules within a package directory.

-

The function scans the filesystem for .py files inside the specified -package and converts them into dotted module import paths.

-

Discovery rules:

-
    -
  • Directories containing __init__.py are treated as packages.
    • -
  • Each .py file is treated as a module.
    • -
  • Results are returned as dotted import paths.
    • -
- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
module_name - str - -
-

Top-level package name to discover modules from.

-
- 		- required -
project_root - Path | None - -
-

Root directory used to resolve module paths. If not provided, the -current working directory is used.

-
- 		- None -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- list[str] - -
-

list[str]: -A sorted list of unique dotted module import paths.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- FileNotFoundError - -
-

If the specified package directory does not exist.

-
-
- -
- -
- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/models/index.html b/doc-forge/lib/docforge/models/index.html deleted file mode 100644 index 7691946..0000000 --- a/doc-forge/lib/docforge/models/index.html +++ /dev/null @@ -1,2418 +0,0 @@ - - - - - - - - - - - - - - - - - - - Models - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Models

- - -
- - - -

- docforge.models - - -

- -
- -

Summary

-

Model layer for doc-forge.

-

The docforge.models package defines the core data structures used to -represent Python source code as a structured documentation model.

-
-

Overview

-

The model layer forms the central intermediate representation used throughout -doc-forge. Python modules and objects discovered during introspection are -converted into a hierarchy of documentation models that can later be rendered -into different documentation formats.

-

Key components:

-
    -
  • Project – Root container representing an entire documented codebase.
    • -
  • Module – Representation of a Python module or package containing - documented members.
    • -
  • DocObject – Recursive structure representing Python objects such as - classes, functions, methods, and attributes.
    • -
-

These models are intentionally renderer-agnostic, allowing the same -documentation structure to be transformed into multiple output formats -(e.g., MkDocs, MCP, or other renderers).

-
- - - -
- - - - - - -

Classes

- -
- - - -

- DocObject - - -

-
1
-2
-3
-4
-5
-6
-7
DocObject(
-    name: str,
-    kind: str,
-    path: str,
-    signature: str | None = None,
-    docstring: str | None = None,
-)
-
- -
- - -

Representation of a documented Python object.

-

A DocObject models a single Python entity discovered during -introspection. Objects may contain nested members, allowing the structure -of modules, classes, and other containers to be represented recursively.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
name - str - -
-

Local name of the object.

-
-
kind - str - -
-

Type of object (for example class, function, method, or attribute).

-
-
path - str - -
-

Fully qualified dotted path to the object.

-
-
signature - str | None - -
-

Callable signature if the object represents a callable.

-
-
docstring - str | None - -
-

Raw docstring text extracted from the source code.

-
-
members - dict[str, DocObject] - -
-

Mapping of member names to child DocObject instances.

-
-
- -

Initialize a DocObject instance.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
name - str - -
-

Local name of the object.

-
- 		- required -
kind - str - -
-

Object type identifier (for example class or function).

-
- 		- required -
path - str - -
-

Fully qualified dotted path of the object.

-
- 		- required -
signature - str | None - -
-

Callable signature if applicable.

-
- 		- None -
docstring - str | None - -
-

Documentation string associated with the object.

-
- 		- None -
- - - - -
- - - - - - - -
Functions
- -
- - -
- add_member - - -
-
1
add_member(obj: DocObject) -> None
-
- -
- -

Add a child documentation object.

-

This is typically used when attaching methods to classes or -nested objects to their parent containers.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
obj - DocObject - -
-

Documentation object to add as a member.

-
- 		- required -
- -
- -
- -
- - -
- get_all_members - - -
-
1
get_all_members() -> Iterable[DocObject]
-
- -
- -

Return all child members of the object.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Iterable[DocObject] - -
-

Iterable[DocObject]: -An iterable of DocObject instances representing nested members.

-
-
- -
- -
- -
- - -
- get_member - - -
-
1
get_member(name: str) -> DocObject
-
- -
- -

Retrieve a member object by name.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
name - str - -
-

Name of the member to retrieve.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
DocObject - DocObject - -
-

The corresponding DocObject instance.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- KeyError - -
-

If the member does not exist.

-
-
- -
- -
- - - -
- -
- -
- -
- - - -

- Module - - -

-
1
Module(path: str, docstring: str | None = None)
-
- -
- - -

Representation of a documented Python module or package.

-

A Module stores metadata about the module itself and maintains a -collection of top-level documentation objects discovered during -introspection.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
path - str - -
-

Dotted import path of the module.

-
-
docstring - str | None - -
-

Module-level documentation string, if present.

-
-
members - dict[str, DocObject] - -
-

Mapping of object names to their corresponding DocObject representations.

-
-
- -

Initialize a Module instance.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - str - -
-

Dotted import path identifying the module.

-
- 		- required -
docstring - str | None - -
-

Module-level documentation text, if available.

-
- 		- None -
- - - - -
- - - - - - - -
Functions
- -
- - -
- add_object - - -
-
1
add_object(obj: DocObject) -> None
-
- -
- -

Add a documented object to the module.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
obj - DocObject - -
-

Documentation object to register as a top-level member of the module.

-
- 		- required -
- -
- -
- -
- - -
- get_all_objects - - -
-
1
get_all_objects() -> Iterable[DocObject]
-
- -
- -

Return all top-level documentation objects in the module.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Iterable[DocObject] - -
-

Iterable[DocObject]: -An iterable of DocObject instances representing the module's public members.

-
-
- -
- -
- -
- - -
- get_object - - -
-
1
get_object(name: str) -> DocObject
-
- -
- -

Retrieve a documented object by name.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
name - str - -
-

Name of the object to retrieve.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
DocObject - DocObject - -
-

The corresponding DocObject instance.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- KeyError - -
-

If no object with the given name exists.

-
-
- -
- -
- - - -
- -
- -
- -
- - - -

- Project - - -

-
1
Project(name: str)
-
- -
- - -

Representation of a documentation project.

-

A Project serves as the root container for all modules discovered during -introspection. Each module is stored by its dotted import path.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
name - str - -
-

Name of the project.

-
-
modules - dict[str, Module] - -
-

Mapping of module paths to Module instances.

-
-
- -

Initialize a Project instance.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
name - str - -
-

Name used to identify the documentation project.

-
- 		- required -
- - -
- Example -

Create a project and register a module:

-
1
-2
-3
-4
```python
-project = Project("mypackage")
-project.add_module(module)
-```
-
-
- - - -
- - - - - - - -
Functions
- -
- - -
- add_module - - -
-
1
add_module(module: Module) -> None
-
- -
- -

Register a module in the project.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
module - Module - -
-

Module instance to add to the project.

-
- 		- required -
- -
- -
- -
- - -
- get_all_modules - - -
-
1
get_all_modules() -> Iterable[Module]
-
- -
- -

Return all modules contained in the project.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Iterable[Module] - -
-

Iterable[Module]: -An iterable of Module instances.

-
-
- -
- -
- -
- - -
- get_module - - -
-
1
get_module(path: str) -> Module
-
- -
- -

Retrieve a module by its dotted path.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - str - -
-

Fully qualified dotted module path (for example pkg.module).

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
Module - Module - -
-

The corresponding Module instance.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- KeyError - -
-

If the module does not exist in the project.

-
-
- -
- -
- -
- - -
- get_module_list - - -
-
1
get_module_list() -> list[str]
-
- -
- -

Return the list of module import paths.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- list[str] - -
-

list[str]: -A list containing the dotted paths of all modules in the project.

-
-
- -
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/models/module/index.html b/doc-forge/lib/docforge/models/module/index.html deleted file mode 100644 index b37ad8d..0000000 --- a/doc-forge/lib/docforge/models/module/index.html +++ /dev/null @@ -1,1520 +0,0 @@ - - - - - - - - - - - - - - - - - - - Module - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Module

- - -
- - - -

- docforge.models.module - - -

- -
- -

Summary

-

Documentation model representing a Python module or package.

-

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

Classes

- -
- - - -

- Module - - -

-
1
Module(path: str, docstring: str | None = None)
-
- -
- - -

Representation of a documented Python module or package.

-

A Module stores metadata about the module itself and maintains a -collection of top-level documentation objects discovered during -introspection.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
path - str - -
-

Dotted import path of the module.

-
-
docstring - str | None - -
-

Module-level documentation string, if present.

-
-
members - dict[str, DocObject] - -
-

Mapping of object names to their corresponding DocObject representations.

-
-
- -

Initialize a Module instance.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - str - -
-

Dotted import path identifying the module.

-
- 		- required -
docstring - str | None - -
-

Module-level documentation text, if available.

-
- 		- None -
- - - - -
- - - - - - - -
Functions
- -
- - -
- add_object - - -
-
1
add_object(obj: DocObject) -> None
-
- -
- -

Add a documented object to the module.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
obj - DocObject - -
-

Documentation object to register as a top-level member of the module.

-
- 		- required -
- -
- -
- -
- - -
- get_all_objects - - -
-
1
get_all_objects() -> Iterable[DocObject]
-
- -
- -

Return all top-level documentation objects in the module.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Iterable[DocObject] - -
-

Iterable[DocObject]: -An iterable of DocObject instances representing the module's public members.

-
-
- -
- -
- -
- - -
- get_object - - -
-
1
get_object(name: str) -> DocObject
-
- -
- -

Retrieve a documented object by name.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
name - str - -
-

Name of the object to retrieve.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
DocObject - DocObject - -
-

The corresponding DocObject instance.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- KeyError - -
-

If no object with the given name exists.

-
-
- -
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/models/object/index.html b/doc-forge/lib/docforge/models/object/index.html deleted file mode 100644 index b8378b8..0000000 --- a/doc-forge/lib/docforge/models/object/index.html +++ /dev/null @@ -1,1610 +0,0 @@ - - - - - - - - - - - - - - - - - - - Object - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Object

- - -
- - - -

- docforge.models.object - - -

- -
- -

Summary

-

Documentation model representing individual Python objects.

-

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

Classes

- -
- - - -

- DocObject - - -

-
1
-2
-3
-4
-5
-6
-7
DocObject(
-    name: str,
-    kind: str,
-    path: str,
-    signature: str | None = None,
-    docstring: str | None = None,
-)
-
- -
- - -

Representation of a documented Python object.

-

A DocObject models a single Python entity discovered during -introspection. Objects may contain nested members, allowing the structure -of modules, classes, and other containers to be represented recursively.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
name - str - -
-

Local name of the object.

-
-
kind - str - -
-

Type of object (for example class, function, method, or attribute).

-
-
path - str - -
-

Fully qualified dotted path to the object.

-
-
signature - str | None - -
-

Callable signature if the object represents a callable.

-
-
docstring - str | None - -
-

Raw docstring text extracted from the source code.

-
-
members - dict[str, DocObject] - -
-

Mapping of member names to child DocObject instances.

-
-
- -

Initialize a DocObject instance.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
name - str - -
-

Local name of the object.

-
- 		- required -
kind - str - -
-

Object type identifier (for example class or function).

-
- 		- required -
path - str - -
-

Fully qualified dotted path of the object.

-
- 		- required -
signature - str | None - -
-

Callable signature if applicable.

-
- 		- None -
docstring - str | None - -
-

Documentation string associated with the object.

-
- 		- None -
- - - - -
- - - - - - - -
Functions
- -
- - -
- add_member - - -
-
1
add_member(obj: DocObject) -> None
-
- -
- -

Add a child documentation object.

-

This is typically used when attaching methods to classes or -nested objects to their parent containers.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
obj - DocObject - -
-

Documentation object to add as a member.

-
- 		- required -
- -
- -
- -
- - -
- get_all_members - - -
-
1
get_all_members() -> Iterable[DocObject]
-
- -
- -

Return all child members of the object.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Iterable[DocObject] - -
-

Iterable[DocObject]: -An iterable of DocObject instances representing nested members.

-
-
- -
- -
- -
- - -
- get_member - - -
-
1
get_member(name: str) -> DocObject
-
- -
- -

Retrieve a member object by name.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
name - str - -
-

Name of the member to retrieve.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
DocObject - DocObject - -
-

The corresponding DocObject instance.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- KeyError - -
-

If the member does not exist.

-
-
- -
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/models/project/index.html b/doc-forge/lib/docforge/models/project/index.html deleted file mode 100644 index de741f6..0000000 --- a/doc-forge/lib/docforge/models/project/index.html +++ /dev/null @@ -1,1559 +0,0 @@ - - - - - - - - - - - - - - - - - - - Project - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Project

- - -
- - - -

- docforge.models.project - - -

- -
- -

Summary

-

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

Classes

- -
- - - -

- Project - - -

-
1
Project(name: str)
-
- -
- - -

Representation of a documentation project.

-

A Project serves as the root container for all modules discovered during -introspection. Each module is stored by its dotted import path.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
name - str - -
-

Name of the project.

-
-
modules - dict[str, Module] - -
-

Mapping of module paths to Module instances.

-
-
- -

Initialize a Project instance.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
name - str - -
-

Name used to identify the documentation project.

-
- 		- required -
- - -
- Example -

Create a project and register a module:

-
1
-2
-3
-4
```python
-project = Project("mypackage")
-project.add_module(module)
-```
-
-
- - - -
- - - - - - - -
Functions
- -
- - -
- add_module - - -
-
1
add_module(module: Module) -> None
-
- -
- -

Register a module in the project.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
module - Module - -
-

Module instance to add to the project.

-
- 		- required -
- -
- -
- -
- - -
- get_all_modules - - -
-
1
get_all_modules() -> Iterable[Module]
-
- -
- -

Return all modules contained in the project.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Iterable[Module] - -
-

Iterable[Module]: -An iterable of Module instances.

-
-
- -
- -
- -
- - -
- get_module - - -
-
1
get_module(path: str) -> Module
-
- -
- -

Retrieve a module by its dotted path.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - str - -
-

Fully qualified dotted module path (for example pkg.module).

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
Module - Module - -
-

The corresponding Module instance.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- KeyError - -
-

If the module does not exist in the project.

-
-
- -
- -
- -
- - -
- get_module_list - - -
-
1
get_module_list() -> list[str]
-
- -
- -

Return the list of module import paths.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- list[str] - -
-

list[str]: -A list containing the dotted paths of all modules in the project.

-
-
- -
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/nav/index.html b/doc-forge/lib/docforge/nav/index.html deleted file mode 100644 index 3c51910..0000000 --- a/doc-forge/lib/docforge/nav/index.html +++ /dev/null @@ -1,2283 +0,0 @@ - - - - - - - - - - - - - - - - - - - Nav - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Nav

- - -
- - - -

- docforge.nav - - -

- -
- -

Navigation layer for doc-forge.

-

The docforge.nav package manages the relationship between the logical -documentation structure defined by the user and the physical documentation -files generated on disk.

-
-

Workflow

-
    -
  1. Specification – Users define navigation intent in docforge.nav.yml.
    2. -
  2. Resolution – resolve_nav expands patterns and matches them against - generated Markdown files.
    3. -
  3. Emission – MkDocsNavEmitter converts the resolved structure into - the YAML navigation format required by mkdocs.yml.
    4. -
-

This layer separates documentation organization from the underlying source -code layout, enabling flexible grouping, ordering, and navigation structures -independent of module hierarchy.

-
- - - -
- - - - - - -

Classes

- -
- - - -

- MkDocsNavEmitter - - -

- - -
- - -

Emit MkDocs navigation structures from resolved navigation data.

-

The emitter transforms a ResolvedNav object into the YAML-compatible -list structure expected by the MkDocs nav configuration field.

- - - - -
- - - - - - - -
Functions
- -
- - -
- emit - - -
-
1
emit(nav: ResolvedNav) -> list[dict[str, Any]]
-
- -
- -

Generate a navigation structure for mkdocs.yml.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
nav - ResolvedNav - -
-

Resolved navigation data describing documentation groups -and their associated Markdown files.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- list[dict[str, Any]] - -
-

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.

-
-
- -
- -
- - - -
- -
- -
- -
- - - -

- NavSpec - - -

-
1
-2
-3
-4
-5
NavSpec(
-    home: str | None,
-    groups: dict[str, list[str]],
-    icon: dict[str, str] | None = None,
-)
-
- -
- - -

Parsed representation of a navigation specification.

-

A NavSpec describes the intended documentation navigation layout before -it is resolved against the filesystem.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
home - str | None - -
-

Relative path to the documentation home page (for example -index.md).

-
-
groups - dict[str, list[str]] - -
-

Mapping of navigation group titles to lists of file patterns -or glob expressions.

-
-
icon - -
-

Optional mapping of theme icon entries (for example -{"logo": "material/code-tags"}) injected into the MkDocs -theme as theme.icon.

-
-
- -

Initialize a NavSpec instance.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
home - str | None - -
-

Relative path to the home document.

-
- 		- required -
groups - dict[str, list[str]] - -
-

Mapping of group names to lists of path patterns -(glob expressions).

-
- 		- required -
icon - dict[str, str] | None - -
-

Optional mapping of theme icon entries applied to the -generated MkDocs configuration.

-
- 		- None -
- - - - -
- - - - - - - -
Functions
- -
- - -
- all_patterns - - -
-
1
all_patterns() -> list[str]
-
- -
- -

Return all path patterns referenced by the specification.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- list[str] - -
-

list[str]: -A list containing the home document (if defined) and all -group pattern entries.

-
-
- -
- -
- -
- - -
- load - - - - classmethod - - -
-
1
load(path: Path) -> NavSpec
-
- -
- -

Load a navigation specification from a YAML file.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - Path - -
-

Filesystem path to the navigation specification file.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
NavSpec - NavSpec - -
-

A NavSpec instance representing the parsed configuration.

-
-
- - -

Raises:

- - - - - - - - - - - - - - - - - -
TypeDescription
- FileNotFoundError - -
-

If the specified file does not exist.

-
-
- ValueError - -
-

If the file contents are not a valid navigation -specification.

-
-
- -
- -
- - - -
- -
- -
- -
- - - -

- ResolvedNav - - -

-
1
-2
-3
-4
-5
ResolvedNav(
-    home: str | None,
-    groups: dict[str, list[Path]],
-    docs_root: Path | None = None,
-)
-
- -
- - -

Resolved navigation structure.

-

A ResolvedNav represents navigation data after glob patterns have been -expanded and paths validated against the filesystem.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
home - str | None - -
-

Relative path to the documentation home page.

-
-
groups - dict[str, list[Path]] - -
-

Mapping of navigation group titles to lists of resolved -documentation file paths.

-
-
- -

Initialize a ResolvedNav instance.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
home - str | None - -
-

Relative path to the home page within the documentation root.

-
- 		- required -
groups - dict[str, list[Path]] - -
-

Mapping of group titles to resolved documentation file paths.

-
- 		- required -
docs_root - Path | None - -
-

Root directory of the documentation source files.

-
- 		- None -
- - - - -
- - - - - - - -
Functions
- -
- - -
- all_files - - -
-
1
all_files() -> Iterable[Path]
-
- -
- -

Iterate over all files referenced by the navigation structure.

- - -

Yields:

- - - - - - - - - - - - - -
Name TypeDescription
Path - Iterable[Path] - -
-

A documentation file referenced by the navigation, including -the home page when defined.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- RuntimeError - -
-

If the home page is defined but the documentation -root is not available for resolution.

-
-
- -
- -
- - - -
- -
- -
-

Functions

- -
- - -

- build_wiki_nav - - -

-
1
build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]
-
- -
- -

Derive an MkDocs navigation block from a wiki directory.

-

Returned paths are relative to the parent of wiki_dir and carry the -wiki directory name as their leading component (for example -wiki/01_overview.md when the wiki lives at docs/wiki). This makes -the result directly usable in an MkDocs nav block with

-
    -
  • index.md at the wiki root becomes the Home entry.
    • -
  • Page labels are derived from filenames: numeric order prefixes such as - 01_ or 02- are stripped, separators are replaced with spaces, and - names are title-cased (01_overview.md becomes Overview).
    • -
  • Subdirectories become nested navigation groups. A nested index.md is - rendered as the section root placed first inside the group.
    • -
  • Only .md files are considered; hidden entries are ignored.
    • -
- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
wiki_dir - Path - -
-

Path to the hand-written wiki directory, for example docs/wiki.

-
- 		- required -
- - -

Returns:

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

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- FileNotFoundError - -
-

If the wiki directory does not exist.

-
-
- -
- -
- -
- - -

- load_nav_spec - - -

-
1
load_nav_spec(path: Path) -> NavSpec
-
- -
- -

Load a navigation specification file.

-

This helper function reads a YAML navigation file and constructs a -corresponding NavSpec instance.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - Path - -
-

Path to the navigation specification file.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
NavSpec - NavSpec - -
-

A NavSpec instance representing the parsed specification.

-
-
- - -

Raises:

- - - - - - - - - - - - - - - - - -
TypeDescription
- FileNotFoundError - -
-

If the specification file does not exist.

-
-
- ValueError - -
-

If the YAML structure is invalid.

-
-
- -
- -
- -
- - -

- resolve_nav - - -

-
1
resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav
-
- -
- -

Resolve a navigation specification against the filesystem.

-

The function expands glob patterns defined in a NavSpec and verifies -that referenced documentation files exist within the documentation root.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
spec - NavSpec - -
-

Navigation specification describing documentation layout.

-
- 		- required -
docs_root - Path - -
-

Root directory containing documentation Markdown files.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
ResolvedNav - ResolvedNav - -
-

A ResolvedNav instance containing validated navigation paths.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- FileNotFoundError - -
-

If the documentation root does not exist or a -navigation pattern does not match any files.

-
-
- -
- -
- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/nav/mkdocs/index.html b/doc-forge/lib/docforge/nav/mkdocs/index.html deleted file mode 100644 index 31cdcb8..0000000 --- a/doc-forge/lib/docforge/nav/mkdocs/index.html +++ /dev/null @@ -1,1288 +0,0 @@ - - - - - - - - - - - - - - - - - - - Mkdocs - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Mkdocs

- - -
- - - -

- docforge.nav.mkdocs - - -

- -
- -

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

Classes

- -
- - - -

- MkDocsNavEmitter - - -

- - -
- - -

Emit MkDocs navigation structures from resolved navigation data.

-

The emitter transforms a ResolvedNav object into the YAML-compatible -list structure expected by the MkDocs nav configuration field.

- - - - -
- - - - - - - -
Functions
- -
- - -
- emit - - -
-
1
emit(nav: ResolvedNav) -> list[dict[str, Any]]
-
- -
- -

Generate a navigation structure for mkdocs.yml.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
nav - ResolvedNav - -
-

Resolved navigation data describing documentation groups -and their associated Markdown files.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- list[dict[str, Any]] - -
-

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.

-
-
- -
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/nav/resolver/index.html b/doc-forge/lib/docforge/nav/resolver/index.html deleted file mode 100644 index b05befa..0000000 --- a/doc-forge/lib/docforge/nav/resolver/index.html +++ /dev/null @@ -1,1519 +0,0 @@ - - - - - - - - - - - - - - - - - - - Resolver - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Resolver

- - -
- - - -

- docforge.nav.resolver - - -

- -
- -

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

Classes

- -
- - - -

- ResolvedNav - - -

-
1
-2
-3
-4
-5
ResolvedNav(
-    home: str | None,
-    groups: dict[str, list[Path]],
-    docs_root: Path | None = None,
-)
-
- -
- - -

Resolved navigation structure.

-

A ResolvedNav represents navigation data after glob patterns have been -expanded and paths validated against the filesystem.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
home - str | None - -
-

Relative path to the documentation home page.

-
-
groups - dict[str, list[Path]] - -
-

Mapping of navigation group titles to lists of resolved -documentation file paths.

-
-
- -

Initialize a ResolvedNav instance.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
home - str | None - -
-

Relative path to the home page within the documentation root.

-
- 		- required -
groups - dict[str, list[Path]] - -
-

Mapping of group titles to resolved documentation file paths.

-
- 		- required -
docs_root - Path | None - -
-

Root directory of the documentation source files.

-
- 		- None -
- - - - -
- - - - - - - -
Functions
- -
- - -
- all_files - - -
-
1
all_files() -> Iterable[Path]
-
- -
- -

Iterate over all files referenced by the navigation structure.

- - -

Yields:

- - - - - - - - - - - - - -
Name TypeDescription
Path - Iterable[Path] - -
-

A documentation file referenced by the navigation, including -the home page when defined.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- RuntimeError - -
-

If the home page is defined but the documentation -root is not available for resolution.

-
-
- -
- -
- - - -
- -
- -
-

Functions

- -
- - -

- resolve_nav - - -

-
1
resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav
-
- -
- -

Resolve a navigation specification against the filesystem.

-

The function expands glob patterns defined in a NavSpec and verifies -that referenced documentation files exist within the documentation root.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
spec - NavSpec - -
-

Navigation specification describing documentation layout.

-
- 		- required -
docs_root - Path - -
-

Root directory containing documentation Markdown files.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
ResolvedNav - ResolvedNav - -
-

A ResolvedNav instance containing validated navigation paths.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- FileNotFoundError - -
-

If the documentation root does not exist or a -navigation pattern does not match any files.

-
-
- -
- -
- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/nav/spec/index.html b/doc-forge/lib/docforge/nav/spec/index.html deleted file mode 100644 index ef8232f..0000000 --- a/doc-forge/lib/docforge/nav/spec/index.html +++ /dev/null @@ -1,1626 +0,0 @@ - - - - - - - - - - - - - - - - - - - Spec - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Spec

- - -
- - - -

- docforge.nav.spec - - -

- -
- -

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

Classes

- -
- - - -

- NavSpec - - -

-
1
-2
-3
-4
-5
NavSpec(
-    home: str | None,
-    groups: dict[str, list[str]],
-    icon: dict[str, str] | None = None,
-)
-
- -
- - -

Parsed representation of a navigation specification.

-

A NavSpec describes the intended documentation navigation layout before -it is resolved against the filesystem.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
home - str | None - -
-

Relative path to the documentation home page (for example -index.md).

-
-
groups - dict[str, list[str]] - -
-

Mapping of navigation group titles to lists of file patterns -or glob expressions.

-
-
icon - -
-

Optional mapping of theme icon entries (for example -{"logo": "material/code-tags"}) injected into the MkDocs -theme as theme.icon.

-
-
- -

Initialize a NavSpec instance.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
home - str | None - -
-

Relative path to the home document.

-
- 		- required -
groups - dict[str, list[str]] - -
-

Mapping of group names to lists of path patterns -(glob expressions).

-
- 		- required -
icon - dict[str, str] | None - -
-

Optional mapping of theme icon entries applied to the -generated MkDocs configuration.

-
- 		- None -
- - - - -
- - - - - - - -
Functions
- -
- - -
- all_patterns - - -
-
1
all_patterns() -> list[str]
-
- -
- -

Return all path patterns referenced by the specification.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- list[str] - -
-

list[str]: -A list containing the home document (if defined) and all -group pattern entries.

-
-
- -
- -
- -
- - -
- load - - - - classmethod - - -
-
1
load(path: Path) -> NavSpec
-
- -
- -

Load a navigation specification from a YAML file.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - Path - -
-

Filesystem path to the navigation specification file.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
NavSpec - NavSpec - -
-

A NavSpec instance representing the parsed configuration.

-
-
- - -

Raises:

- - - - - - - - - - - - - - - - - -
TypeDescription
- FileNotFoundError - -
-

If the specified file does not exist.

-
-
- ValueError - -
-

If the file contents are not a valid navigation -specification.

-
-
- -
- -
- - - -
- -
- -
-

Functions

- -
- - -

- load_nav_spec - - -

-
1
load_nav_spec(path: Path) -> NavSpec
-
- -
- -

Load a navigation specification file.

-

This helper function reads a YAML navigation file and constructs a -corresponding NavSpec instance.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - Path - -
-

Path to the navigation specification file.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
NavSpec - NavSpec - -
-

A NavSpec instance representing the parsed specification.

-
-
- - -

Raises:

- - - - - - - - - - - - - - - - - -
TypeDescription
- FileNotFoundError - -
-

If the specification file does not exist.

-
-
- ValueError - -
-

If the YAML structure is invalid.

-
-
- -
- -
- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/nav/wiki/index.html b/doc-forge/lib/docforge/nav/wiki/index.html deleted file mode 100644 index 7a2233a..0000000 --- a/doc-forge/lib/docforge/nav/wiki/index.html +++ /dev/null @@ -1,1273 +0,0 @@ - - - - - - - - - - - - - - - - - - - Wiki - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Wiki

- - -
- - - -

- docforge.nav.wiki - - -

- -
- -

Summary

-

Wiki navigation derivation.

-

This module provides build_wiki_nav, which derives an MkDocs-ready -navigation block from the file structure of a hand-written wiki directory -(typically docs/wiki). wiki content is authored by hand and is never -modified by doc-forge; only the navigation layout is inferred.

-

Notes

-
    -
  • index.md at the wiki root becomes the Home entry.
    • -
  • Page labels are derived from filenames: numeric order prefixes such as - 01_ or 02- are stripped, separators are replaced with spaces, and - names are title-cased (01_overview.md becomes Overview).
    • -
  • Subdirectories become nested navigation groups. A nested index.md is - rendered as the section root placed first inside the group.
    • -
  • Only .md files are considered; hidden entries are ignored.
    • -
- - - -
- - - - - - - -

Functions

- -
- - -

- build_wiki_nav - - -

-
1
build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]
-
- -
- -

Derive an MkDocs navigation block from a wiki directory.

-

Returned paths are relative to the parent of wiki_dir and carry the -wiki directory name as their leading component (for example -wiki/01_overview.md when the wiki lives at docs/wiki). This makes -the result directly usable in an MkDocs nav block with

-
    -
  • index.md at the wiki root becomes the Home entry.
    • -
  • Page labels are derived from filenames: numeric order prefixes such as - 01_ or 02- are stripped, separators are replaced with spaces, and - names are title-cased (01_overview.md becomes Overview).
    • -
  • Subdirectories become nested navigation groups. A nested index.md is - rendered as the section root placed first inside the group.
    • -
  • Only .md files are considered; hidden entries are ignored.
    • -
- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
wiki_dir - Path - -
-

Path to the hand-written wiki directory, for example docs/wiki.

-
- 		- required -
- - -

Returns:

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

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- FileNotFoundError - -
-

If the wiki directory does not exist.

-
-
- -
- -
- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/renderers/base/index.html b/doc-forge/lib/docforge/renderers/base/index.html deleted file mode 100644 index dc16971..0000000 --- a/doc-forge/lib/docforge/renderers/base/index.html +++ /dev/null @@ -1,1422 +0,0 @@ - - - - - - - - - - - - - - - - - - - Base - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Base

- - -
- - - -

- docforge.renderers.base - - -

- -
- -

Summary

-

Renderer base interfaces and configuration models.

-

This module defines the base protocol and configuration container used by -doc-forge renderers. Concrete renderer implementations should implement the -DocRenderer protocol.

- - - -
- - - - - - -

Classes

- -
- - - -

- DocRenderer - - -

- - -
-

- Bases: Protocol

- - -

Protocol defining the interface for documentation renderers.

-

Implementations of this protocol are responsible for transforming a -Project model into renderer-specific documentation sources.

- - - - -
- - - - - - - -
Functions
- -
- - -
- generate_sources - - -
-
1
generate_sources(project: Project, out_dir: Path) -> None
-
- -
- -

Generate renderer-specific documentation sources.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
project - Project - -
-

Project model containing modules and documentation objects.

-
- 		- required -
out_dir - Path - -
-

Directory where generated documentation sources should be written.

-
- 		- required -
- -
- -
- - - -
- -
- -
- -
- - - -

- RendererConfig - - -

-
1
RendererConfig(out_dir: Path, project: Project)
-
- -
- - -

Configuration container for documentation renderers.

-

A RendererConfig instance groups together the project model and the -output directory used during rendering.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
out_dir - Path - -
-

Directory where generated documentation files will be written.

-
-
project - Project - -
-

Documentation project model to be rendered.

-
-
- -

Initialize a RendererConfig instance.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
out_dir - Path - -
-

Target directory where documentation files should be written.

-
- 		- required -
project - Project - -
-

Introspected project model to render.

-
- 		- required -
- - - - -
- - - - - - - -
Functions
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/renderers/index.html b/doc-forge/lib/docforge/renderers/index.html deleted file mode 100644 index 38fd766..0000000 --- a/doc-forge/lib/docforge/renderers/index.html +++ /dev/null @@ -1,1601 +0,0 @@ - - - - - - - - - - - - - - - - - - - Renderers - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Renderers

- - -
- - - -

- docforge.renderers - - -

- -
- -

Summary

-

Renderers layer for doc-forge.

-

The docforge.renderers package transforms the internal documentation -models into files formatted for specific documentation systems.

-
-

Overview

-

Renderers consume the doc-forge project model and generate output suitable -for documentation tools or machine interfaces.

-

Current implementations:

-
    -
  • MkDocsRenderer – Produces Markdown files compatible with MkDocs and - the mkdocstrings plugin. It automatically handles package hierarchy - and generates index.md files for packages.
    • -
  • MCPRenderer – Emits structured JSON resources designed for consumption - by Model Context Protocol (MCP) clients.
    • -
-
-

Extending

-

New renderers can be added by implementing the DocRenderer protocol -defined in docforge.renderers.base.

-
- - - -
- - - - - - -

Classes

- -
- - - -

- MCPRenderer - - -

- - -
- - -

Renderer that generates MCP-compatible documentation resources.

-

This renderer converts doc-forge project models into structured JSON -resources suitable for consumption by systems implementing the Model -Context Protocol (MCP).

- - - - -
- - - - - - - -
Functions
- -
- - -
- generate_sources - - -
-
1
generate_sources(project: Project, out_dir: Path) -> None
-
- -
- -

Generate MCP documentation resources for a project.

-

The renderer serializes each module into a JSON resource and produces -supporting metadata files such as nav.json and index.json.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
project - Project - -
-

Documentation project model to render.

-
- 		- required -
out_dir - Path - -
-

Directory where MCP resources will be written.

-
- 		- required -
- -
- -
- - - -
- -
- -
- -
- - - -

- MkDocsRenderer - - -

- - -
- - -

Renderer that produces Markdown documentation for MkDocs.

-

Generated pages use mkdocstrings directives to reference Python modules, -allowing MkDocs to render API documentation dynamically.

- - - - -
- - - - - - - -
Functions
- -
- - -
- generate_readme - - -
-
1
-2
-3
-4
-5
-6
generate_readme(
-    project: Project,
-    docs_dir: Path,
-    module_is_source: bool | None = None,
-    readme_dir: Path | None = None,
-) -> None
-
- -
- -

Generate a README.md file from the root module docstring.

- - -
- Notes -
    -
  • If module_is_source is True, README.md is written to the - project root directory.
    • -
  • If False, README generation is currently not implemented.
    • -
-
- -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
project - Project - -
-

Project model containing documentation metadata.

-
- 		- required -
docs_dir - Path - -
-

Directory containing generated documentation sources.

-
- 		- required -
module_is_source - bool | None - -
-

Whether the module is treated as the project source root.

-
- 		- None -
readme_dir - Path | None - -
-

Directory where the generated README.md should be written. -Defaults to the parent of docs_dir.

-
- 		- None -
- -
- -
- -
- - -
- generate_sources - - -
-
1
-2
-3
-4
-5
generate_sources(
-    project: Project,
-    out_dir: Path,
-    module_is_source: bool | None = None,
-) -> None
-
- -
- -

Generate Markdown documentation files for a project.

-

This method renders a documentation structure from the provided -project model and writes the resulting Markdown files to the -specified output directory.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
project - Project - -
-

Project model containing modules to document.

-
- 		- required -
out_dir - Path - -
-

Directory where generated Markdown files will be written.

-
- 		- required -
module_is_source - bool | None - -
-

If True, treat the specified module as the documentation root -rather than nesting it inside a folder.

-
- 		- None -
- -
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/renderers/mcp_renderer/index.html b/doc-forge/lib/docforge/renderers/mcp_renderer/index.html deleted file mode 100644 index 3ecc776..0000000 --- a/doc-forge/lib/docforge/renderers/mcp_renderer/index.html +++ /dev/null @@ -1,1277 +0,0 @@ - - - - - - - - - - - - - - - - - - - Mcp Renderer - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Mcp Renderer

- - -
- - - -

- docforge.renderers.mcp_renderer - - -

- -
- -

Summary

-

MCP renderer implementation.

-

This module defines the MCPRenderer class, which generates documentation -resources compatible with the Model Context Protocol (MCP).

- - - -
- - - - - - -

Classes

- -
- - - -

- MCPRenderer - - -

- - -
- - -

Renderer that generates MCP-compatible documentation resources.

-

This renderer converts doc-forge project models into structured JSON -resources suitable for consumption by systems implementing the Model -Context Protocol (MCP).

- - - - -
- - - - - - - -
Functions
- -
- - -
- generate_sources - - -
-
1
generate_sources(project: Project, out_dir: Path) -> None
-
- -
- -

Generate MCP documentation resources for a project.

-

The renderer serializes each module into a JSON resource and produces -supporting metadata files such as nav.json and index.json.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
project - Project - -
-

Documentation project model to render.

-
- 		- required -
out_dir - Path - -
-

Directory where MCP resources will be written.

-
- 		- required -
- -
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/renderers/mkdocs_renderer/index.html b/doc-forge/lib/docforge/renderers/mkdocs_renderer/index.html deleted file mode 100644 index fea679e..0000000 --- a/doc-forge/lib/docforge/renderers/mkdocs_renderer/index.html +++ /dev/null @@ -1,1427 +0,0 @@ - - - - - - - - - - - - - - - - - - - Mkdocs Renderer - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Mkdocs Renderer

- - -
- - - -

- docforge.renderers.mkdocs_renderer - - -

- -
- -

Summary

-

MkDocs renderer implementation.

-

This module defines the MkDocsRenderer class, which generates Markdown -documentation sources compatible with MkDocs Material and the mkdocstrings -plugin.

-

The renderer ensures a consistent documentation structure by:

-
    -
  • Creating a root index.md if one does not exist
    • -
  • Generating package index pages automatically
    • -
  • Linking child modules within parent package pages
    • -
  • Optionally generating README.md from the root package docstring
    • -
- - - -
- - - - - - -

Classes

- -
- - - -

- MkDocsRenderer - - -

- - -
- - -

Renderer that produces Markdown documentation for MkDocs.

-

Generated pages use mkdocstrings directives to reference Python modules, -allowing MkDocs to render API documentation dynamically.

- - - - -
- - - - - - - -
Functions
- -
- - -
- generate_readme - - -
-
1
-2
-3
-4
-5
-6
generate_readme(
-    project: Project,
-    docs_dir: Path,
-    module_is_source: bool | None = None,
-    readme_dir: Path | None = None,
-) -> None
-
- -
- -

Generate a README.md file from the root module docstring.

- - -
- Notes -
    -
  • If module_is_source is True, README.md is written to the - project root directory.
    • -
  • If False, README generation is currently not implemented.
    • -
-
- -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
project - Project - -
-

Project model containing documentation metadata.

-
- 		- required -
docs_dir - Path - -
-

Directory containing generated documentation sources.

-
- 		- required -
module_is_source - bool | None - -
-

Whether the module is treated as the project source root.

-
- 		- None -
readme_dir - Path | None - -
-

Directory where the generated README.md should be written. -Defaults to the parent of docs_dir.

-
- 		- None -
- -
- -
- -
- - -
- generate_sources - - -
-
1
-2
-3
-4
-5
generate_sources(
-    project: Project,
-    out_dir: Path,
-    module_is_source: bool | None = None,
-) -> None
-
- -
- -

Generate Markdown documentation files for a project.

-

This method renders a documentation structure from the provided -project model and writes the resulting Markdown files to the -specified output directory.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
project - Project - -
-

Project model containing modules to document.

-
- 		- required -
out_dir - Path - -
-

Directory where generated Markdown files will be written.

-
- 		- required -
module_is_source - bool | None - -
-

If True, treat the specified module as the documentation root -rather than nesting it inside a folder.

-
- 		- None -
- -
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/servers/index.html b/doc-forge/lib/docforge/servers/index.html deleted file mode 100644 index 44bab25..0000000 --- a/doc-forge/lib/docforge/servers/index.html +++ /dev/null @@ -1,1357 +0,0 @@ - - - - - - - - - - - - - - - - - - - Servers - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Servers

- - -
- - - -

- docforge.servers - - -

- -
- -

Summary

-

Server layer for doc-forge.

-

This module exposes server implementations used to provide live access -to generated documentation resources. Currently, it includes the MCP -documentation server.

-
- - - -
- - - - - - -

Classes

- -
- - - -

- MCPServer - - -

-
1
MCPServer(mcp_root: Path, name: str)
-
- -
- - -

MCP server for serving a pre-generated documentation bundle.

-

The server exposes documentation resources and diagnostic tools through -MCP endpoints backed by JSON files generated by the MCP renderer.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
mcp_root - Path - -
-

Directory containing the generated MCP documentation bundle.

-
-
app - FastMCP - -
-

Underlying FastMCP application instance that registers resources -and tools.

-
-
- -

Initialize the MCP server.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
mcp_root - Path - -
-

Directory containing the generated MCP documentation bundle -(for example index.json, nav.json, and modules/).

-
- 		- required -
name - str - -
-

Identifier used for the MCP server instance.

-
- 		- required -
- - - - -
- - - - - - - -
Functions
- -
- - -
- run - - -
-
1
-2
-3
-4
-5
run(
-    transport: Literal[
-        "stdio", "sse", "streamable-http"
-    ] = "streamable-http",
-) -> None
-
- -
- -

Start the MCP server.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
transport - Literal['stdio', 'sse', 'streamable-http'] - -
-

Transport mechanism used by the MCP server. Supported options -include stdio, sse, and streamable-http.

-
- 		- 'streamable-http' -
- -
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/docforge/servers/mcp_server/index.html b/doc-forge/lib/docforge/servers/mcp_server/index.html deleted file mode 100644 index 8172de1..0000000 --- a/doc-forge/lib/docforge/servers/mcp_server/index.html +++ /dev/null @@ -1,1365 +0,0 @@ - - - - - - - - - - - - - - - - - - - Mcp Server - docforge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Mcp Server

- - -
- - - -

- docforge.servers.mcp_server - - -

- -
- -

Summary

-

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

Classes

- -
- - - -

- MCPServer - - -

-
1
MCPServer(mcp_root: Path, name: str)
-
- -
- - -

MCP server for serving a pre-generated documentation bundle.

-

The server exposes documentation resources and diagnostic tools through -MCP endpoints backed by JSON files generated by the MCP renderer.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
mcp_root - Path - -
-

Directory containing the generated MCP documentation bundle.

-
-
app - FastMCP - -
-

Underlying FastMCP application instance that registers resources -and tools.

-
-
- -

Initialize the MCP server.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
mcp_root - Path - -
-

Directory containing the generated MCP documentation bundle -(for example index.json, nav.json, and modules/).

-
- 		- required -
name - str - -
-

Identifier used for the MCP server instance.

-
- 		- required -
- - - - -
- - - - - - - -
Functions
- -
- - -
- run - - -
-
1
-2
-3
-4
-5
run(
-    transport: Literal[
-        "stdio", "sse", "streamable-http"
-    ] = "streamable-http",
-) -> None
-
- -
- -

Start the MCP server.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
transport - Literal['stdio', 'sse', 'streamable-http'] - -
-

Transport mechanism used by the MCP server. Supported options -include stdio, sse, and streamable-http.

-
- 		- 'streamable-http' -
- -
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/doc-forge/lib/index.html b/doc-forge/lib/index.html index c1ef901..0e72874 100644 --- a/doc-forge/lib/index.html +++ b/doc-forge/lib/index.html @@ -585,6 +585,15 @@ + + +
  • + + + Type parity ( docforge Summary Renderer-agnostic Python documentation compiler that converts Python docstrings into structured documentation for both humans (MkDocs) and machines (MCP / AI agents). doc-forge statically analyzes source code, builds a semantic model of modules, classes, functions, and attributes, and renders that model into documentation outputs without executing user code. Installation Install using pip: 1pip install doc-forge CLI usage Each site kind (lib, api, wiki) is built independently into site/{kind}. Build the library reference from a Python package: 1doc-forge build --mkdocs --module my_package Build the API reference from an OpenAPI spec: 1doc-forge build --api --openapi-spec spec.json Build the hand-written wiki: 1doc-forge build --wiki --site-name my_package Generate MCP JSON documentation: 1doc-forge build --mcp --module my_package Build several kinds in one pass: 1doc-forge build --mcp --mkdocs --wiki --module my_package Each enabled kind gets its own MkDocs config (docs/mkdocs.{lib,api,wiki}.yml) and its own site under site/. Serve a site locally: 1 2 3 4 5doc-forge serve --wiki # preview from docs/mkdocs.wiki.yml doc-forge serve --lib doc-forge serve --api # or any config directly: doc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml Serve MCP locally: 1doc-forge serve --mcp --module my_package Core concepts Loader Extracts symbols, signatures, and docstrings using static analysis. Semantic model Structured, renderer-agnostic representation of the API. Renderer Converts the semantic model into output formats such as MkDocs or MCP JSON. Symbol Any documentable object module class function method property attribute Architecture doc-forge follows a compiler architecture: Front-end: Static analysis of modules, classes, functions, type hints, and docstrings. Middle-end: Builds a semantic model describing symbols and relationships. Back-end: Renders documentation using interchangeable renderers. This architecture ensures deterministic documentation generation. Rendering pipeline Typical flow: 1 2 3 4 5 6 7 8 9Python package | Loader (static analysis) | Semantic model | Renderer | MkDocs site or MCP JSON Google-Styled Doc-Forge Convention (GSDFC) GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling. Docstrings are the single source of truth. doc-forge compiles docstrings but does not generate documentation content. Documentation follows the Python import hierarchy. Every public symbol should have a complete and accurate docstring. General rules Use Markdown headings at package and module level. Use Google-style structured sections at class, function, and method level. 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 --- Notes subsection grouping Group related information using labeled subsections. Example: 1 2 3 4 5 6 7 8 9 10 11 12 13Notes: **Guarantees:** - deterministic behavior **Lifecycle:** - created during initialization - reused across executions **Thread safety:** - safe for concurrent reads Example formatting Use indentation for examples. Indent section contents using four spaces. Use code blocks for example code. Example Single example: 1 2 3 4 5 6Example: ```python foo = Foo("example") process(foo, multiplier=2) ``` Multiple examples: 1 2 3 4 5 6 7 8 9 10 11 12 13Example: Create foo: ```python foo = Foo("example") ``` Run engine: ```python engine = BarEngine([foo]) engine.run() ``` 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. Separator rules Use horizontal separators only at docstring root level to separate sections: 1--- Allowed locations: package docstrings module docstrings major documentation sections Do not use separators inside code sections. Package docstrings Package docstrings act as the documentation home page. Recommended sections: 1 2 3 4 5 6 7 8 9# Summary # Installation # Quick start # CLI usage # Core concepts # Architecture # Rendering pipeline # Examples # Notes Example Package Doc String: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30''' # Summary Foo-bar processing framework. Provides tools for defining Foo objects and executing Bar pipelines. --- # Installation ```bash pip install foo-bar ``` --- # Quick start ```python from foobar import Foo, BarEngine foo = Foo("example") engine = BarEngine([foo]) result = engine.run() ``` --- ''' Module docstrings Module docstrings describe a subsystem. Recommended sections: 1 2 3# Summary # Examples # Notes Example Module Doc String: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23''' # Summary Foo execution subsystem. Provides utilities for executing Foo objects through Bar stages. --- Example: ```python from foobar.engine import BarEngine from foobar.foo import Foo foo = Foo("example") engine = BarEngine([foo]) engine.run() ``` --- ''' Class docstrings Class docstrings define object responsibility, lifecycle, and attributes. Recommended sections: 1 2 3 4Attributes: Notes: Example: Raises: Example Simple Foo: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29class Foo: ''' Represents a unit of work. Attributes: name (str): Identifier of the foo instance. value (int): Numeric value associated with foo. Notes: Guarantees: - instances are immutable after creation Lifecycle: - create instance - pass to processing engine Example: Create and inspect a Foo: ```python foo = Foo("example", value=42) print(foo.name) ``` ''' Complex Bar: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24class BarEngine: ''' Executes Foo objects through Bar stages. Attributes: foos (tuple[Foo, ...]): Foo instances managed by the engine. Notes: Guarantees: - deterministic execution order Example: Run engine: ```python foo1 = Foo("a") foo2 = Foo("b") engine = BarEngine([foo1, foo2]) engine.run() ``` ''' Function and method docstrings Function docstrings define API contracts. Recommended sections: 1 2 3 4 5 6Args: Returns: Raises: Yields: Notes: Example: Example Simple process method: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34def 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. Notes: Guarantees: - foo is not modified Example: Process foo: ```python foo = Foo("example", value=10) result = process(foo, multiplier=2) print(result) ``` ''' Multiple Examples: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32def combine(foo_a: Foo, foo_b: Foo) -> Foo: ''' Combine two Foo instances. Args: foo_a (Foo): First foo. foo_b (Foo): Second foo. Returns: Foo: Combined foo. Example: Basic usage: ```python foo1 = Foo("a") foo2 = Foo("b") combined = combine(foo1, foo2) ``` Pipeline usage: ```python engine = BarEngine([foo1, foo2]) engine.run() ``` ''' Property docstrings Properties must document return values. Example Property Doc String: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18```python @property def foos(self) -> tuple[Foo, ...]: ''' Return contained Foo instances. Returns: tuple[Foo, ...]: Stored foo objects. Example: ```python container = FooContainer() foos = container.foos ``` ''' ``` Attribute documentation Document attributes in class docstrings using Attributes:. Example Attribute Doc String: 1 2 3 4 5 6 7 8 9 10 11 12```python ''' Represents a processing stage. Attributes: id (str): Unique identifier. enabled (bool): Whether the stage is active. ''' ``` Type parity (.pyi stubs and py.typed) Documented APIs ship matching type information: Each .py module has a synchronized .pyi stub in the same package. Packages expose a py.typed marker so type checkers (and consumers) use the authored signatures instead of Any. When signatures change, update the .py implementation and its .pyi stub together. Doc-forge documents the docstrings in .py; the .pyi stub is the machine-consumable signature surface. Parsing guarantees GSDFC ensures doc-forge can deterministically extract: symbol kind (module, class, function, property, attribute) symbol name parameters return values attributes examples structured Notes subsections This enables: reliable MkDocs rendering deterministic MCP export accurate AI semantic interpretation Notes doc-forge never executes analyzed modules. Documentation is generated entirely through static analysis. Classes GriffeLoader 1GriffeLoader() Load Python modules using Griffe and convert them into doc-forge models. 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: Name Type Description _loader GriffeLoader Internal Griffe loader with dedicated module and line collections. Initialize the Griffe-backed loader. Creates an internal Griffe loader instance with dedicated collections for modules and source lines. Functions load_module 1load_module(path: str) -> Module Load and convert a single Python module. The module is introspected using Griffe and then transformed into a doc-forge Module model. Parameters: Name Type Description Default path str Dotted import path of the module. required Returns: Name Type Description Module Module A populated Module instance. Raises: Type Description 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: 1 2 3 4```python loader = GriffeLoader() module = loader.load_module("mypackage.submodule") ``` load_project 1 2 3 4 5load_project( module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None, ) -> Project Load multiple modules and assemble them into a Project model. Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object. Parameters: Name Type Description Default module_paths list[str] List of dotted module import paths to load. required project_name str | None Optional override for the project name. Defaults to the top-level name of the first module. None skip_import_errors bool | None If True, modules that fail to load will be skipped instead of raising an error. None Returns: Name Type Description Project Project A populated Project instance containing the loaded modules. Raises: Type Description ValueError If no module paths are provided. ImportError If a module fails to load and skip_import_errors is False. MCPRenderer Renderer that generates MCP-compatible documentation resources. This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP). Functions generate_sources 1generate_sources(project: Project, out_dir: Path) -> None Generate MCP documentation resources for a project. The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json. Parameters: Name Type Description Default project Project Documentation project model to render. required out_dir Path Directory where MCP resources will be written. required MkDocsRenderer Renderer that produces Markdown documentation for MkDocs. Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically. Functions generate_readme 1 2 3 4 5 6generate_readme( project: Project, docs_dir: Path, module_is_source: bool | None = None, readme_dir: Path | None = None, ) -> None Generate a README.md file from the root module docstring. Notes If module_is_source is True, README.md is written to the project root directory. If False, README generation is currently not implemented. Parameters: Name Type Description Default project Project Project model containing documentation metadata. required docs_dir Path Directory containing generated documentation sources. required module_is_source bool | None Whether the module is treated as the project source root. None readme_dir Path | None Directory where the generated README.md should be written. Defaults to the parent of docs_dir. None generate_sources 1 2 3 4 5generate_sources( project: Project, out_dir: Path, module_is_source: bool | None = None, ) -> None Generate Markdown documentation files for a project. This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory. Parameters: Name Type Description Default project Project Project model containing modules to document. required out_dir Path Directory where generated Markdown files will be written. required module_is_source bool | None If True, treat the specified module as the documentation root rather than nesting it inside a folder. None Functions discover_module_paths 1 2 3discover_module_paths( module_name: str, project_root: Path | None = None ) -> list[str] Discover Python modules within a package directory. The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths. Discovery rules: Directories containing __init__.py are treated as packages. Each .py file is treated as a module. Results are returned as dotted import paths. Parameters: Name Type Description Default module_name str Top-level package name to discover modules from. required project_root Path | None Root directory used to resolve module paths. If not provided, the current working directory is used. None Returns: Type Description list[str] list[str]: A sorted list of unique dotted module import paths. Raises: Type Description FileNotFoundError If the specified package directory does not exist. stubs and wzxhzdk:1) + + +
  • @@ -1830,6 +1839,15 @@ +
    • + +
  • + + + Type parity ( docforge Summary Renderer-agnostic Python documentation compiler that converts Python docstrings into structured documentation for both humans (MkDocs) and machines (MCP / AI agents). doc-forge statically analyzes source code, builds a semantic model of modules, classes, functions, and attributes, and renders that model into documentation outputs without executing user code. Installation Install using pip: 1pip install doc-forge CLI usage Each site kind (lib, api, wiki) is built independently into site/{kind}. Build the library reference from a Python package: 1doc-forge build --mkdocs --module my_package Build the API reference from an OpenAPI spec: 1doc-forge build --api --openapi-spec spec.json Build the hand-written wiki: 1doc-forge build --wiki --site-name my_package Generate MCP JSON documentation: 1doc-forge build --mcp --module my_package Build several kinds in one pass: 1doc-forge build --mcp --mkdocs --wiki --module my_package Each enabled kind gets its own MkDocs config (docs/mkdocs.{lib,api,wiki}.yml) and its own site under site/. Serve a site locally: 1 2 3 4 5doc-forge serve --wiki # preview from docs/mkdocs.wiki.yml doc-forge serve --lib doc-forge serve --api # or any config directly: doc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml Serve MCP locally: 1doc-forge serve --mcp --module my_package Core concepts Loader Extracts symbols, signatures, and docstrings using static analysis. Semantic model Structured, renderer-agnostic representation of the API. Renderer Converts the semantic model into output formats such as MkDocs or MCP JSON. Symbol Any documentable object module class function method property attribute Architecture doc-forge follows a compiler architecture: Front-end: Static analysis of modules, classes, functions, type hints, and docstrings. Middle-end: Builds a semantic model describing symbols and relationships. Back-end: Renders documentation using interchangeable renderers. This architecture ensures deterministic documentation generation. Rendering pipeline Typical flow: 1 2 3 4 5 6 7 8 9Python package | Loader (static analysis) | Semantic model | Renderer | MkDocs site or MCP JSON Google-Styled Doc-Forge Convention (GSDFC) GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling. Docstrings are the single source of truth. doc-forge compiles docstrings but does not generate documentation content. Documentation follows the Python import hierarchy. Every public symbol should have a complete and accurate docstring. General rules Use Markdown headings at package and module level. Use Google-style structured sections at class, function, and method level. 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 --- Notes subsection grouping Group related information using labeled subsections. Example: 1 2 3 4 5 6 7 8 9 10 11 12 13Notes: **Guarantees:** - deterministic behavior **Lifecycle:** - created during initialization - reused across executions **Thread safety:** - safe for concurrent reads Example formatting Use indentation for examples. Indent section contents using four spaces. Use code blocks for example code. Example Single example: 1 2 3 4 5 6Example: ```python foo = Foo("example") process(foo, multiplier=2) ``` Multiple examples: 1 2 3 4 5 6 7 8 9 10 11 12 13Example: Create foo: ```python foo = Foo("example") ``` Run engine: ```python engine = BarEngine([foo]) engine.run() ``` 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. Separator rules Use horizontal separators only at docstring root level to separate sections: 1--- Allowed locations: package docstrings module docstrings major documentation sections Do not use separators inside code sections. Package docstrings Package docstrings act as the documentation home page. Recommended sections: 1 2 3 4 5 6 7 8 9# Summary # Installation # Quick start # CLI usage # Core concepts # Architecture # Rendering pipeline # Examples # Notes Example Package Doc String: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30''' # Summary Foo-bar processing framework. Provides tools for defining Foo objects and executing Bar pipelines. --- # Installation ```bash pip install foo-bar ``` --- # Quick start ```python from foobar import Foo, BarEngine foo = Foo("example") engine = BarEngine([foo]) result = engine.run() ``` --- ''' Module docstrings Module docstrings describe a subsystem. Recommended sections: 1 2 3# Summary # Examples # Notes Example Module Doc String: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23''' # Summary Foo execution subsystem. Provides utilities for executing Foo objects through Bar stages. --- Example: ```python from foobar.engine import BarEngine from foobar.foo import Foo foo = Foo("example") engine = BarEngine([foo]) engine.run() ``` --- ''' Class docstrings Class docstrings define object responsibility, lifecycle, and attributes. Recommended sections: 1 2 3 4Attributes: Notes: Example: Raises: Example Simple Foo: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29class Foo: ''' Represents a unit of work. Attributes: name (str): Identifier of the foo instance. value (int): Numeric value associated with foo. Notes: Guarantees: - instances are immutable after creation Lifecycle: - create instance - pass to processing engine Example: Create and inspect a Foo: ```python foo = Foo("example", value=42) print(foo.name) ``` ''' Complex Bar: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24class BarEngine: ''' Executes Foo objects through Bar stages. Attributes: foos (tuple[Foo, ...]): Foo instances managed by the engine. Notes: Guarantees: - deterministic execution order Example: Run engine: ```python foo1 = Foo("a") foo2 = Foo("b") engine = BarEngine([foo1, foo2]) engine.run() ``` ''' Function and method docstrings Function docstrings define API contracts. Recommended sections: 1 2 3 4 5 6Args: Returns: Raises: Yields: Notes: Example: Example Simple process method: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34def 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. Notes: Guarantees: - foo is not modified Example: Process foo: ```python foo = Foo("example", value=10) result = process(foo, multiplier=2) print(result) ``` ''' Multiple Examples: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32def combine(foo_a: Foo, foo_b: Foo) -> Foo: ''' Combine two Foo instances. Args: foo_a (Foo): First foo. foo_b (Foo): Second foo. Returns: Foo: Combined foo. Example: Basic usage: ```python foo1 = Foo("a") foo2 = Foo("b") combined = combine(foo1, foo2) ``` Pipeline usage: ```python engine = BarEngine([foo1, foo2]) engine.run() ``` ''' Property docstrings Properties must document return values. Example Property Doc String: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18```python @property def foos(self) -> tuple[Foo, ...]: ''' Return contained Foo instances. Returns: tuple[Foo, ...]: Stored foo objects. Example: ```python container = FooContainer() foos = container.foos ``` ''' ``` Attribute documentation Document attributes in class docstrings using Attributes:. Example Attribute Doc String: 1 2 3 4 5 6 7 8 9 10 11 12```python ''' Represents a processing stage. Attributes: id (str): Unique identifier. enabled (bool): Whether the stage is active. ''' ``` Type parity (.pyi stubs and py.typed) Documented APIs ship matching type information: Each .py module has a synchronized .pyi stub in the same package. Packages expose a py.typed marker so type checkers (and consumers) use the authored signatures instead of Any. When signatures change, update the .py implementation and its .pyi stub together. Doc-forge documents the docstrings in .py; the .pyi stub is the machine-consumable signature surface. Parsing guarantees GSDFC ensures doc-forge can deterministically extract: symbol kind (module, class, function, property, attribute) symbol name parameters return values attributes examples structured Notes subsections This enables: reliable MkDocs rendering deterministic MCP export accurate AI semantic interpretation Notes doc-forge never executes analyzed modules. Documentation is generated entirely through static analysis. Classes GriffeLoader 1GriffeLoader() Load Python modules using Griffe and convert them into doc-forge models. 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: Name Type Description _loader GriffeLoader Internal Griffe loader with dedicated module and line collections. Initialize the Griffe-backed loader. Creates an internal Griffe loader instance with dedicated collections for modules and source lines. Functions load_module 1load_module(path: str) -> Module Load and convert a single Python module. The module is introspected using Griffe and then transformed into a doc-forge Module model. Parameters: Name Type Description Default path str Dotted import path of the module. required Returns: Name Type Description Module Module A populated Module instance. Raises: Type Description 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: 1 2 3 4```python loader = GriffeLoader() module = loader.load_module("mypackage.submodule") ``` load_project 1 2 3 4 5load_project( module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None, ) -> Project Load multiple modules and assemble them into a Project model. Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object. Parameters: Name Type Description Default module_paths list[str] List of dotted module import paths to load. required project_name str | None Optional override for the project name. Defaults to the top-level name of the first module. None skip_import_errors bool | None If True, modules that fail to load will be skipped instead of raising an error. None Returns: Name Type Description Project Project A populated Project instance containing the loaded modules. Raises: Type Description ValueError If no module paths are provided. ImportError If a module fails to load and skip_import_errors is False. MCPRenderer Renderer that generates MCP-compatible documentation resources. This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP). Functions generate_sources 1generate_sources(project: Project, out_dir: Path) -> None Generate MCP documentation resources for a project. The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json. Parameters: Name Type Description Default project Project Documentation project model to render. required out_dir Path Directory where MCP resources will be written. required MkDocsRenderer Renderer that produces Markdown documentation for MkDocs. Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically. Functions generate_readme 1 2 3 4 5 6generate_readme( project: Project, docs_dir: Path, module_is_source: bool | None = None, readme_dir: Path | None = None, ) -> None Generate a README.md file from the root module docstring. Notes If module_is_source is True, README.md is written to the project root directory. If False, README generation is currently not implemented. Parameters: Name Type Description Default project Project Project model containing documentation metadata. required docs_dir Path Directory containing generated documentation sources. required module_is_source bool | None Whether the module is treated as the project source root. None readme_dir Path | None Directory where the generated README.md should be written. Defaults to the parent of docs_dir. None generate_sources 1 2 3 4 5generate_sources( project: Project, out_dir: Path, module_is_source: bool | None = None, ) -> None Generate Markdown documentation files for a project. This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory. Parameters: Name Type Description Default project Project Project model containing modules to document. required out_dir Path Directory where generated Markdown files will be written. required module_is_source bool | None If True, treat the specified module as the documentation root rather than nesting it inside a folder. None Functions discover_module_paths 1 2 3discover_module_paths( module_name: str, project_root: Path | None = None ) -> list[str] Discover Python modules within a package directory. The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths. Discovery rules: Directories containing __init__.py are treated as packages. Each .py file is treated as a module. Results are returned as dotted import paths. Parameters: Name Type Description Default module_name str Top-level package name to discover modules from. required project_root Path | None Root directory used to resolve module paths. If not provided, the current working directory is used. None Returns: Type Description list[str] list[str]: A sorted list of unique dotted module import paths. Raises: Type Description FileNotFoundError If the specified package directory does not exist. stubs and wzxhzdk:1) + + +
  • @@ -2764,6 +2782,18 @@ Attributes: ```
    • +

    Type parity (.pyi stubs and py.typed)

    +

    Documented APIs ship matching type information:

    + +

    Parsing guarantees

    GSDFC ensures doc-forge can deterministically extract:

    "},{"location":"#docforge","title":"docforge","text":""},{"location":"#docforge--summary","title":"Summary","text":"

    Renderer-agnostic Python documentation compiler that converts Python docstrings into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).

    doc-forge statically analyzes source code, builds a semantic model of modules, classes, functions, and attributes, and renders that model into documentation outputs without executing user code.

    "},{"location":"#docforge--installation","title":"Installation","text":"

    Install using pip:

    pip install doc-forge\n
    "},{"location":"#docforge--cli-usage","title":"CLI usage","text":"

    Each site kind (lib, api, wiki) is built independently into site/{kind}.

    "},{"location":"#docforge--build-the-library-reference-from-a-python-package","title":"Build the library reference from a Python package:","text":"
    doc-forge build --mkdocs --module my_package\n
    "},{"location":"#docforge--build-the-api-reference-from-an-openapi-spec","title":"Build the API reference from an OpenAPI spec:","text":"
    doc-forge build --api --openapi-spec spec.json\n
    "},{"location":"#docforge--build-the-hand-written-wiki","title":"Build the hand-written wiki:","text":"
    doc-forge build --wiki --site-name my_package\n
    "},{"location":"#docforge--generate-mcp-json-documentation","title":"Generate MCP JSON documentation:","text":"
    doc-forge build --mcp --module my_package\n
    "},{"location":"#docforge--build-several-kinds-in-one-pass","title":"Build several kinds in one pass:","text":"
    doc-forge build --mcp --mkdocs --wiki --module my_package\n

    Each enabled kind gets its own MkDocs config (docs/mkdocs.{lib,api,wiki}.yml) and its own site under site/.

    "},{"location":"#docforge--serve-a-site-locally","title":"Serve a site locally:","text":"
    doc-forge serve --wiki        # preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n
    "},{"location":"#docforge--serve-mcp-locally","title":"Serve MCP locally:","text":"
    doc-forge serve --mcp --module my_package\n
    "},{"location":"#docforge--core-concepts","title":"Core concepts","text":""},{"location":"#docforge--loader","title":"Loader","text":"

    Extracts symbols, signatures, and docstrings using static analysis.

    "},{"location":"#docforge--semantic-model","title":"Semantic model","text":"

    Structured, renderer-agnostic representation of the API.

    "},{"location":"#docforge--renderer","title":"Renderer","text":"

    Converts the semantic model into output formats such as MkDocs or MCP JSON.

    "},{"location":"#docforge--symbol","title":"Symbol","text":"

    Any documentable object

    "},{"location":"#docforge--architecture","title":"Architecture","text":"

    doc-forge follows a compiler architecture:

    "},{"location":"#docforge--front-end","title":"Front-end:","text":"

    Static analysis of modules, classes, functions, type hints, and docstrings.

    "},{"location":"#docforge--middle-end","title":"Middle-end:","text":"

    Builds a semantic model describing symbols and relationships.

    "},{"location":"#docforge--back-end","title":"Back-end:","text":"

    Renders documentation using interchangeable renderers.

    This architecture ensures deterministic documentation generation.

    "},{"location":"#docforge--rendering-pipeline","title":"Rendering pipeline","text":"

    Typical flow:

    Python package\n    |\nLoader (static analysis)\n    |\nSemantic model\n    |\nRenderer\n    |\nMkDocs site or MCP JSON\n
    "},{"location":"#docforge--google-styled-doc-forge-convention-gsdfc","title":"Google-Styled Doc-Forge Convention (GSDFC)","text":"

    GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.

    "},{"location":"#docforge--general-rules","title":"General rules","text":""},{"location":"#docforge--notes-subsection-grouping","title":"Notes subsection grouping","text":"

    Group related information using labeled subsections.

    Example:

    Notes:\n    **Guarantees:**\n\n        - deterministic behavior\n\n    **Lifecycle:**\n\n        - created during initialization\n        - reused across executions\n\n    **Thread safety:**\n\n        - safe for concurrent reads\n
    "},{"location":"#docforge--example-formatting","title":"Example formatting","text":" Example

    Single example:

    Example:\n\n    ```python\n    foo = Foo(\"example\")\n    process(foo, multiplier=2)\n    ```\n

    Multiple examples:

    Example:\n    Create foo:\n\n        ```python\n        foo = Foo(\"example\")\n        ```\n\n    Run engine:\n\n        ```python\n        engine = BarEngine([foo])\n        engine.run()\n        ```\n

    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.

    "},{"location":"#docforge--separator-rules","title":"Separator rules","text":"

    Use horizontal separators only at docstring root level to separate sections:

    ---\n

    Allowed locations:

    Do not use separators inside code sections.

    "},{"location":"#docforge--package-docstrings","title":"Package docstrings","text":"

    Package docstrings act as the documentation home page.

    Recommended sections:

    # Summary\n# Installation\n# Quick start\n# CLI usage\n# Core concepts\n# Architecture\n# Rendering pipeline\n# Examples\n# Notes\n
    Example

    Package Doc String:

    '''\n# Summary\n\nFoo-bar processing framework.\n\nProvides tools for defining Foo objects and executing Bar pipelines.\n\n---\n\n# Installation\n\n```bash\npip install foo-bar\n```\n\n---\n\n# Quick start\n\n```python\nfrom foobar import Foo, BarEngine\n\nfoo = Foo(\"example\")\nengine = BarEngine([foo])\n\nresult = engine.run()\n```\n\n---\n'''\n
    "},{"location":"#docforge--module-docstrings","title":"Module docstrings","text":"

    Module docstrings describe a subsystem.

    Recommended sections:

    # Summary\n# Examples\n# Notes\n
    Example

    Module Doc String:

    '''\n# Summary\n\nFoo execution subsystem.\n\nProvides utilities for executing Foo objects through Bar stages.\n\n---\n\nExample:\n\n    ```python\n    from foobar.engine import BarEngine\n    from foobar.foo import Foo\n\n    foo = Foo(\"example\")\n\n    engine = BarEngine([foo])\n    engine.run()\n    ```\n\n---\n'''\n
    "},{"location":"#docforge--class-docstrings","title":"Class docstrings","text":"

    Class docstrings define object responsibility, lifecycle, and attributes.

    Recommended sections:

    Attributes:\nNotes:\nExample:\nRaises:\n
    Example

    Simple Foo:

    class Foo:\n    '''\n    Represents a unit of work.\n\n    Attributes:\n        name (str):\n            Identifier of the foo instance.\n\n        value (int):\n            Numeric value associated with foo.\n\n    Notes:\n        Guarantees:\n\n            - instances are immutable after creation\n\n        Lifecycle:\n\n            - create instance\n            - pass to processing engine\n\n    Example:\n        Create and inspect a Foo:\n\n            ```python\n            foo = Foo(\"example\", value=42)\n            print(foo.name)\n            ```\n    '''\n

    Complex Bar:

    class BarEngine:\n    '''\n    Executes Foo objects through Bar stages.\n\n    Attributes:\n        foos (tuple[Foo, ...]):\n            Foo instances managed by the engine.\n\n    Notes:\n        Guarantees:\n\n            - deterministic execution order\n\n    Example:\n        Run engine:\n\n            ```python\n            foo1 = Foo(\"a\")\n            foo2 = Foo(\"b\")\n\n            engine = BarEngine([foo1, foo2])\n            engine.run()\n            ```\n    '''\n
    "},{"location":"#docforge--function-and-method-docstrings","title":"Function and method docstrings","text":"

    Function docstrings define API contracts.

    Recommended sections:

    Args:\nReturns:\nRaises:\nYields:\nNotes:\nExample:\n
    Example

    Simple process method:

    def process(foo: Foo, multiplier: int) -> int:\n    '''\n    Process a Foo instance.\n\n    Args:\n        foo (Foo):\n            Foo instance to process.\n\n        multiplier (int):\n            Value used to scale foo.\n\n    Returns:\n        int:\n            Processed result.\n\n    Raises:\n        ValueError:\n            If multiplier is negative.\n\n    Notes:\n        Guarantees:\n\n            - foo is not modified\n\n    Example:\n        Process foo:\n\n            ```python\n            foo = Foo(\"example\", value=10)\n\n            result = process(foo, multiplier=2)\n            print(result)\n            ```\n    '''\n

    Multiple Examples:

    def combine(foo_a: Foo, foo_b: Foo) -> Foo:\n    '''\n    Combine two Foo instances.\n\n    Args:\n        foo_a (Foo):\n            First foo.\n\n        foo_b (Foo):\n            Second foo.\n\n    Returns:\n        Foo:\n            Combined foo.\n\n    Example:\n        Basic usage:\n\n            ```python\n            foo1 = Foo(\"a\")\n            foo2 = Foo(\"b\")\n\n            combined = combine(foo1, foo2)\n            ```\n\n        Pipeline usage:\n\n            ```python\n            engine = BarEngine([foo1, foo2])\n            engine.run()\n            ```\n    '''\n
    "},{"location":"#docforge--property-docstrings","title":"Property docstrings","text":"

    Properties must document return values.

    Example

    Property Doc String:

    ```python\n@property\ndef foos(self) -> tuple[Foo, ...]:\n    '''\n    Return contained Foo instances.\n\n    Returns:\n        tuple[Foo, ...]:\n            Stored foo objects.\n\n    Example:\n        ```python\n        container = FooContainer()\n\n        foos = container.foos\n        ```\n    '''\n```\n
    "},{"location":"#docforge--attribute-documentation","title":"Attribute documentation","text":"

    Document attributes in class docstrings using Attributes:.

    Example

    Attribute Doc String:

    ```python\n'''\nRepresents a processing stage.\n\nAttributes:\n    id (str):\n        Unique identifier.\n\n    enabled (bool):\n        Whether the stage is active.\n'''\n```\n
    "},{"location":"#docforge--parsing-guarantees","title":"Parsing guarantees","text":"

    GSDFC ensures doc-forge can deterministically extract:

    This enables:

    Notes "},{"location":"#docforge-classes","title":"Classes","text":""},{"location":"#docforge.GriffeLoader","title":"GriffeLoader","text":"
    GriffeLoader()\n

    Load Python modules using Griffe and convert them into doc-forge models.

    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:

    Name Type Description _loader GriffeLoader

    Internal Griffe loader with dedicated module and line collections.

    Initialize the Griffe-backed loader.

    Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

    "},{"location":"#docforge.GriffeLoader-functions","title":"Functions","text":""},{"location":"#docforge.GriffeLoader.load_module","title":"load_module","text":"
    load_module(path: str) -> Module\n

    Load and convert a single Python module.

    The module is introspected using Griffe and then transformed into a doc-forge Module model.

    Parameters:

    Name Type Description Default path str

    Dotted import path of the module.

    required

    Returns:

    Name Type Description Module Module

    A populated Module instance.

    Raises:

    Type Description 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\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
    "},{"location":"#docforge.GriffeLoader.load_project","title":"load_project","text":"
    load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

    Load multiple modules and assemble them into a Project model.

    Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

    Parameters:

    Name Type Description Default module_paths list[str]

    List of dotted module import paths to load.

    required project_name str | None

    Optional override for the project name. Defaults to the top-level name of the first module.

    None skip_import_errors bool | None

    If True, modules that fail to load will be skipped instead of raising an error.

    None

    Returns:

    Name Type Description Project Project

    A populated Project instance containing the loaded modules.

    Raises:

    Type Description ValueError

    If no module paths are provided.

    ImportError

    If a module fails to load and skip_import_errors is False.

    "},{"location":"#docforge.MCPRenderer","title":"MCPRenderer","text":"

    Renderer that generates MCP-compatible documentation resources.

    This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

    "},{"location":"#docforge.MCPRenderer-functions","title":"Functions","text":""},{"location":"#docforge.MCPRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(project: Project, out_dir: Path) -> None\n

    Generate MCP documentation resources for a project.

    The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

    Parameters:

    Name Type Description Default project Project

    Documentation project model to render.

    required out_dir Path

    Directory where MCP resources will be written.

    required"},{"location":"#docforge.MkDocsRenderer","title":"MkDocsRenderer","text":"

    Renderer that produces Markdown documentation for MkDocs.

    Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

    "},{"location":"#docforge.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"#docforge.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
    generate_readme(\n    project: Project,\n    docs_dir: Path,\n    module_is_source: bool | None = None,\n    readme_dir: Path | None = None,\n) -> None\n

    Generate a README.md file from the root module docstring.

    Notes

    Parameters:

    Name Type Description Default project Project

    Project model containing documentation metadata.

    required docs_dir Path

    Directory containing generated documentation sources.

    required module_is_source bool | None

    Whether the module is treated as the project source root.

    None readme_dir Path | None

    Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

    None"},{"location":"#docforge.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

    Generate Markdown documentation files for a project.

    This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

    Parameters:

    Name Type Description Default project Project

    Project model containing modules to document.

    required out_dir Path

    Directory where generated Markdown files will be written.

    required module_is_source bool | None

    If True, treat the specified module as the documentation root rather than nesting it inside a folder.

    None"},{"location":"#docforge-functions","title":"Functions","text":""},{"location":"#docforge.discover_module_paths","title":"discover_module_paths","text":"
    discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

    Discover Python modules within a package directory.

    The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

    Discovery rules:

    Parameters:

    Name Type Description Default module_name str

    Top-level package name to discover modules from.

    required project_root Path | None

    Root directory used to resolve module paths. If not provided, the current working directory is used.

    None

    Returns:

    Type Description list[str]

    list[str]: A sorted list of unique dotted module import paths.

    Raises:

    Type Description FileNotFoundError

    If the specified package directory does not exist.

    "},{"location":"cli/","title":"Cli","text":""},{"location":"cli/#docforge.cli","title":"docforge.cli","text":""},{"location":"cli/#docforge.cli--summary","title":"Summary","text":"

    Command line interface entry point for doc-forge.

    This module exposes the primary CLI entry function used by the doc-forge command. The actual command implementation resides in docforge.cli.main, while this module provides a stable import path for external tools and the package entry point configuration.

    The CLI is responsible for orchestrating documentation workflows such as generating renderer sources, building documentation sites, exporting machine-readable documentation bundles, and starting development or MCP servers.

    "},{"location":"cli/#docforge.cli--typical-usage","title":"Typical usage","text":"

    The CLI is normally invoked through the installed command:

    doc-forge <command> [options]\n

    Programmatic invocation is also possible:

    Example:

    ```python\nfrom docforge.cli import main\nmain()\n```\n
    "},{"location":"cli/api_utils/","title":"Api Utils","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils","title":"docforge.cli.api_utils","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils--summary","title":"Summary","text":"

    Utilities for building API documentation from an OpenAPI specification.

    "},{"location":"cli/api_utils/#docforge.cli.api_utils-classes","title":"Classes","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils.OpenAPIMetadata","title":"OpenAPIMetadata dataclass","text":"
    OpenAPIMetadata(\n    site_name: str,\n    site_description: str | None,\n    site_author: str | None,\n)\n

    Metadata derived from the info block of an OpenAPI specification.

    Attributes:

    Name Type Description site_name str

    Spec title, used as the MkDocs site name.

    site_description str | None

    Spec description, used as the site description.

    site_author str | None

    Contact name (fallback: contact email), used as the site author.

    "},{"location":"cli/api_utils/#docforge.cli.api_utils-functions","title":"Functions","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils.derive_metadata","title":"derive_metadata","text":"
    derive_metadata(spec: dict[Any, Any]) -> OpenAPIMetadata\n

    Derive MkDocs site metadata from an OpenAPI spec info block.

    Parameters:

    Name Type Description Default spec dict

    Parsed OpenAPI specification.

    required

    Returns:

    Name Type Description OpenAPIMetadata OpenAPIMetadata

    Site name, description, and author derived from the spec.

    "},{"location":"cli/api_utils/#docforge.cli.api_utils.generate_api_sources","title":"generate_api_sources","text":"
    generate_api_sources(\n    spec: dict[Any, Any], docs_dir: Path\n) -> None\n

    Generate swagger-enabled Markdown sources and the spec copy.

    The specification is written as openapi.json inside docs_dir and an index.md embedding the swagger UI is generated alongside it.

    Parameters:

    Name Type Description Default spec dict

    Parsed OpenAPI specification.

    required docs_dir Path

    Directory (for example docs/api) where the swagger sources are written.

    required"},{"location":"cli/api_utils/#docforge.cli.api_utils.load_openapi_spec","title":"load_openapi_spec","text":"
    load_openapi_spec(spec_path: Path) -> dict[Any, Any]\n

    Load and validate an OpenAPI specification from a JSON file.

    Parameters:

    Name Type Description Default spec_path Path

    Path to the OpenAPI JSON specification file.

    required

    Returns:

    Name Type Description dict dict[Any, Any]

    The parsed OpenAPI specification.

    Raises:

    Type Description ClickException

    If the file cannot be read or the info block is invalid.

    "},{"location":"cli/commands/","title":"Commands","text":""},{"location":"cli/commands/#docforge.cli.commands","title":"docforge.cli.commands","text":""},{"location":"cli/commands/#docforge.cli.commands--summary","title":"Summary","text":"

    Command definitions for the doc-forge CLI.

    Provides the CLI structure using Click, including build, serve, and tree commands.

    Notes "},{"location":"cli/commands/#docforge.cli.commands-classes","title":"Classes","text":""},{"location":"cli/commands/#docforge.cli.commands-functions","title":"Functions","text":""},{"location":"cli/commands/#docforge.cli.commands.build","title":"build","text":"
    build(\n    mcp: bool,\n    mkdocs: bool,\n    api: bool,\n    wiki: bool,\n    refresh: bool,\n    module_is_source: bool,\n    module: str | None,\n    openapi_spec: Path | None,\n    project_name: str | None,\n    site_name: str | None,\n    docs_dir: Path,\n    wiki_dir: Path,\n    nav_file: Path,\n    template: Path | None,\n    out_dir: Path,\n) -> None\n

    Build documentation artifacts.

    This command runs the full documentation pipeline: it loads Python modules, generates renderer-specific documentation sources, and optionally builds the final output.

    Depending on the selected options, the build can target:

    Each enabled site kind produces its own MkDocs configuration (docs/mkdocs.{kind}.yml) and its own build (site/{kind}).

    Notes

    Parameters:

    Name Type Description Default mcp bool

    Enable MCP documentation generation.

    required mkdocs bool

    Enable the lib MkDocs documentation generation.

    required api bool

    Enable API documentation generation from an OpenAPI spec.

    required wiki bool

    Build a hand-written wiki directory as its own MkDocs site.

    required refresh bool

    Regenerate docs/mkdocs.{kind}.yml from templates even when it already exists. By default, existing configs are used as-is.

    required module_is_source bool

    Treat the specified module directory as the project root.

    required module str | None

    Python module import path to document.

    required openapi_spec Path | None

    Path to the OpenAPI JSON specification used for API docs.

    required project_name str | None

    Optional override for the project name.

    required site_name str | None

    Display name for the lib and wiki MkDocs sites.

    required docs_dir Path

    Shared documentation root used for generated sources.

    required wiki_dir Path

    Directory containing hand-written wiki markdown files.

    required nav_file Path

    Path to the navigation specification file.

    required template Path | None

    Optional custom MkDocs configuration template.

    required out_dir Path

    Output directory for generated MCP resources.

    required

    Raises:

    Type Description UsageError

    If required options are missing or conflicting.

    "},{"location":"cli/commands/#docforge.cli.commands.serve","title":"serve","text":"
    serve(\n    mcp: bool,\n    mkdocs: bool,\n    lib: bool,\n    api: bool,\n    wiki: bool,\n    module: str | None,\n    mkdocs_yml: Path,\n    out_dir: Path,\n) -> None\n

    Serve generated documentation locally.

    Depending on the selected mode, this command starts either:

    The kind flags (--lib, --api, --wiki) select the generated per-kind config (docs/mkdocs.{kind}.yml); --mkdocs serves the config passed via --mkdocs-yml.

    Parameters:

    Name Type Description Default mcp bool

    Serve documentation using the MCP server.

    required mkdocs bool

    Serve the MkDocs development site from --mkdocs-yml.

    required lib bool

    Serve the lib MkDocs site.

    required api bool

    Serve the API MkDocs site.

    required wiki bool

    Serve the wiki MkDocs site.

    required module str | None

    Python module import path to serve via MCP.

    required mkdocs_yml Path

    Path to the MkDocs configuration file.

    required out_dir Path

    Root directory containing MCP documentation resources.

    required

    Raises:

    Type Description UsageError

    If invalid or conflicting options are provided.

    "},{"location":"cli/commands/#docforge.cli.commands.tree","title":"tree","text":"
    tree(module: str, project_name: str | None) -> None\n

    Display the documentation object tree for a module.

    This command introspects the specified module and prints a hierarchical representation of the discovered documentation objects, including modules, classes, functions, and members.

    Parameters:

    Name Type Description Default module str

    Python module import path to introspect.

    required project_name str | None

    Optional name to display as the project root.

    required"},{"location":"cli/main/","title":"Main","text":""},{"location":"cli/main/#docforge.cli.main","title":"docforge.cli.main","text":""},{"location":"cli/main/#docforge.cli.main--summary","title":"Summary","text":"

    Command-line entry point for the doc-forge CLI.

    This module exposes the executable entry point that initializes the Click command group defined in docforge.cli.commands.

    "},{"location":"cli/main/#docforge.cli.main-functions","title":"Functions","text":""},{"location":"cli/main/#docforge.cli.main.main","title":"main","text":"
    main() -> None\n

    Run the doc-forge command-line interface.

    This function initializes and executes the Click CLI application. It is used as the console entry point when invoking doc-forge from the command line.

    "},{"location":"cli/mcp_utils/","title":"Mcp Utils","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils","title":"docforge.cli.mcp_utils","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils--summary","title":"Summary","text":"

    Utilities for working with MCP in the doc-forge CLI.

    Notes "},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils-classes","title":"Classes","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils-functions","title":"Functions","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils.generate_resources","title":"generate_resources","text":"
    generate_resources(\n    module: str, project_name: str | None, out_dir: Path\n) -> None\n

    Generate MCP documentation resources from a Python module.

    The function performs project introspection, builds the internal documentation model, and renders MCP-compatible JSON resources to the specified output directory.

    Parameters:

    Name Type Description Default module str

    Python module import path used as the entry point for documentation generation.

    required project_name str | None

    Optional override for the project name used in generated documentation metadata.

    required out_dir Path

    Directory where MCP resources (index.json, nav.json, and module data) will be written.

    required"},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils.serve","title":"serve","text":"
    serve(module: str, mcp_root: Path) -> None\n

    Start an MCP server for a pre-generated documentation bundle.

    The server exposes documentation resources such as project metadata, navigation structure, and module documentation through MCP endpoints.

    Parameters:

    Name Type Description Default module str

    Python module import path used to identify the served documentation instance.

    required mcp_root Path

    Path to the directory containing the MCP documentation bundle (index.json, nav.json, and modules/).

    required

    Raises:

    Type Description ClickException

    If the MCP documentation bundle is missing required files or directories.

    "},{"location":"cli/mkdocs_utils/","title":"Mkdocs Utils","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils","title":"docforge.cli.mkdocs_utils","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils--summary","title":"Summary","text":"

    Utilities for working with MkDocs in the doc-forge CLI.

    Notes "},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils-classes","title":"Classes","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils-functions","title":"Functions","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_configs","title":"build_configs","text":"
    build_configs(yml_paths: Iterable[Path]) -> None\n

    Build the MkDocs documentation site for every given configuration.

    Each configuration file is loaded and built in turn, producing the per-kind static sites (site/lib, site/api, site/wiki).

    Parameters:

    Name Type Description Default yml_paths Iterable[Path]

    Configuration files to build, in order.

    required

    Raises:

    Type Description ClickException

    If a configuration file does not exist.

    "},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_lib_nav","title":"build_lib_nav","text":"
    build_lib_nav(\n    nav_file: Path, docs_root: Path\n) -> tuple[list[dict[str, Any]], dict[str, str] | None]\n

    Build the re-rooted navigation block for a lib site.

    The navigation specification is resolved against the shared documentation root and every resulting path is re-rooted relative to the lib subdirectory by stripping its leading lib/ scope component.

    Parameters:

    Name Type Description Default nav_file Path

    Path to the docforge.nav.yml navigation specification.

    required docs_root Path

    Shared documentation root containing the lib sources.

    required

    Returns:

    Type Description tuple[list[dict[str, Any]], dict[str, str] | None]

    tuple[list[dict[str, Any]], dict[str, str] | None]: The re-rooted navigation block and the optional theme icon mapping from the specification.

    Raises:

    Type Description FileError

    If the navigation specification cannot be found.

    "},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_wiki_nav_block","title":"build_wiki_nav_block","text":"
    build_wiki_nav_block(\n    wiki_dir: Path,\n) -> list[dict[str, Any]]\n

    Build the re-rooted navigation block for a wiki site.

    The wiki navigation derived from the wiki file structure is re-rooted relative to the wiki directory itself by stripping the leading wiki/ scope component.

    Parameters:

    Name Type Description Default wiki_dir Path

    Path to the hand-written wiki directory, for example docs/wiki.

    required

    Returns:

    Type Description list[dict[str, Any]]

    list[dict[str, Any]]: Navigation entries relative to the wiki directory.

    Raises:

    Type Description FileError

    If the wiki directory does not exist.

    "},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_site_config","title":"generate_site_config","text":"
    generate_site_config(\n    kind: str,\n    kind_root: Path,\n    nav_block: list[dict[str, Any]],\n    out: Path,\n    site_name: str,\n    docs_dir: str,\n    site_dir: str,\n    template: Path | None = None,\n    site_description: str | None = None,\n    site_author: str | None = None,\n    theme_icon: dict[str, str] | None = None,\n) -> None\n

    Generate a per-kind mkdocs.{kind}.yml configuration file.

    The configuration is created by merging the shared mkdocs.common.yml template with the fragment contributed by the kind (lib, api, or wiki). Both docs_dir and site_dir are written relative to the configuration file's directory: the kind's sources when expressed as a sibling path (for example lib) and the per-kind site output (for example ../site/lib).

    Parameters:

    Name Type Description Default kind str

    Documentation kind, one of lib, api, or wiki.

    required kind_root Path

    Directory scoped to the kind (for example docs/lib) that serves as the MkDocs docs_dir.

    required nav_block list[dict[str, Any]]

    Re-rooted navigation entries for the kind's site.

    required out Path

    Destination path where the generated mkdocs.{kind}.yml file is written.

    required site_name str

    Display name for the generated documentation site.

    required docs_dir str

    MkDocs docs_dir value, relative to the configuration file's directory.

    required site_dir str

    MkDocs site_dir value, relative to the configuration file's directory.

    required template Path | None

    Optional path to a fully custom MkDocs configuration template that replaces the built-in templates entirely.

    None site_description str | None

    Optional site description written into the configuration.

    None site_author str | None

    Optional site author written into the configuration.

    None theme_icon dict[str, str] | None

    Optional mapping of theme icon entries injected as theme.icon.

    None"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_sources","title":"generate_sources","text":"
    generate_sources(\n    module: str,\n    docs_dir: Path,\n    project_name: str | None = None,\n    module_is_source: bool | None = None,\n    readme_dir: Path | None = None,\n) -> None\n

    Generate MkDocs Markdown sources for a Python module.

    This function introspects the specified module, builds the internal documentation model, and renders Markdown documentation files for use with MkDocs.

    Parameters:

    Name Type Description Default module str

    Python module import path used as the entry point for documentation generation.

    required docs_dir Path

    Directory where the generated Markdown files will be written.

    required project_name str | None

    Optional override for the project name used in documentation metadata.

    None module_is_source bool | None

    If True, treat the specified module directory as the project root rather than a nested module.

    None readme_dir Path | None

    Directory where the generated README.md should be written. If not provided, defaults to the parent of docs_dir.

    None"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.load_spec_icon","title":"load_spec_icon","text":"
    load_spec_icon(nav_file: Path) -> dict[str, str] | None\n

    Load the theme icon mapping from a navigation specification.

    Parameters:

    Name Type Description Default nav_file Path

    Path to the navigation specification file.

    required

    Returns:

    Type Description dict[str, str] | None

    dict[str, str] | None: The icon mapping, or None when the specification file is absent or cannot be parsed.

    "},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.serve","title":"serve","text":"
    serve(mkdocs_yml: Path) -> None\n

    Start an MkDocs development server with live reload.

    The server watches documentation files and automatically reloads the site when changes are detected.

    Parameters:

    Name Type Description Default mkdocs_yml Path

    Path to the mkdocs.yml configuration file.

    required

    Raises:

    Type Description ClickException

    If the configuration file does not exist.

    "},{"location":"docforge/","title":"Docforge","text":""},{"location":"docforge/#docforge","title":"docforge","text":""},{"location":"docforge/#docforge--summary","title":"Summary","text":"

    Renderer-agnostic Python documentation compiler that converts Python docstrings into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).

    doc-forge statically analyzes source code, builds a semantic model of modules, classes, functions, and attributes, and renders that model into documentation outputs without executing user code.

    "},{"location":"docforge/#docforge--installation","title":"Installation","text":"

    Install using pip:

    pip install doc-forge\n
    "},{"location":"docforge/#docforge--cli-usage","title":"CLI usage","text":"

    Each site kind (lib, api, wiki) is built independently into site/{kind}.

    "},{"location":"docforge/#docforge--build-the-library-reference-from-a-python-package","title":"Build the library reference from a Python package:","text":"
    doc-forge build --mkdocs --module my_package\n
    "},{"location":"docforge/#docforge--build-the-api-reference-from-an-openapi-spec","title":"Build the API reference from an OpenAPI spec:","text":"
    doc-forge build --api --openapi-spec spec.json\n
    "},{"location":"docforge/#docforge--build-the-hand-written-wiki","title":"Build the hand-written wiki:","text":"
    doc-forge build --wiki --site-name my_package\n
    "},{"location":"docforge/#docforge--generate-mcp-json-documentation","title":"Generate MCP JSON documentation:","text":"
    doc-forge build --mcp --module my_package\n
    "},{"location":"docforge/#docforge--build-several-kinds-in-one-pass","title":"Build several kinds in one pass:","text":"
    doc-forge build --mcp --mkdocs --wiki --module my_package\n

    Each enabled kind gets its own MkDocs config (docs/mkdocs.{lib,api,wiki}.yml) and its own site under site/.

    "},{"location":"docforge/#docforge--serve-a-site-locally","title":"Serve a site locally:","text":"
    doc-forge serve --wiki        # preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n
    "},{"location":"docforge/#docforge--serve-mcp-locally","title":"Serve MCP locally:","text":"
    doc-forge serve --mcp --module my_package\n
    "},{"location":"docforge/#docforge--core-concepts","title":"Core concepts","text":""},{"location":"docforge/#docforge--loader","title":"Loader","text":"

    Extracts symbols, signatures, and docstrings using static analysis.

    "},{"location":"docforge/#docforge--semantic-model","title":"Semantic model","text":"

    Structured, renderer-agnostic representation of the API.

    "},{"location":"docforge/#docforge--renderer","title":"Renderer","text":"

    Converts the semantic model into output formats such as MkDocs or MCP JSON.

    "},{"location":"docforge/#docforge--symbol","title":"Symbol","text":"

    Any documentable object

    "},{"location":"docforge/#docforge--architecture","title":"Architecture","text":"

    doc-forge follows a compiler architecture:

    "},{"location":"docforge/#docforge--front-end","title":"Front-end:","text":"

    Static analysis of modules, classes, functions, type hints, and docstrings.

    "},{"location":"docforge/#docforge--middle-end","title":"Middle-end:","text":"

    Builds a semantic model describing symbols and relationships.

    "},{"location":"docforge/#docforge--back-end","title":"Back-end:","text":"

    Renders documentation using interchangeable renderers.

    This architecture ensures deterministic documentation generation.

    "},{"location":"docforge/#docforge--rendering-pipeline","title":"Rendering pipeline","text":"

    Typical flow:

    Python package\n    |\nLoader (static analysis)\n    |\nSemantic model\n    |\nRenderer\n    |\nMkDocs site or MCP JSON\n
    "},{"location":"docforge/#docforge--google-styled-doc-forge-convention-gsdfc","title":"Google-Styled Doc-Forge Convention (GSDFC)","text":"

    GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.

    "},{"location":"docforge/#docforge--general-rules","title":"General rules","text":""},{"location":"docforge/#docforge--notes-subsection-grouping","title":"Notes subsection grouping","text":"

    Group related information using labeled subsections.

    Example:

    Notes:\n    **Guarantees:**\n\n        - deterministic behavior\n\n    **Lifecycle:**\n\n        - created during initialization\n        - reused across executions\n\n    **Thread safety:**\n\n        - safe for concurrent reads\n
    "},{"location":"docforge/#docforge--example-formatting","title":"Example formatting","text":" Example

    Single example:

    Example:\n\n    ```python\n    foo = Foo(\"example\")\n    process(foo, multiplier=2)\n    ```\n

    Multiple examples:

    Example:\n    Create foo:\n\n        ```python\n        foo = Foo(\"example\")\n        ```\n\n    Run engine:\n\n        ```python\n        engine = BarEngine([foo])\n        engine.run()\n        ```\n

    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.

    "},{"location":"docforge/#docforge--separator-rules","title":"Separator rules","text":"

    Use horizontal separators only at docstring root level to separate sections:

    ---\n

    Allowed locations:

    Do not use separators inside code sections.

    "},{"location":"docforge/#docforge--package-docstrings","title":"Package docstrings","text":"

    Package docstrings act as the documentation home page.

    Recommended sections:

    # Summary\n# Installation\n# Quick start\n# CLI usage\n# Core concepts\n# Architecture\n# Rendering pipeline\n# Examples\n# Notes\n
    Example

    Package Doc String:

    '''\n# Summary\n\nFoo-bar processing framework.\n\nProvides tools for defining Foo objects and executing Bar pipelines.\n\n---\n\n# Installation\n\n```bash\npip install foo-bar\n```\n\n---\n\n# Quick start\n\n```python\nfrom foobar import Foo, BarEngine\n\nfoo = Foo(\"example\")\nengine = BarEngine([foo])\n\nresult = engine.run()\n```\n\n---\n'''\n
    "},{"location":"docforge/#docforge--module-docstrings","title":"Module docstrings","text":"

    Module docstrings describe a subsystem.

    Recommended sections:

    # Summary\n# Examples\n# Notes\n
    Example

    Module Doc String:

    '''\n# Summary\n\nFoo execution subsystem.\n\nProvides utilities for executing Foo objects through Bar stages.\n\n---\n\nExample:\n\n    ```python\n    from foobar.engine import BarEngine\n    from foobar.foo import Foo\n\n    foo = Foo(\"example\")\n\n    engine = BarEngine([foo])\n    engine.run()\n    ```\n\n---\n'''\n
    "},{"location":"docforge/#docforge--class-docstrings","title":"Class docstrings","text":"

    Class docstrings define object responsibility, lifecycle, and attributes.

    Recommended sections:

    Attributes:\nNotes:\nExample:\nRaises:\n
    Example

    Simple Foo:

    class Foo:\n    '''\n    Represents a unit of work.\n\n    Attributes:\n        name (str):\n            Identifier of the foo instance.\n\n        value (int):\n            Numeric value associated with foo.\n\n    Notes:\n        Guarantees:\n\n            - instances are immutable after creation\n\n        Lifecycle:\n\n            - create instance\n            - pass to processing engine\n\n    Example:\n        Create and inspect a Foo:\n\n            ```python\n            foo = Foo(\"example\", value=42)\n            print(foo.name)\n            ```\n    '''\n

    Complex Bar:

    class BarEngine:\n    '''\n    Executes Foo objects through Bar stages.\n\n    Attributes:\n        foos (tuple[Foo, ...]):\n            Foo instances managed by the engine.\n\n    Notes:\n        Guarantees:\n\n            - deterministic execution order\n\n    Example:\n        Run engine:\n\n            ```python\n            foo1 = Foo(\"a\")\n            foo2 = Foo(\"b\")\n\n            engine = BarEngine([foo1, foo2])\n            engine.run()\n            ```\n    '''\n
    "},{"location":"docforge/#docforge--function-and-method-docstrings","title":"Function and method docstrings","text":"

    Function docstrings define API contracts.

    Recommended sections:

    Args:\nReturns:\nRaises:\nYields:\nNotes:\nExample:\n
    Example

    Simple process method:

    def process(foo: Foo, multiplier: int) -> int:\n    '''\n    Process a Foo instance.\n\n    Args:\n        foo (Foo):\n            Foo instance to process.\n\n        multiplier (int):\n            Value used to scale foo.\n\n    Returns:\n        int:\n            Processed result.\n\n    Raises:\n        ValueError:\n            If multiplier is negative.\n\n    Notes:\n        Guarantees:\n\n            - foo is not modified\n\n    Example:\n        Process foo:\n\n            ```python\n            foo = Foo(\"example\", value=10)\n\n            result = process(foo, multiplier=2)\n            print(result)\n            ```\n    '''\n

    Multiple Examples:

    def combine(foo_a: Foo, foo_b: Foo) -> Foo:\n    '''\n    Combine two Foo instances.\n\n    Args:\n        foo_a (Foo):\n            First foo.\n\n        foo_b (Foo):\n            Second foo.\n\n    Returns:\n        Foo:\n            Combined foo.\n\n    Example:\n        Basic usage:\n\n            ```python\n            foo1 = Foo(\"a\")\n            foo2 = Foo(\"b\")\n\n            combined = combine(foo1, foo2)\n            ```\n\n        Pipeline usage:\n\n            ```python\n            engine = BarEngine([foo1, foo2])\n            engine.run()\n            ```\n    '''\n
    "},{"location":"docforge/#docforge--property-docstrings","title":"Property docstrings","text":"

    Properties must document return values.

    Example

    Property Doc String:

    ```python\n@property\ndef foos(self) -> tuple[Foo, ...]:\n    '''\n    Return contained Foo instances.\n\n    Returns:\n        tuple[Foo, ...]:\n            Stored foo objects.\n\n    Example:\n        ```python\n        container = FooContainer()\n\n        foos = container.foos\n        ```\n    '''\n```\n
    "},{"location":"docforge/#docforge--attribute-documentation","title":"Attribute documentation","text":"

    Document attributes in class docstrings using Attributes:.

    Example

    Attribute Doc String:

    ```python\n'''\nRepresents a processing stage.\n\nAttributes:\n    id (str):\n        Unique identifier.\n\n    enabled (bool):\n        Whether the stage is active.\n'''\n```\n
    "},{"location":"docforge/#docforge--parsing-guarantees","title":"Parsing guarantees","text":"

    GSDFC ensures doc-forge can deterministically extract:

    This enables:

    Notes "},{"location":"docforge/#docforge-classes","title":"Classes","text":""},{"location":"docforge/#docforge.GriffeLoader","title":"GriffeLoader","text":"
    GriffeLoader()\n

    Load Python modules using Griffe and convert them into doc-forge models.

    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:

    Name Type Description _loader GriffeLoader

    Internal Griffe loader with dedicated module and line collections.

    Initialize the Griffe-backed loader.

    Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

    "},{"location":"docforge/#docforge.GriffeLoader-functions","title":"Functions","text":""},{"location":"docforge/#docforge.GriffeLoader.load_module","title":"load_module","text":"
    load_module(path: str) -> Module\n

    Load and convert a single Python module.

    The module is introspected using Griffe and then transformed into a doc-forge Module model.

    Parameters:

    Name Type Description Default path str

    Dotted import path of the module.

    required

    Returns:

    Name Type Description Module Module

    A populated Module instance.

    Raises:

    Type Description 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\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
    "},{"location":"docforge/#docforge.GriffeLoader.load_project","title":"load_project","text":"
    load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

    Load multiple modules and assemble them into a Project model.

    Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

    Parameters:

    Name Type Description Default module_paths list[str]

    List of dotted module import paths to load.

    required project_name str | None

    Optional override for the project name. Defaults to the top-level name of the first module.

    None skip_import_errors bool | None

    If True, modules that fail to load will be skipped instead of raising an error.

    None

    Returns:

    Name Type Description Project Project

    A populated Project instance containing the loaded modules.

    Raises:

    Type Description ValueError

    If no module paths are provided.

    ImportError

    If a module fails to load and skip_import_errors is False.

    "},{"location":"docforge/#docforge.MCPRenderer","title":"MCPRenderer","text":"

    Renderer that generates MCP-compatible documentation resources.

    This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

    "},{"location":"docforge/#docforge.MCPRenderer-functions","title":"Functions","text":""},{"location":"docforge/#docforge.MCPRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(project: Project, out_dir: Path) -> None\n

    Generate MCP documentation resources for a project.

    The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

    Parameters:

    Name Type Description Default project Project

    Documentation project model to render.

    required out_dir Path

    Directory where MCP resources will be written.

    required"},{"location":"docforge/#docforge.MkDocsRenderer","title":"MkDocsRenderer","text":"

    Renderer that produces Markdown documentation for MkDocs.

    Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

    "},{"location":"docforge/#docforge.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"docforge/#docforge.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
    generate_readme(\n    project: Project,\n    docs_dir: Path,\n    module_is_source: bool | None = None,\n    readme_dir: Path | None = None,\n) -> None\n

    Generate a README.md file from the root module docstring.

    Notes

    Parameters:

    Name Type Description Default project Project

    Project model containing documentation metadata.

    required docs_dir Path

    Directory containing generated documentation sources.

    required module_is_source bool | None

    Whether the module is treated as the project source root.

    None readme_dir Path | None

    Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

    None"},{"location":"docforge/#docforge.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

    Generate Markdown documentation files for a project.

    This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

    Parameters:

    Name Type Description Default project Project

    Project model containing modules to document.

    required out_dir Path

    Directory where generated Markdown files will be written.

    required module_is_source bool | None

    If True, treat the specified module as the documentation root rather than nesting it inside a folder.

    None"},{"location":"docforge/#docforge-functions","title":"Functions","text":""},{"location":"docforge/#docforge.discover_module_paths","title":"discover_module_paths","text":"
    discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

    Discover Python modules within a package directory.

    The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

    Discovery rules:

    Parameters:

    Name Type Description Default module_name str

    Top-level package name to discover modules from.

    required project_root Path | None

    Root directory used to resolve module paths. If not provided, the current working directory is used.

    None

    Returns:

    Type Description list[str]

    list[str]: A sorted list of unique dotted module import paths.

    Raises:

    Type Description FileNotFoundError

    If the specified package directory does not exist.

    "},{"location":"docforge/cli/","title":"Cli","text":""},{"location":"docforge/cli/#docforge.cli","title":"docforge.cli","text":""},{"location":"docforge/cli/#docforge.cli--summary","title":"Summary","text":"

    Command line interface entry point for doc-forge.

    This module exposes the primary CLI entry function used by the doc-forge command. The actual command implementation resides in docforge.cli.main, while this module provides a stable import path for external tools and the package entry point configuration.

    The CLI is responsible for orchestrating documentation workflows such as generating renderer sources, building documentation sites, exporting machine-readable documentation bundles, and starting development or MCP servers.

    "},{"location":"docforge/cli/#docforge.cli--typical-usage","title":"Typical usage","text":"

    The CLI is normally invoked through the installed command:

    doc-forge <command> [options]\n

    Programmatic invocation is also possible:

    Example:

    ```python\nfrom docforge.cli import main\nmain()\n```\n
    "},{"location":"docforge/cli/api_utils/","title":"Api Utils","text":""},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils","title":"docforge.cli.api_utils","text":""},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils--summary","title":"Summary","text":"

    Utilities for building API documentation from an OpenAPI specification.

    "},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils-classes","title":"Classes","text":""},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils.OpenAPIMetadata","title":"OpenAPIMetadata dataclass","text":"
    OpenAPIMetadata(\n    site_name: str,\n    site_description: str | None,\n    site_author: str | None,\n)\n

    Metadata derived from the info block of an OpenAPI specification.

    Attributes:

    Name Type Description site_name str

    Spec title, used as the MkDocs site name.

    site_description str | None

    Spec description, used as the site description.

    site_author str | None

    Contact name (fallback: contact email), used as the site author.

    "},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils-functions","title":"Functions","text":""},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils.derive_metadata","title":"derive_metadata","text":"
    derive_metadata(spec: dict[Any, Any]) -> OpenAPIMetadata\n

    Derive MkDocs site metadata from an OpenAPI spec info block.

    Parameters:

    Name Type Description Default spec dict

    Parsed OpenAPI specification.

    required

    Returns:

    Name Type Description OpenAPIMetadata OpenAPIMetadata

    Site name, description, and author derived from the spec.

    "},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils.generate_api_sources","title":"generate_api_sources","text":"
    generate_api_sources(\n    spec: dict[Any, Any], docs_dir: Path\n) -> None\n

    Generate swagger-enabled Markdown sources and the spec copy.

    The specification is written as openapi.json inside docs_dir and an index.md embedding the swagger UI is generated alongside it.

    Parameters:

    Name Type Description Default spec dict

    Parsed OpenAPI specification.

    required docs_dir Path

    Directory (for example docs/api) where the swagger sources are written.

    required"},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils.load_openapi_spec","title":"load_openapi_spec","text":"
    load_openapi_spec(spec_path: Path) -> dict[Any, Any]\n

    Load and validate an OpenAPI specification from a JSON file.

    Parameters:

    Name Type Description Default spec_path Path

    Path to the OpenAPI JSON specification file.

    required

    Returns:

    Name Type Description dict dict[Any, Any]

    The parsed OpenAPI specification.

    Raises:

    Type Description ClickException

    If the file cannot be read or the info block is invalid.

    "},{"location":"docforge/cli/commands/","title":"Commands","text":""},{"location":"docforge/cli/commands/#docforge.cli.commands","title":"docforge.cli.commands","text":""},{"location":"docforge/cli/commands/#docforge.cli.commands--summary","title":"Summary","text":"

    Command definitions for the doc-forge CLI.

    Provides the CLI structure using Click, including build, serve, and tree commands.

    Notes "},{"location":"docforge/cli/commands/#docforge.cli.commands-classes","title":"Classes","text":""},{"location":"docforge/cli/commands/#docforge.cli.commands-functions","title":"Functions","text":""},{"location":"docforge/cli/commands/#docforge.cli.commands.build","title":"build","text":"
    build(\n    mcp: bool,\n    mkdocs: bool,\n    api: bool,\n    wiki: bool,\n    refresh: bool,\n    module_is_source: bool,\n    module: str | None,\n    openapi_spec: Path | None,\n    project_name: str | None,\n    site_name: str | None,\n    docs_dir: Path,\n    wiki_dir: Path,\n    nav_file: Path,\n    template: Path | None,\n    out_dir: Path,\n) -> None\n

    Build documentation artifacts.

    This command runs the full documentation pipeline: it loads Python modules, generates renderer-specific documentation sources, and optionally builds the final output.

    Depending on the selected options, the build can target:

    Each enabled site kind produces its own MkDocs configuration (docs/mkdocs.{kind}.yml) and its own build (site/{kind}).

    Notes

    Parameters:

    Name Type Description Default mcp bool

    Enable MCP documentation generation.

    required mkdocs bool

    Enable the lib MkDocs documentation generation.

    required api bool

    Enable API documentation generation from an OpenAPI spec.

    required wiki bool

    Build a hand-written wiki directory as its own MkDocs site.

    required refresh bool

    Regenerate docs/mkdocs.{kind}.yml from templates even when it already exists. By default, existing configs are used as-is.

    required module_is_source bool

    Treat the specified module directory as the project root.

    required module str | None

    Python module import path to document.

    required openapi_spec Path | None

    Path to the OpenAPI JSON specification used for API docs.

    required project_name str | None

    Optional override for the project name.

    required site_name str | None

    Display name for the lib and wiki MkDocs sites.

    required docs_dir Path

    Shared documentation root used for generated sources.

    required wiki_dir Path

    Directory containing hand-written wiki markdown files.

    required nav_file Path

    Path to the navigation specification file.

    required template Path | None

    Optional custom MkDocs configuration template.

    required out_dir Path

    Output directory for generated MCP resources.

    required

    Raises:

    Type Description UsageError

    If required options are missing or conflicting.

    "},{"location":"docforge/cli/commands/#docforge.cli.commands.serve","title":"serve","text":"
    serve(\n    mcp: bool,\n    mkdocs: bool,\n    lib: bool,\n    api: bool,\n    wiki: bool,\n    module: str | None,\n    mkdocs_yml: Path,\n    out_dir: Path,\n) -> None\n

    Serve generated documentation locally.

    Depending on the selected mode, this command starts either:

    The kind flags (--lib, --api, --wiki) select the generated per-kind config (docs/mkdocs.{kind}.yml); --mkdocs serves the config passed via --mkdocs-yml.

    Parameters:

    Name Type Description Default mcp bool

    Serve documentation using the MCP server.

    required mkdocs bool

    Serve the MkDocs development site from --mkdocs-yml.

    required lib bool

    Serve the lib MkDocs site.

    required api bool

    Serve the API MkDocs site.

    required wiki bool

    Serve the wiki MkDocs site.

    required module str | None

    Python module import path to serve via MCP.

    required mkdocs_yml Path

    Path to the MkDocs configuration file.

    required out_dir Path

    Root directory containing MCP documentation resources.

    required

    Raises:

    Type Description UsageError

    If invalid or conflicting options are provided.

    "},{"location":"docforge/cli/commands/#docforge.cli.commands.tree","title":"tree","text":"
    tree(module: str, project_name: str | None) -> None\n

    Display the documentation object tree for a module.

    This command introspects the specified module and prints a hierarchical representation of the discovered documentation objects, including modules, classes, functions, and members.

    Parameters:

    Name Type Description Default module str

    Python module import path to introspect.

    required project_name str | None

    Optional name to display as the project root.

    required"},{"location":"docforge/cli/main/","title":"Main","text":""},{"location":"docforge/cli/main/#docforge.cli.main","title":"docforge.cli.main","text":""},{"location":"docforge/cli/main/#docforge.cli.main--summary","title":"Summary","text":"

    Command-line entry point for the doc-forge CLI.

    This module exposes the executable entry point that initializes the Click command group defined in docforge.cli.commands.

    "},{"location":"docforge/cli/main/#docforge.cli.main-functions","title":"Functions","text":""},{"location":"docforge/cli/main/#docforge.cli.main.main","title":"main","text":"
    main() -> None\n

    Run the doc-forge command-line interface.

    This function initializes and executes the Click CLI application. It is used as the console entry point when invoking doc-forge from the command line.

    "},{"location":"docforge/cli/mcp_utils/","title":"Mcp Utils","text":""},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils","title":"docforge.cli.mcp_utils","text":""},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils--summary","title":"Summary","text":"

    Utilities for working with MCP in the doc-forge CLI.

    Notes "},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils-classes","title":"Classes","text":""},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils-functions","title":"Functions","text":""},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils.generate_resources","title":"generate_resources","text":"
    generate_resources(\n    module: str, project_name: str | None, out_dir: Path\n) -> None\n

    Generate MCP documentation resources from a Python module.

    The function performs project introspection, builds the internal documentation model, and renders MCP-compatible JSON resources to the specified output directory.

    Parameters:

    Name Type Description Default module str

    Python module import path used as the entry point for documentation generation.

    required project_name str | None

    Optional override for the project name used in generated documentation metadata.

    required out_dir Path

    Directory where MCP resources (index.json, nav.json, and module data) will be written.

    required"},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils.serve","title":"serve","text":"
    serve(module: str, mcp_root: Path) -> None\n

    Start an MCP server for a pre-generated documentation bundle.

    The server exposes documentation resources such as project metadata, navigation structure, and module documentation through MCP endpoints.

    Parameters:

    Name Type Description Default module str

    Python module import path used to identify the served documentation instance.

    required mcp_root Path

    Path to the directory containing the MCP documentation bundle (index.json, nav.json, and modules/).

    required

    Raises:

    Type Description ClickException

    If the MCP documentation bundle is missing required files or directories.

    "},{"location":"docforge/cli/mkdocs_utils/","title":"Mkdocs Utils","text":""},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils","title":"docforge.cli.mkdocs_utils","text":""},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils--summary","title":"Summary","text":"

    Utilities for working with MkDocs in the doc-forge CLI.

    Notes "},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils-classes","title":"Classes","text":""},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils-functions","title":"Functions","text":""},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_configs","title":"build_configs","text":"
    build_configs(yml_paths: Iterable[Path]) -> None\n

    Build the MkDocs documentation site for every given configuration.

    Each configuration file is loaded and built in turn, producing the per-kind static sites (site/lib, site/api, site/wiki).

    Parameters:

    Name Type Description Default yml_paths Iterable[Path]

    Configuration files to build, in order.

    required

    Raises:

    Type Description ClickException

    If a configuration file does not exist.

    "},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_lib_nav","title":"build_lib_nav","text":"
    build_lib_nav(\n    nav_file: Path, docs_root: Path\n) -> tuple[list[dict[str, Any]], dict[str, str] | None]\n

    Build the re-rooted navigation block for a lib site.

    The navigation specification is resolved against the shared documentation root and every resulting path is re-rooted relative to the lib subdirectory by stripping its leading lib/ scope component.

    Parameters:

    Name Type Description Default nav_file Path

    Path to the docforge.nav.yml navigation specification.

    required docs_root Path

    Shared documentation root containing the lib sources.

    required

    Returns:

    Type Description tuple[list[dict[str, Any]], dict[str, str] | None]

    tuple[list[dict[str, Any]], dict[str, str] | None]: The re-rooted navigation block and the optional theme icon mapping from the specification.

    Raises:

    Type Description FileError

    If the navigation specification cannot be found.

    "},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_wiki_nav_block","title":"build_wiki_nav_block","text":"
    build_wiki_nav_block(\n    wiki_dir: Path,\n) -> list[dict[str, Any]]\n

    Build the re-rooted navigation block for a wiki site.

    The wiki navigation derived from the wiki file structure is re-rooted relative to the wiki directory itself by stripping the leading wiki/ scope component.

    Parameters:

    Name Type Description Default wiki_dir Path

    Path to the hand-written wiki directory, for example docs/wiki.

    required

    Returns:

    Type Description list[dict[str, Any]]

    list[dict[str, Any]]: Navigation entries relative to the wiki directory.

    Raises:

    Type Description FileError

    If the wiki directory does not exist.

    "},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_site_config","title":"generate_site_config","text":"
    generate_site_config(\n    kind: str,\n    kind_root: Path,\n    nav_block: list[dict[str, Any]],\n    out: Path,\n    site_name: str,\n    docs_dir: str,\n    site_dir: str,\n    template: Path | None = None,\n    site_description: str | None = None,\n    site_author: str | None = None,\n    theme_icon: dict[str, str] | None = None,\n) -> None\n

    Generate a per-kind mkdocs.{kind}.yml configuration file.

    The configuration is created by merging the shared mkdocs.common.yml template with the fragment contributed by the kind (lib, api, or wiki). Both docs_dir and site_dir are written relative to the configuration file's directory: the kind's sources when expressed as a sibling path (for example lib) and the per-kind site output (for example ../site/lib).

    Parameters:

    Name Type Description Default kind str

    Documentation kind, one of lib, api, or wiki.

    required kind_root Path

    Directory scoped to the kind (for example docs/lib) that serves as the MkDocs docs_dir.

    required nav_block list[dict[str, Any]]

    Re-rooted navigation entries for the kind's site.

    required out Path

    Destination path where the generated mkdocs.{kind}.yml file is written.

    required site_name str

    Display name for the generated documentation site.

    required docs_dir str

    MkDocs docs_dir value, relative to the configuration file's directory.

    required site_dir str

    MkDocs site_dir value, relative to the configuration file's directory.

    required template Path | None

    Optional path to a fully custom MkDocs configuration template that replaces the built-in templates entirely.

    None site_description str | None

    Optional site description written into the configuration.

    None site_author str | None

    Optional site author written into the configuration.

    None theme_icon dict[str, str] | None

    Optional mapping of theme icon entries injected as theme.icon.

    None"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_sources","title":"generate_sources","text":"
    generate_sources(\n    module: str,\n    docs_dir: Path,\n    project_name: str | None = None,\n    module_is_source: bool | None = None,\n    readme_dir: Path | None = None,\n) -> None\n

    Generate MkDocs Markdown sources for a Python module.

    This function introspects the specified module, builds the internal documentation model, and renders Markdown documentation files for use with MkDocs.

    Parameters:

    Name Type Description Default module str

    Python module import path used as the entry point for documentation generation.

    required docs_dir Path

    Directory where the generated Markdown files will be written.

    required project_name str | None

    Optional override for the project name used in documentation metadata.

    None module_is_source bool | None

    If True, treat the specified module directory as the project root rather than a nested module.

    None readme_dir Path | None

    Directory where the generated README.md should be written. If not provided, defaults to the parent of docs_dir.

    None"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.load_spec_icon","title":"load_spec_icon","text":"
    load_spec_icon(nav_file: Path) -> dict[str, str] | None\n

    Load the theme icon mapping from a navigation specification.

    Parameters:

    Name Type Description Default nav_file Path

    Path to the navigation specification file.

    required

    Returns:

    Type Description dict[str, str] | None

    dict[str, str] | None: The icon mapping, or None when the specification file is absent or cannot be parsed.

    "},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.serve","title":"serve","text":"
    serve(mkdocs_yml: Path) -> None\n

    Start an MkDocs development server with live reload.

    The server watches documentation files and automatically reloads the site when changes are detected.

    Parameters:

    Name Type Description Default mkdocs_yml Path

    Path to the mkdocs.yml configuration file.

    required

    Raises:

    Type Description ClickException

    If the configuration file does not exist.

    "},{"location":"docforge/loaders/","title":"Loaders","text":""},{"location":"docforge/loaders/#docforge.loaders","title":"docforge.loaders","text":""},{"location":"docforge/loaders/#docforge.loaders--summary","title":"Summary","text":"

    Loader layer for doc-forge.

    The docforge.loaders package is responsible for discovering Python modules and extracting documentation data using static analysis.

    "},{"location":"docforge/loaders/#docforge.loaders--overview","title":"Overview","text":"

    This layer converts Python source code into an intermediate documentation model used by doc-forge. It performs module discovery, introspection, and initial filtering before the data is passed to the core documentation models.

    Core capabilities include:

    "},{"location":"docforge/loaders/#docforge.loaders-classes","title":"Classes","text":""},{"location":"docforge/loaders/#docforge.loaders.GriffeLoader","title":"GriffeLoader","text":"
    GriffeLoader()\n

    Load Python modules using Griffe and convert them into doc-forge models.

    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:

    Name Type Description _loader GriffeLoader

    Internal Griffe loader with dedicated module and line collections.

    Initialize the Griffe-backed loader.

    Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

    "},{"location":"docforge/loaders/#docforge.loaders.GriffeLoader-functions","title":"Functions","text":""},{"location":"docforge/loaders/#docforge.loaders.GriffeLoader.load_module","title":"load_module","text":"
    load_module(path: str) -> Module\n

    Load and convert a single Python module.

    The module is introspected using Griffe and then transformed into a doc-forge Module model.

    Parameters:

    Name Type Description Default path str

    Dotted import path of the module.

    required

    Returns:

    Name Type Description Module Module

    A populated Module instance.

    Raises:

    Type Description 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\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
    "},{"location":"docforge/loaders/#docforge.loaders.GriffeLoader.load_project","title":"load_project","text":"
    load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

    Load multiple modules and assemble them into a Project model.

    Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

    Parameters:

    Name Type Description Default module_paths list[str]

    List of dotted module import paths to load.

    required project_name str | None

    Optional override for the project name. Defaults to the top-level name of the first module.

    None skip_import_errors bool | None

    If True, modules that fail to load will be skipped instead of raising an error.

    None

    Returns:

    Name Type Description Project Project

    A populated Project instance containing the loaded modules.

    Raises:

    Type Description ValueError

    If no module paths are provided.

    ImportError

    If a module fails to load and skip_import_errors is False.

    "},{"location":"docforge/loaders/#docforge.loaders-functions","title":"Functions","text":""},{"location":"docforge/loaders/#docforge.loaders.discover_module_paths","title":"discover_module_paths","text":"
    discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

    Discover Python modules within a package directory.

    The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

    Discovery rules:

    Parameters:

    Name Type Description Default module_name str

    Top-level package name to discover modules from.

    required project_root Path | None

    Root directory used to resolve module paths. If not provided, the current working directory is used.

    None

    Returns:

    Type Description list[str]

    list[str]: A sorted list of unique dotted module import paths.

    Raises:

    Type Description FileNotFoundError

    If the specified package directory does not exist.

    "},{"location":"docforge/loaders/griffe_loader/","title":"Griffe Loader","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader","title":"docforge.loaders.griffe_loader","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader--summary","title":"Summary","text":"

    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 "},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader-classes","title":"Classes","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader","title":"GriffeLoader","text":"
    GriffeLoader()\n

    Load Python modules using Griffe and convert them into doc-forge models.

    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:

    Name Type Description _loader GriffeLoader

    Internal Griffe loader with dedicated module and line collections.

    Initialize the Griffe-backed loader.

    Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

    "},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader-functions","title":"Functions","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_module","title":"load_module","text":"
    load_module(path: str) -> Module\n

    Load and convert a single Python module.

    The module is introspected using Griffe and then transformed into a doc-forge Module model.

    Parameters:

    Name Type Description Default path str

    Dotted import path of the module.

    required

    Returns:

    Name Type Description Module Module

    A populated Module instance.

    Raises:

    Type Description 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\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
    "},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_project","title":"load_project","text":"
    load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

    Load multiple modules and assemble them into a Project model.

    Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

    Parameters:

    Name Type Description Default module_paths list[str]

    List of dotted module import paths to load.

    required project_name str | None

    Optional override for the project name. Defaults to the top-level name of the first module.

    None skip_import_errors bool | None

    If True, modules that fail to load will be skipped instead of raising an error.

    None

    Returns:

    Name Type Description Project Project

    A populated Project instance containing the loaded modules.

    Raises:

    Type Description ValueError

    If no module paths are provided.

    ImportError

    If a module fails to load and skip_import_errors is False.

    "},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader-functions","title":"Functions","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.discover_module_paths","title":"discover_module_paths","text":"
    discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

    Discover Python modules within a package directory.

    The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

    Discovery rules:

    Parameters:

    Name Type Description Default module_name str

    Top-level package name to discover modules from.

    required project_root Path | None

    Root directory used to resolve module paths. If not provided, the current working directory is used.

    None

    Returns:

    Type Description list[str]

    list[str]: A sorted list of unique dotted module import paths.

    Raises:

    Type Description FileNotFoundError

    If the specified package directory does not exist.

    "},{"location":"docforge/models/","title":"Models","text":""},{"location":"docforge/models/#docforge.models","title":"docforge.models","text":""},{"location":"docforge/models/#docforge.models--summary","title":"Summary","text":"

    Model layer for doc-forge.

    The docforge.models package defines the core data structures used to represent Python source code as a structured documentation model.

    "},{"location":"docforge/models/#docforge.models--overview","title":"Overview","text":"

    The model layer forms the central intermediate representation used throughout doc-forge. Python modules and objects discovered during introspection are converted into a hierarchy of documentation models that can later be rendered into different documentation formats.

    Key components:

    These models are intentionally renderer-agnostic, allowing the same documentation structure to be transformed into multiple output formats (e.g., MkDocs, MCP, or other renderers).

    "},{"location":"docforge/models/#docforge.models-classes","title":"Classes","text":""},{"location":"docforge/models/#docforge.models.DocObject","title":"DocObject","text":"
    DocObject(\n    name: str,\n    kind: str,\n    path: str,\n    signature: str | None = None,\n    docstring: str | None = None,\n)\n

    Representation of a documented Python object.

    A DocObject models a single Python entity discovered during introspection. Objects may contain nested members, allowing the structure of modules, classes, and other containers to be represented recursively.

    Attributes:

    Name Type Description name str

    Local name of the object.

    kind str

    Type of object (for example class, function, method, or attribute).

    path str

    Fully qualified dotted path to the object.

    signature str | None

    Callable signature if the object represents a callable.

    docstring str | None

    Raw docstring text extracted from the source code.

    members dict[str, DocObject]

    Mapping of member names to child DocObject instances.

    Initialize a DocObject instance.

    Parameters:

    Name Type Description Default name str

    Local name of the object.

    required kind str

    Object type identifier (for example class or function).

    required path str

    Fully qualified dotted path of the object.

    required signature str | None

    Callable signature if applicable.

    None docstring str | None

    Documentation string associated with the object.

    None"},{"location":"docforge/models/#docforge.models.DocObject-functions","title":"Functions","text":""},{"location":"docforge/models/#docforge.models.DocObject.add_member","title":"add_member","text":"
    add_member(obj: DocObject) -> None\n

    Add a child documentation object.

    This is typically used when attaching methods to classes or nested objects to their parent containers.

    Parameters:

    Name Type Description Default obj DocObject

    Documentation object to add as a member.

    required"},{"location":"docforge/models/#docforge.models.DocObject.get_all_members","title":"get_all_members","text":"
    get_all_members() -> Iterable[DocObject]\n

    Return all child members of the object.

    Returns:

    Type Description Iterable[DocObject]

    Iterable[DocObject]: An iterable of DocObject instances representing nested members.

    "},{"location":"docforge/models/#docforge.models.DocObject.get_member","title":"get_member","text":"
    get_member(name: str) -> DocObject\n

    Retrieve a member object by name.

    Parameters:

    Name Type Description Default name str

    Name of the member to retrieve.

    required

    Returns:

    Name Type Description DocObject DocObject

    The corresponding DocObject instance.

    Raises:

    Type Description KeyError

    If the member does not exist.

    "},{"location":"docforge/models/#docforge.models.Module","title":"Module","text":"
    Module(path: str, docstring: str | None = None)\n

    Representation of a documented Python module or package.

    A Module stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.

    Attributes:

    Name Type Description path str

    Dotted import path of the module.

    docstring str | None

    Module-level documentation string, if present.

    members dict[str, DocObject]

    Mapping of object names to their corresponding DocObject representations.

    Initialize a Module instance.

    Parameters:

    Name Type Description Default path str

    Dotted import path identifying the module.

    required docstring str | None

    Module-level documentation text, if available.

    None"},{"location":"docforge/models/#docforge.models.Module-functions","title":"Functions","text":""},{"location":"docforge/models/#docforge.models.Module.add_object","title":"add_object","text":"
    add_object(obj: DocObject) -> None\n

    Add a documented object to the module.

    Parameters:

    Name Type Description Default obj DocObject

    Documentation object to register as a top-level member of the module.

    required"},{"location":"docforge/models/#docforge.models.Module.get_all_objects","title":"get_all_objects","text":"
    get_all_objects() -> Iterable[DocObject]\n

    Return all top-level documentation objects in the module.

    Returns:

    Type Description Iterable[DocObject]

    Iterable[DocObject]: An iterable of DocObject instances representing the module's public members.

    "},{"location":"docforge/models/#docforge.models.Module.get_object","title":"get_object","text":"
    get_object(name: str) -> DocObject\n

    Retrieve a documented object by name.

    Parameters:

    Name Type Description Default name str

    Name of the object to retrieve.

    required

    Returns:

    Name Type Description DocObject DocObject

    The corresponding DocObject instance.

    Raises:

    Type Description KeyError

    If no object with the given name exists.

    "},{"location":"docforge/models/#docforge.models.Project","title":"Project","text":"
    Project(name: str)\n

    Representation of a documentation project.

    A Project serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.

    Attributes:

    Name Type Description name str

    Name of the project.

    modules dict[str, Module]

    Mapping of module paths to Module instances.

    Initialize a Project instance.

    Parameters:

    Name Type Description Default name str

    Name used to identify the documentation project.

    required Example

    Create a project and register a module:

    ```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n
    "},{"location":"docforge/models/#docforge.models.Project-functions","title":"Functions","text":""},{"location":"docforge/models/#docforge.models.Project.add_module","title":"add_module","text":"
    add_module(module: Module) -> None\n

    Register a module in the project.

    Parameters:

    Name Type Description Default module Module

    Module instance to add to the project.

    required"},{"location":"docforge/models/#docforge.models.Project.get_all_modules","title":"get_all_modules","text":"
    get_all_modules() -> Iterable[Module]\n

    Return all modules contained in the project.

    Returns:

    Type Description Iterable[Module]

    Iterable[Module]: An iterable of Module instances.

    "},{"location":"docforge/models/#docforge.models.Project.get_module","title":"get_module","text":"
    get_module(path: str) -> Module\n

    Retrieve a module by its dotted path.

    Parameters:

    Name Type Description Default path str

    Fully qualified dotted module path (for example pkg.module).

    required

    Returns:

    Name Type Description Module Module

    The corresponding Module instance.

    Raises:

    Type Description KeyError

    If the module does not exist in the project.

    "},{"location":"docforge/models/#docforge.models.Project.get_module_list","title":"get_module_list","text":"
    get_module_list() -> list[str]\n

    Return the list of module import paths.

    Returns:

    Type Description list[str]

    list[str]: A list containing the dotted paths of all modules in the project.

    "},{"location":"docforge/models/module/","title":"Module","text":""},{"location":"docforge/models/module/#docforge.models.module","title":"docforge.models.module","text":""},{"location":"docforge/models/module/#docforge.models.module--summary","title":"Summary","text":"

    Documentation model representing a Python module or package.

    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 "},{"location":"docforge/models/module/#docforge.models.module-classes","title":"Classes","text":""},{"location":"docforge/models/module/#docforge.models.module.Module","title":"Module","text":"
    Module(path: str, docstring: str | None = None)\n

    Representation of a documented Python module or package.

    A Module stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.

    Attributes:

    Name Type Description path str

    Dotted import path of the module.

    docstring str | None

    Module-level documentation string, if present.

    members dict[str, DocObject]

    Mapping of object names to their corresponding DocObject representations.

    Initialize a Module instance.

    Parameters:

    Name Type Description Default path str

    Dotted import path identifying the module.

    required docstring str | None

    Module-level documentation text, if available.

    None"},{"location":"docforge/models/module/#docforge.models.module.Module-functions","title":"Functions","text":""},{"location":"docforge/models/module/#docforge.models.module.Module.add_object","title":"add_object","text":"
    add_object(obj: DocObject) -> None\n

    Add a documented object to the module.

    Parameters:

    Name Type Description Default obj DocObject

    Documentation object to register as a top-level member of the module.

    required"},{"location":"docforge/models/module/#docforge.models.module.Module.get_all_objects","title":"get_all_objects","text":"
    get_all_objects() -> Iterable[DocObject]\n

    Return all top-level documentation objects in the module.

    Returns:

    Type Description Iterable[DocObject]

    Iterable[DocObject]: An iterable of DocObject instances representing the module's public members.

    "},{"location":"docforge/models/module/#docforge.models.module.Module.get_object","title":"get_object","text":"
    get_object(name: str) -> DocObject\n

    Retrieve a documented object by name.

    Parameters:

    Name Type Description Default name str

    Name of the object to retrieve.

    required

    Returns:

    Name Type Description DocObject DocObject

    The corresponding DocObject instance.

    Raises:

    Type Description KeyError

    If no object with the given name exists.

    "},{"location":"docforge/models/object/","title":"Object","text":""},{"location":"docforge/models/object/#docforge.models.object","title":"docforge.models.object","text":""},{"location":"docforge/models/object/#docforge.models.object--summary","title":"Summary","text":"

    Documentation model representing individual Python objects.

    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 "},{"location":"docforge/models/object/#docforge.models.object-classes","title":"Classes","text":""},{"location":"docforge/models/object/#docforge.models.object.DocObject","title":"DocObject","text":"
    DocObject(\n    name: str,\n    kind: str,\n    path: str,\n    signature: str | None = None,\n    docstring: str | None = None,\n)\n

    Representation of a documented Python object.

    A DocObject models a single Python entity discovered during introspection. Objects may contain nested members, allowing the structure of modules, classes, and other containers to be represented recursively.

    Attributes:

    Name Type Description name str

    Local name of the object.

    kind str

    Type of object (for example class, function, method, or attribute).

    path str

    Fully qualified dotted path to the object.

    signature str | None

    Callable signature if the object represents a callable.

    docstring str | None

    Raw docstring text extracted from the source code.

    members dict[str, DocObject]

    Mapping of member names to child DocObject instances.

    Initialize a DocObject instance.

    Parameters:

    Name Type Description Default name str

    Local name of the object.

    required kind str

    Object type identifier (for example class or function).

    required path str

    Fully qualified dotted path of the object.

    required signature str | None

    Callable signature if applicable.

    None docstring str | None

    Documentation string associated with the object.

    None"},{"location":"docforge/models/object/#docforge.models.object.DocObject-functions","title":"Functions","text":""},{"location":"docforge/models/object/#docforge.models.object.DocObject.add_member","title":"add_member","text":"
    add_member(obj: DocObject) -> None\n

    Add a child documentation object.

    This is typically used when attaching methods to classes or nested objects to their parent containers.

    Parameters:

    Name Type Description Default obj DocObject

    Documentation object to add as a member.

    required"},{"location":"docforge/models/object/#docforge.models.object.DocObject.get_all_members","title":"get_all_members","text":"
    get_all_members() -> Iterable[DocObject]\n

    Return all child members of the object.

    Returns:

    Type Description Iterable[DocObject]

    Iterable[DocObject]: An iterable of DocObject instances representing nested members.

    "},{"location":"docforge/models/object/#docforge.models.object.DocObject.get_member","title":"get_member","text":"
    get_member(name: str) -> DocObject\n

    Retrieve a member object by name.

    Parameters:

    Name Type Description Default name str

    Name of the member to retrieve.

    required

    Returns:

    Name Type Description DocObject DocObject

    The corresponding DocObject instance.

    Raises:

    Type Description KeyError

    If the member does not exist.

    "},{"location":"docforge/models/project/","title":"Project","text":""},{"location":"docforge/models/project/#docforge.models.project","title":"docforge.models.project","text":""},{"location":"docforge/models/project/#docforge.models.project--summary","title":"Summary","text":"

    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 "},{"location":"docforge/models/project/#docforge.models.project-classes","title":"Classes","text":""},{"location":"docforge/models/project/#docforge.models.project.Project","title":"Project","text":"
    Project(name: str)\n

    Representation of a documentation project.

    A Project serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.

    Attributes:

    Name Type Description name str

    Name of the project.

    modules dict[str, Module]

    Mapping of module paths to Module instances.

    Initialize a Project instance.

    Parameters:

    Name Type Description Default name str

    Name used to identify the documentation project.

    required Example

    Create a project and register a module:

    ```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n
    "},{"location":"docforge/models/project/#docforge.models.project.Project-functions","title":"Functions","text":""},{"location":"docforge/models/project/#docforge.models.project.Project.add_module","title":"add_module","text":"
    add_module(module: Module) -> None\n

    Register a module in the project.

    Parameters:

    Name Type Description Default module Module

    Module instance to add to the project.

    required"},{"location":"docforge/models/project/#docforge.models.project.Project.get_all_modules","title":"get_all_modules","text":"
    get_all_modules() -> Iterable[Module]\n

    Return all modules contained in the project.

    Returns:

    Type Description Iterable[Module]

    Iterable[Module]: An iterable of Module instances.

    "},{"location":"docforge/models/project/#docforge.models.project.Project.get_module","title":"get_module","text":"
    get_module(path: str) -> Module\n

    Retrieve a module by its dotted path.

    Parameters:

    Name Type Description Default path str

    Fully qualified dotted module path (for example pkg.module).

    required

    Returns:

    Name Type Description Module Module

    The corresponding Module instance.

    Raises:

    Type Description KeyError

    If the module does not exist in the project.

    "},{"location":"docforge/models/project/#docforge.models.project.Project.get_module_list","title":"get_module_list","text":"
    get_module_list() -> list[str]\n

    Return the list of module import paths.

    Returns:

    Type Description list[str]

    list[str]: A list containing the dotted paths of all modules in the project.

    "},{"location":"docforge/nav/","title":"Nav","text":""},{"location":"docforge/nav/#docforge.nav","title":"docforge.nav","text":"

    Navigation layer for doc-forge.

    The docforge.nav package manages the relationship between the logical documentation structure defined by the user and the physical documentation files generated on disk.

    "},{"location":"docforge/nav/#docforge.nav--workflow","title":"Workflow","text":"
    1. Specification \u2013 Users define navigation intent in docforge.nav.yml.
    2. Resolution \u2013 resolve_nav expands patterns and matches them against generated Markdown files.
    3. Emission \u2013 MkDocsNavEmitter converts the resolved structure into the YAML navigation format required by mkdocs.yml.

    This layer separates documentation organization from the underlying source code layout, enabling flexible grouping, ordering, and navigation structures independent of module hierarchy.

    "},{"location":"docforge/nav/#docforge.nav-classes","title":"Classes","text":""},{"location":"docforge/nav/#docforge.nav.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"

    Emit MkDocs navigation structures from resolved navigation data.

    The emitter transforms a ResolvedNav object into the YAML-compatible list structure expected by the MkDocs nav configuration field.

    "},{"location":"docforge/nav/#docforge.nav.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"docforge/nav/#docforge.nav.MkDocsNavEmitter.emit","title":"emit","text":"
    emit(nav: ResolvedNav) -> list[dict[str, Any]]\n

    Generate a navigation structure for mkdocs.yml.

    Parameters:

    Name Type Description Default nav ResolvedNav

    Resolved navigation data describing documentation groups and their associated Markdown files.

    required

    Returns:

    Type Description list[dict[str, Any]]

    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.

    "},{"location":"docforge/nav/#docforge.nav.NavSpec","title":"NavSpec","text":"
    NavSpec(\n    home: str | None,\n    groups: dict[str, list[str]],\n    icon: dict[str, str] | None = None,\n)\n

    Parsed representation of a navigation specification.

    A NavSpec describes the intended documentation navigation layout before it is resolved against the filesystem.

    Attributes:

    Name Type Description home str | None

    Relative path to the documentation home page (for example index.md).

    groups dict[str, list[str]]

    Mapping of navigation group titles to lists of file patterns or glob expressions.

    icon

    Optional mapping of theme icon entries (for example {\"logo\": \"material/code-tags\"}) injected into the MkDocs theme as theme.icon.

    Initialize a NavSpec instance.

    Parameters:

    Name Type Description Default home str | None

    Relative path to the home document.

    required groups dict[str, list[str]]

    Mapping of group names to lists of path patterns (glob expressions).

    required icon dict[str, str] | None

    Optional mapping of theme icon entries applied to the generated MkDocs configuration.

    None"},{"location":"docforge/nav/#docforge.nav.NavSpec-functions","title":"Functions","text":""},{"location":"docforge/nav/#docforge.nav.NavSpec.all_patterns","title":"all_patterns","text":"
    all_patterns() -> list[str]\n

    Return all path patterns referenced by the specification.

    Returns:

    Type Description list[str]

    list[str]: A list containing the home document (if defined) and all group pattern entries.

    "},{"location":"docforge/nav/#docforge.nav.NavSpec.load","title":"load classmethod","text":"
    load(path: Path) -> NavSpec\n

    Load a navigation specification from a YAML file.

    Parameters:

    Name Type Description Default path Path

    Filesystem path to the navigation specification file.

    required

    Returns:

    Name Type Description NavSpec NavSpec

    A NavSpec instance representing the parsed configuration.

    Raises:

    Type Description FileNotFoundError

    If the specified file does not exist.

    ValueError

    If the file contents are not a valid navigation specification.

    "},{"location":"docforge/nav/#docforge.nav.ResolvedNav","title":"ResolvedNav","text":"
    ResolvedNav(\n    home: str | None,\n    groups: dict[str, list[Path]],\n    docs_root: Path | None = None,\n)\n

    Resolved navigation structure.

    A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.

    Attributes:

    Name Type Description home str | None

    Relative path to the documentation home page.

    groups dict[str, list[Path]]

    Mapping of navigation group titles to lists of resolved documentation file paths.

    Initialize a ResolvedNav instance.

    Parameters:

    Name Type Description Default home str | None

    Relative path to the home page within the documentation root.

    required groups dict[str, list[Path]]

    Mapping of group titles to resolved documentation file paths.

    required docs_root Path | None

    Root directory of the documentation source files.

    None"},{"location":"docforge/nav/#docforge.nav.ResolvedNav-functions","title":"Functions","text":""},{"location":"docforge/nav/#docforge.nav.ResolvedNav.all_files","title":"all_files","text":"
    all_files() -> Iterable[Path]\n

    Iterate over all files referenced by the navigation structure.

    Yields:

    Name Type Description Path Iterable[Path]

    A documentation file referenced by the navigation, including the home page when defined.

    Raises:

    Type Description RuntimeError

    If the home page is defined but the documentation root is not available for resolution.

    "},{"location":"docforge/nav/#docforge.nav-functions","title":"Functions","text":""},{"location":"docforge/nav/#docforge.nav.build_wiki_nav","title":"build_wiki_nav","text":"
    build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n

    Derive an MkDocs navigation block from a wiki directory.

    Returned paths are relative to the parent of wiki_dir and carry the wiki directory name as their leading component (for example wiki/01_overview.md when the wiki lives at docs/wiki). This makes the result directly usable in an MkDocs nav block with

    Parameters:

    Name Type Description Default wiki_dir Path

    Path to the hand-written wiki directory, for example docs/wiki.

    required

    Returns:

    Type Description 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.

    Raises:

    Type Description FileNotFoundError

    If the wiki directory does not exist.

    "},{"location":"docforge/nav/#docforge.nav.load_nav_spec","title":"load_nav_spec","text":"
    load_nav_spec(path: Path) -> NavSpec\n

    Load a navigation specification file.

    This helper function reads a YAML navigation file and constructs a corresponding NavSpec instance.

    Parameters:

    Name Type Description Default path Path

    Path to the navigation specification file.

    required

    Returns:

    Name Type Description NavSpec NavSpec

    A NavSpec instance representing the parsed specification.

    Raises:

    Type Description FileNotFoundError

    If the specification file does not exist.

    ValueError

    If the YAML structure is invalid.

    "},{"location":"docforge/nav/#docforge.nav.resolve_nav","title":"resolve_nav","text":"
    resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n

    Resolve a navigation specification against the filesystem.

    The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.

    Parameters:

    Name Type Description Default spec NavSpec

    Navigation specification describing documentation layout.

    required docs_root Path

    Root directory containing documentation Markdown files.

    required

    Returns:

    Name Type Description ResolvedNav ResolvedNav

    A ResolvedNav instance containing validated navigation paths.

    Raises:

    Type Description FileNotFoundError

    If the documentation root does not exist or a navigation pattern does not match any files.

    "},{"location":"docforge/nav/mkdocs/","title":"Mkdocs","text":""},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs","title":"docforge.nav.mkdocs","text":"

    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 "},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs-classes","title":"Classes","text":""},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"

    Emit MkDocs navigation structures from resolved navigation data.

    The emitter transforms a ResolvedNav object into the YAML-compatible list structure expected by the MkDocs nav configuration field.

    "},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter.emit","title":"emit","text":"
    emit(nav: ResolvedNav) -> list[dict[str, Any]]\n

    Generate a navigation structure for mkdocs.yml.

    Parameters:

    Name Type Description Default nav ResolvedNav

    Resolved navigation data describing documentation groups and their associated Markdown files.

    required

    Returns:

    Type Description list[dict[str, Any]]

    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.

    "},{"location":"docforge/nav/resolver/","title":"Resolver","text":""},{"location":"docforge/nav/resolver/#docforge.nav.resolver","title":"docforge.nav.resolver","text":"

    Navigation resolution utilities.

    This module resolves a NavSpec against the filesystem by expanding glob patterns and validating that referenced documentation files exist.

    Notes "},{"location":"docforge/nav/resolver/#docforge.nav.resolver-classes","title":"Classes","text":""},{"location":"docforge/nav/resolver/#docforge.nav.resolver.ResolvedNav","title":"ResolvedNav","text":"
    ResolvedNav(\n    home: str | None,\n    groups: dict[str, list[Path]],\n    docs_root: Path | None = None,\n)\n

    Resolved navigation structure.

    A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.

    Attributes:

    Name Type Description home str | None

    Relative path to the documentation home page.

    groups dict[str, list[Path]]

    Mapping of navigation group titles to lists of resolved documentation file paths.

    Initialize a ResolvedNav instance.

    Parameters:

    Name Type Description Default home str | None

    Relative path to the home page within the documentation root.

    required groups dict[str, list[Path]]

    Mapping of group titles to resolved documentation file paths.

    required docs_root Path | None

    Root directory of the documentation source files.

    None"},{"location":"docforge/nav/resolver/#docforge.nav.resolver.ResolvedNav-functions","title":"Functions","text":""},{"location":"docforge/nav/resolver/#docforge.nav.resolver.ResolvedNav.all_files","title":"all_files","text":"
    all_files() -> Iterable[Path]\n

    Iterate over all files referenced by the navigation structure.

    Yields:

    Name Type Description Path Iterable[Path]

    A documentation file referenced by the navigation, including the home page when defined.

    Raises:

    Type Description RuntimeError

    If the home page is defined but the documentation root is not available for resolution.

    "},{"location":"docforge/nav/resolver/#docforge.nav.resolver-functions","title":"Functions","text":""},{"location":"docforge/nav/resolver/#docforge.nav.resolver.resolve_nav","title":"resolve_nav","text":"
    resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n

    Resolve a navigation specification against the filesystem.

    The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.

    Parameters:

    Name Type Description Default spec NavSpec

    Navigation specification describing documentation layout.

    required docs_root Path

    Root directory containing documentation Markdown files.

    required

    Returns:

    Name Type Description ResolvedNav ResolvedNav

    A ResolvedNav instance containing validated navigation paths.

    Raises:

    Type Description FileNotFoundError

    If the documentation root does not exist or a navigation pattern does not match any files.

    "},{"location":"docforge/nav/spec/","title":"Spec","text":""},{"location":"docforge/nav/spec/#docforge.nav.spec","title":"docforge.nav.spec","text":"

    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 "},{"location":"docforge/nav/spec/#docforge.nav.spec-classes","title":"Classes","text":""},{"location":"docforge/nav/spec/#docforge.nav.spec.NavSpec","title":"NavSpec","text":"
    NavSpec(\n    home: str | None,\n    groups: dict[str, list[str]],\n    icon: dict[str, str] | None = None,\n)\n

    Parsed representation of a navigation specification.

    A NavSpec describes the intended documentation navigation layout before it is resolved against the filesystem.

    Attributes:

    Name Type Description home str | None

    Relative path to the documentation home page (for example index.md).

    groups dict[str, list[str]]

    Mapping of navigation group titles to lists of file patterns or glob expressions.

    icon

    Optional mapping of theme icon entries (for example {\"logo\": \"material/code-tags\"}) injected into the MkDocs theme as theme.icon.

    Initialize a NavSpec instance.

    Parameters:

    Name Type Description Default home str | None

    Relative path to the home document.

    required groups dict[str, list[str]]

    Mapping of group names to lists of path patterns (glob expressions).

    required icon dict[str, str] | None

    Optional mapping of theme icon entries applied to the generated MkDocs configuration.

    None"},{"location":"docforge/nav/spec/#docforge.nav.spec.NavSpec-functions","title":"Functions","text":""},{"location":"docforge/nav/spec/#docforge.nav.spec.NavSpec.all_patterns","title":"all_patterns","text":"
    all_patterns() -> list[str]\n

    Return all path patterns referenced by the specification.

    Returns:

    Type Description list[str]

    list[str]: A list containing the home document (if defined) and all group pattern entries.

    "},{"location":"docforge/nav/spec/#docforge.nav.spec.NavSpec.load","title":"load classmethod","text":"
    load(path: Path) -> NavSpec\n

    Load a navigation specification from a YAML file.

    Parameters:

    Name Type Description Default path Path

    Filesystem path to the navigation specification file.

    required

    Returns:

    Name Type Description NavSpec NavSpec

    A NavSpec instance representing the parsed configuration.

    Raises:

    Type Description FileNotFoundError

    If the specified file does not exist.

    ValueError

    If the file contents are not a valid navigation specification.

    "},{"location":"docforge/nav/spec/#docforge.nav.spec-functions","title":"Functions","text":""},{"location":"docforge/nav/spec/#docforge.nav.spec.load_nav_spec","title":"load_nav_spec","text":"
    load_nav_spec(path: Path) -> NavSpec\n

    Load a navigation specification file.

    This helper function reads a YAML navigation file and constructs a corresponding NavSpec instance.

    Parameters:

    Name Type Description Default path Path

    Path to the navigation specification file.

    required

    Returns:

    Name Type Description NavSpec NavSpec

    A NavSpec instance representing the parsed specification.

    Raises:

    Type Description FileNotFoundError

    If the specification file does not exist.

    ValueError

    If the YAML structure is invalid.

    "},{"location":"docforge/nav/wiki/","title":"Wiki","text":""},{"location":"docforge/nav/wiki/#docforge.nav.wiki","title":"docforge.nav.wiki","text":""},{"location":"docforge/nav/wiki/#docforge.nav.wiki--summary","title":"Summary","text":"

    Wiki navigation derivation.

    This module provides build_wiki_nav, which derives an MkDocs-ready navigation block from the file structure of a hand-written wiki directory (typically docs/wiki). wiki content is authored by hand and is never modified by doc-forge; only the navigation layout is inferred.

    "},{"location":"docforge/nav/wiki/#docforge.nav.wiki--notes","title":"Notes","text":""},{"location":"docforge/nav/wiki/#docforge.nav.wiki-functions","title":"Functions","text":""},{"location":"docforge/nav/wiki/#docforge.nav.wiki.build_wiki_nav","title":"build_wiki_nav","text":"
    build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n

    Derive an MkDocs navigation block from a wiki directory.

    Returned paths are relative to the parent of wiki_dir and carry the wiki directory name as their leading component (for example wiki/01_overview.md when the wiki lives at docs/wiki). This makes the result directly usable in an MkDocs nav block with

    Parameters:

    Name Type Description Default wiki_dir Path

    Path to the hand-written wiki directory, for example docs/wiki.

    required

    Returns:

    Type Description 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.

    Raises:

    Type Description FileNotFoundError

    If the wiki directory does not exist.

    "},{"location":"docforge/renderers/","title":"Renderers","text":""},{"location":"docforge/renderers/#docforge.renderers","title":"docforge.renderers","text":""},{"location":"docforge/renderers/#docforge.renderers--summary","title":"Summary","text":"

    Renderers layer for doc-forge.

    The docforge.renderers package transforms the internal documentation models into files formatted for specific documentation systems.

    "},{"location":"docforge/renderers/#docforge.renderers--overview","title":"Overview","text":"

    Renderers consume the doc-forge project model and generate output suitable for documentation tools or machine interfaces.

    Current implementations:

    "},{"location":"docforge/renderers/#docforge.renderers--extending","title":"Extending","text":"

    New renderers can be added by implementing the DocRenderer protocol defined in docforge.renderers.base.

    "},{"location":"docforge/renderers/#docforge.renderers-classes","title":"Classes","text":""},{"location":"docforge/renderers/#docforge.renderers.MCPRenderer","title":"MCPRenderer","text":"

    Renderer that generates MCP-compatible documentation resources.

    This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

    "},{"location":"docforge/renderers/#docforge.renderers.MCPRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/#docforge.renderers.MCPRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(project: Project, out_dir: Path) -> None\n

    Generate MCP documentation resources for a project.

    The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

    Parameters:

    Name Type Description Default project Project

    Documentation project model to render.

    required out_dir Path

    Directory where MCP resources will be written.

    required"},{"location":"docforge/renderers/#docforge.renderers.MkDocsRenderer","title":"MkDocsRenderer","text":"

    Renderer that produces Markdown documentation for MkDocs.

    Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

    "},{"location":"docforge/renderers/#docforge.renderers.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/#docforge.renderers.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
    generate_readme(\n    project: Project,\n    docs_dir: Path,\n    module_is_source: bool | None = None,\n    readme_dir: Path | None = None,\n) -> None\n

    Generate a README.md file from the root module docstring.

    Notes

    Parameters:

    Name Type Description Default project Project

    Project model containing documentation metadata.

    required docs_dir Path

    Directory containing generated documentation sources.

    required module_is_source bool | None

    Whether the module is treated as the project source root.

    None readme_dir Path | None

    Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

    None"},{"location":"docforge/renderers/#docforge.renderers.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

    Generate Markdown documentation files for a project.

    This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

    Parameters:

    Name Type Description Default project Project

    Project model containing modules to document.

    required out_dir Path

    Directory where generated Markdown files will be written.

    required module_is_source bool | None

    If True, treat the specified module as the documentation root rather than nesting it inside a folder.

    None"},{"location":"docforge/renderers/base/","title":"Base","text":""},{"location":"docforge/renderers/base/#docforge.renderers.base","title":"docforge.renderers.base","text":""},{"location":"docforge/renderers/base/#docforge.renderers.base--summary","title":"Summary","text":"

    Renderer base interfaces and configuration models.

    This module defines the base protocol and configuration container used by doc-forge renderers. Concrete renderer implementations should implement the DocRenderer protocol.

    "},{"location":"docforge/renderers/base/#docforge.renderers.base-classes","title":"Classes","text":""},{"location":"docforge/renderers/base/#docforge.renderers.base.DocRenderer","title":"DocRenderer","text":"

    Bases: Protocol

    Protocol defining the interface for documentation renderers.

    Implementations of this protocol are responsible for transforming a Project model into renderer-specific documentation sources.

    "},{"location":"docforge/renderers/base/#docforge.renderers.base.DocRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/base/#docforge.renderers.base.DocRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(project: Project, out_dir: Path) -> None\n

    Generate renderer-specific documentation sources.

    Parameters:

    Name Type Description Default project Project

    Project model containing modules and documentation objects.

    required out_dir Path

    Directory where generated documentation sources should be written.

    required"},{"location":"docforge/renderers/base/#docforge.renderers.base.RendererConfig","title":"RendererConfig","text":"
    RendererConfig(out_dir: Path, project: Project)\n

    Configuration container for documentation renderers.

    A RendererConfig instance groups together the project model and the output directory used during rendering.

    Attributes:

    Name Type Description out_dir Path

    Directory where generated documentation files will be written.

    project Project

    Documentation project model to be rendered.

    Initialize a RendererConfig instance.

    Parameters:

    Name Type Description Default out_dir Path

    Target directory where documentation files should be written.

    required project Project

    Introspected project model to render.

    required"},{"location":"docforge/renderers/base/#docforge.renderers.base.RendererConfig-functions","title":"Functions","text":""},{"location":"docforge/renderers/mcp_renderer/","title":"Mcp Renderer","text":""},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer","title":"docforge.renderers.mcp_renderer","text":""},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer--summary","title":"Summary","text":"

    MCP renderer implementation.

    This module defines the MCPRenderer class, which generates documentation resources compatible with the Model Context Protocol (MCP).

    "},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer-classes","title":"Classes","text":""},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer","title":"MCPRenderer","text":"

    Renderer that generates MCP-compatible documentation resources.

    This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

    "},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(project: Project, out_dir: Path) -> None\n

    Generate MCP documentation resources for a project.

    The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

    Parameters:

    Name Type Description Default project Project

    Documentation project model to render.

    required out_dir Path

    Directory where MCP resources will be written.

    required"},{"location":"docforge/renderers/mkdocs_renderer/","title":"Mkdocs Renderer","text":""},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer","title":"docforge.renderers.mkdocs_renderer","text":""},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer--summary","title":"Summary","text":"

    MkDocs renderer implementation.

    This module defines the MkDocsRenderer class, which generates Markdown documentation sources compatible with MkDocs Material and the mkdocstrings plugin.

    The renderer ensures a consistent documentation structure by:

    "},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer-classes","title":"Classes","text":""},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer","title":"MkDocsRenderer","text":"

    Renderer that produces Markdown documentation for MkDocs.

    Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

    "},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
    generate_readme(\n    project: Project,\n    docs_dir: Path,\n    module_is_source: bool | None = None,\n    readme_dir: Path | None = None,\n) -> None\n

    Generate a README.md file from the root module docstring.

    Notes

    Parameters:

    Name Type Description Default project Project

    Project model containing documentation metadata.

    required docs_dir Path

    Directory containing generated documentation sources.

    required module_is_source bool | None

    Whether the module is treated as the project source root.

    None readme_dir Path | None

    Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

    None"},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

    Generate Markdown documentation files for a project.

    This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

    Parameters:

    Name Type Description Default project Project

    Project model containing modules to document.

    required out_dir Path

    Directory where generated Markdown files will be written.

    required module_is_source bool | None

    If True, treat the specified module as the documentation root rather than nesting it inside a folder.

    None"},{"location":"docforge/servers/","title":"Servers","text":""},{"location":"docforge/servers/#docforge.servers","title":"docforge.servers","text":""},{"location":"docforge/servers/#docforge.servers--summary","title":"Summary","text":"

    Server layer for doc-forge.

    This module exposes server implementations used to provide live access to generated documentation resources. Currently, it includes the MCP documentation server.

    "},{"location":"docforge/servers/#docforge.servers-classes","title":"Classes","text":""},{"location":"docforge/servers/#docforge.servers.MCPServer","title":"MCPServer","text":"
    MCPServer(mcp_root: Path, name: str)\n

    MCP server for serving a pre-generated documentation bundle.

    The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.

    Attributes:

    Name Type Description mcp_root Path

    Directory containing the generated MCP documentation bundle.

    app FastMCP

    Underlying FastMCP application instance that registers resources and tools.

    Initialize the MCP server.

    Parameters:

    Name Type Description Default mcp_root Path

    Directory containing the generated MCP documentation bundle (for example index.json, nav.json, and modules/).

    required name str

    Identifier used for the MCP server instance.

    required"},{"location":"docforge/servers/#docforge.servers.MCPServer-functions","title":"Functions","text":""},{"location":"docforge/servers/#docforge.servers.MCPServer.run","title":"run","text":"
    run(\n    transport: Literal[\n        \"stdio\", \"sse\", \"streamable-http\"\n    ] = \"streamable-http\",\n) -> None\n

    Start the MCP server.

    Parameters:

    Name Type Description Default transport Literal['stdio', 'sse', 'streamable-http']

    Transport mechanism used by the MCP server. Supported options include stdio, sse, and streamable-http.

    'streamable-http'"},{"location":"docforge/servers/mcp_server/","title":"Mcp Server","text":""},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server","title":"docforge.servers.mcp_server","text":""},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server--summary","title":"Summary","text":"

    MCP server implementation.

    This module defines the MCPServer class, which serves pre-generated documentation bundles through the Model Context Protocol (MCP).

    Notes "},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server-classes","title":"Classes","text":""},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server.MCPServer","title":"MCPServer","text":"
    MCPServer(mcp_root: Path, name: str)\n

    MCP server for serving a pre-generated documentation bundle.

    The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.

    Attributes:

    Name Type Description mcp_root Path

    Directory containing the generated MCP documentation bundle.

    app FastMCP

    Underlying FastMCP application instance that registers resources and tools.

    Initialize the MCP server.

    Parameters:

    Name Type Description Default mcp_root Path

    Directory containing the generated MCP documentation bundle (for example index.json, nav.json, and modules/).

    required name str

    Identifier used for the MCP server instance.

    required"},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server.MCPServer-functions","title":"Functions","text":""},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server.MCPServer.run","title":"run","text":"
    run(\n    transport: Literal[\n        \"stdio\", \"sse\", \"streamable-http\"\n    ] = \"streamable-http\",\n) -> None\n

    Start the MCP server.

    Parameters:

    Name Type Description Default transport Literal['stdio', 'sse', 'streamable-http']

    Transport mechanism used by the MCP server. Supported options include stdio, sse, and streamable-http.

    'streamable-http'"},{"location":"loaders/","title":"Loaders","text":""},{"location":"loaders/#docforge.loaders","title":"docforge.loaders","text":""},{"location":"loaders/#docforge.loaders--summary","title":"Summary","text":"

    Loader layer for doc-forge.

    The docforge.loaders package is responsible for discovering Python modules and extracting documentation data using static analysis.

    "},{"location":"loaders/#docforge.loaders--overview","title":"Overview","text":"

    This layer converts Python source code into an intermediate documentation model used by doc-forge. It performs module discovery, introspection, and initial filtering before the data is passed to the core documentation models.

    Core capabilities include:

    "},{"location":"loaders/#docforge.loaders-classes","title":"Classes","text":""},{"location":"loaders/#docforge.loaders.GriffeLoader","title":"GriffeLoader","text":"
    GriffeLoader()\n

    Load Python modules using Griffe and convert them into doc-forge models.

    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:

    Name Type Description _loader GriffeLoader

    Internal Griffe loader with dedicated module and line collections.

    Initialize the Griffe-backed loader.

    Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

    "},{"location":"loaders/#docforge.loaders.GriffeLoader-functions","title":"Functions","text":""},{"location":"loaders/#docforge.loaders.GriffeLoader.load_module","title":"load_module","text":"
    load_module(path: str) -> Module\n

    Load and convert a single Python module.

    The module is introspected using Griffe and then transformed into a doc-forge Module model.

    Parameters:

    Name Type Description Default path str

    Dotted import path of the module.

    required

    Returns:

    Name Type Description Module Module

    A populated Module instance.

    Raises:

    Type Description 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\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
    "},{"location":"loaders/#docforge.loaders.GriffeLoader.load_project","title":"load_project","text":"
    load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

    Load multiple modules and assemble them into a Project model.

    Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

    Parameters:

    Name Type Description Default module_paths list[str]

    List of dotted module import paths to load.

    required project_name str | None

    Optional override for the project name. Defaults to the top-level name of the first module.

    None skip_import_errors bool | None

    If True, modules that fail to load will be skipped instead of raising an error.

    None

    Returns:

    Name Type Description Project Project

    A populated Project instance containing the loaded modules.

    Raises:

    Type Description ValueError

    If no module paths are provided.

    ImportError

    If a module fails to load and skip_import_errors is False.

    "},{"location":"loaders/#docforge.loaders-functions","title":"Functions","text":""},{"location":"loaders/#docforge.loaders.discover_module_paths","title":"discover_module_paths","text":"
    discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

    Discover Python modules within a package directory.

    The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

    Discovery rules:

    Parameters:

    Name Type Description Default module_name str

    Top-level package name to discover modules from.

    required project_root Path | None

    Root directory used to resolve module paths. If not provided, the current working directory is used.

    None

    Returns:

    Type Description list[str]

    list[str]: A sorted list of unique dotted module import paths.

    Raises:

    Type Description FileNotFoundError

    If the specified package directory does not exist.

    "},{"location":"loaders/griffe_loader/","title":"Griffe Loader","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader","title":"docforge.loaders.griffe_loader","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader--summary","title":"Summary","text":"

    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 "},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader-classes","title":"Classes","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader","title":"GriffeLoader","text":"
    GriffeLoader()\n

    Load Python modules using Griffe and convert them into doc-forge models.

    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:

    Name Type Description _loader GriffeLoader

    Internal Griffe loader with dedicated module and line collections.

    Initialize the Griffe-backed loader.

    Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

    "},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader-functions","title":"Functions","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_module","title":"load_module","text":"
    load_module(path: str) -> Module\n

    Load and convert a single Python module.

    The module is introspected using Griffe and then transformed into a doc-forge Module model.

    Parameters:

    Name Type Description Default path str

    Dotted import path of the module.

    required

    Returns:

    Name Type Description Module Module

    A populated Module instance.

    Raises:

    Type Description 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\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
    "},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_project","title":"load_project","text":"
    load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

    Load multiple modules and assemble them into a Project model.

    Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

    Parameters:

    Name Type Description Default module_paths list[str]

    List of dotted module import paths to load.

    required project_name str | None

    Optional override for the project name. Defaults to the top-level name of the first module.

    None skip_import_errors bool | None

    If True, modules that fail to load will be skipped instead of raising an error.

    None

    Returns:

    Name Type Description Project Project

    A populated Project instance containing the loaded modules.

    Raises:

    Type Description ValueError

    If no module paths are provided.

    ImportError

    If a module fails to load and skip_import_errors is False.

    "},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader-functions","title":"Functions","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.discover_module_paths","title":"discover_module_paths","text":"
    discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

    Discover Python modules within a package directory.

    The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

    Discovery rules:

    Parameters:

    Name Type Description Default module_name str

    Top-level package name to discover modules from.

    required project_root Path | None

    Root directory used to resolve module paths. If not provided, the current working directory is used.

    None

    Returns:

    Type Description list[str]

    list[str]: A sorted list of unique dotted module import paths.

    Raises:

    Type Description FileNotFoundError

    If the specified package directory does not exist.

    "},{"location":"models/","title":"Models","text":""},{"location":"models/#docforge.models","title":"docforge.models","text":""},{"location":"models/#docforge.models--summary","title":"Summary","text":"

    Model layer for doc-forge.

    The docforge.models package defines the core data structures used to represent Python source code as a structured documentation model.

    "},{"location":"models/#docforge.models--overview","title":"Overview","text":"

    The model layer forms the central intermediate representation used throughout doc-forge. Python modules and objects discovered during introspection are converted into a hierarchy of documentation models that can later be rendered into different documentation formats.

    Key components:

    These models are intentionally renderer-agnostic, allowing the same documentation structure to be transformed into multiple output formats (e.g., MkDocs, MCP, or other renderers).

    "},{"location":"models/#docforge.models-classes","title":"Classes","text":""},{"location":"models/#docforge.models.DocObject","title":"DocObject","text":"
    DocObject(\n    name: str,\n    kind: str,\n    path: str,\n    signature: str | None = None,\n    docstring: str | None = None,\n)\n

    Representation of a documented Python object.

    A DocObject models a single Python entity discovered during introspection. Objects may contain nested members, allowing the structure of modules, classes, and other containers to be represented recursively.

    Attributes:

    Name Type Description name str

    Local name of the object.

    kind str

    Type of object (for example class, function, method, or attribute).

    path str

    Fully qualified dotted path to the object.

    signature str | None

    Callable signature if the object represents a callable.

    docstring str | None

    Raw docstring text extracted from the source code.

    members dict[str, DocObject]

    Mapping of member names to child DocObject instances.

    Initialize a DocObject instance.

    Parameters:

    Name Type Description Default name str

    Local name of the object.

    required kind str

    Object type identifier (for example class or function).

    required path str

    Fully qualified dotted path of the object.

    required signature str | None

    Callable signature if applicable.

    None docstring str | None

    Documentation string associated with the object.

    None"},{"location":"models/#docforge.models.DocObject-functions","title":"Functions","text":""},{"location":"models/#docforge.models.DocObject.add_member","title":"add_member","text":"
    add_member(obj: DocObject) -> None\n

    Add a child documentation object.

    This is typically used when attaching methods to classes or nested objects to their parent containers.

    Parameters:

    Name Type Description Default obj DocObject

    Documentation object to add as a member.

    required"},{"location":"models/#docforge.models.DocObject.get_all_members","title":"get_all_members","text":"
    get_all_members() -> Iterable[DocObject]\n

    Return all child members of the object.

    Returns:

    Type Description Iterable[DocObject]

    Iterable[DocObject]: An iterable of DocObject instances representing nested members.

    "},{"location":"models/#docforge.models.DocObject.get_member","title":"get_member","text":"
    get_member(name: str) -> DocObject\n

    Retrieve a member object by name.

    Parameters:

    Name Type Description Default name str

    Name of the member to retrieve.

    required

    Returns:

    Name Type Description DocObject DocObject

    The corresponding DocObject instance.

    Raises:

    Type Description KeyError

    If the member does not exist.

    "},{"location":"models/#docforge.models.Module","title":"Module","text":"
    Module(path: str, docstring: str | None = None)\n

    Representation of a documented Python module or package.

    A Module stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.

    Attributes:

    Name Type Description path str

    Dotted import path of the module.

    docstring str | None

    Module-level documentation string, if present.

    members dict[str, DocObject]

    Mapping of object names to their corresponding DocObject representations.

    Initialize a Module instance.

    Parameters:

    Name Type Description Default path str

    Dotted import path identifying the module.

    required docstring str | None

    Module-level documentation text, if available.

    None"},{"location":"models/#docforge.models.Module-functions","title":"Functions","text":""},{"location":"models/#docforge.models.Module.add_object","title":"add_object","text":"
    add_object(obj: DocObject) -> None\n

    Add a documented object to the module.

    Parameters:

    Name Type Description Default obj DocObject

    Documentation object to register as a top-level member of the module.

    required"},{"location":"models/#docforge.models.Module.get_all_objects","title":"get_all_objects","text":"
    get_all_objects() -> Iterable[DocObject]\n

    Return all top-level documentation objects in the module.

    Returns:

    Type Description Iterable[DocObject]

    Iterable[DocObject]: An iterable of DocObject instances representing the module's public members.

    "},{"location":"models/#docforge.models.Module.get_object","title":"get_object","text":"
    get_object(name: str) -> DocObject\n

    Retrieve a documented object by name.

    Parameters:

    Name Type Description Default name str

    Name of the object to retrieve.

    required

    Returns:

    Name Type Description DocObject DocObject

    The corresponding DocObject instance.

    Raises:

    Type Description KeyError

    If no object with the given name exists.

    "},{"location":"models/#docforge.models.Project","title":"Project","text":"
    Project(name: str)\n

    Representation of a documentation project.

    A Project serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.

    Attributes:

    Name Type Description name str

    Name of the project.

    modules dict[str, Module]

    Mapping of module paths to Module instances.

    Initialize a Project instance.

    Parameters:

    Name Type Description Default name str

    Name used to identify the documentation project.

    required Example

    Create a project and register a module:

    ```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n
    "},{"location":"models/#docforge.models.Project-functions","title":"Functions","text":""},{"location":"models/#docforge.models.Project.add_module","title":"add_module","text":"
    add_module(module: Module) -> None\n

    Register a module in the project.

    Parameters:

    Name Type Description Default module Module

    Module instance to add to the project.

    required"},{"location":"models/#docforge.models.Project.get_all_modules","title":"get_all_modules","text":"
    get_all_modules() -> Iterable[Module]\n

    Return all modules contained in the project.

    Returns:

    Type Description Iterable[Module]

    Iterable[Module]: An iterable of Module instances.

    "},{"location":"models/#docforge.models.Project.get_module","title":"get_module","text":"
    get_module(path: str) -> Module\n

    Retrieve a module by its dotted path.

    Parameters:

    Name Type Description Default path str

    Fully qualified dotted module path (for example pkg.module).

    required

    Returns:

    Name Type Description Module Module

    The corresponding Module instance.

    Raises:

    Type Description KeyError

    If the module does not exist in the project.

    "},{"location":"models/#docforge.models.Project.get_module_list","title":"get_module_list","text":"
    get_module_list() -> list[str]\n

    Return the list of module import paths.

    Returns:

    Type Description list[str]

    list[str]: A list containing the dotted paths of all modules in the project.

    "},{"location":"models/module/","title":"Module","text":""},{"location":"models/module/#docforge.models.module","title":"docforge.models.module","text":""},{"location":"models/module/#docforge.models.module--summary","title":"Summary","text":"

    Documentation model representing a Python module or package.

    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 "},{"location":"models/module/#docforge.models.module-classes","title":"Classes","text":""},{"location":"models/module/#docforge.models.module.Module","title":"Module","text":"
    Module(path: str, docstring: str | None = None)\n

    Representation of a documented Python module or package.

    A Module stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.

    Attributes:

    Name Type Description path str

    Dotted import path of the module.

    docstring str | None

    Module-level documentation string, if present.

    members dict[str, DocObject]

    Mapping of object names to their corresponding DocObject representations.

    Initialize a Module instance.

    Parameters:

    Name Type Description Default path str

    Dotted import path identifying the module.

    required docstring str | None

    Module-level documentation text, if available.

    None"},{"location":"models/module/#docforge.models.module.Module-functions","title":"Functions","text":""},{"location":"models/module/#docforge.models.module.Module.add_object","title":"add_object","text":"
    add_object(obj: DocObject) -> None\n

    Add a documented object to the module.

    Parameters:

    Name Type Description Default obj DocObject

    Documentation object to register as a top-level member of the module.

    required"},{"location":"models/module/#docforge.models.module.Module.get_all_objects","title":"get_all_objects","text":"
    get_all_objects() -> Iterable[DocObject]\n

    Return all top-level documentation objects in the module.

    Returns:

    Type Description Iterable[DocObject]

    Iterable[DocObject]: An iterable of DocObject instances representing the module's public members.

    "},{"location":"models/module/#docforge.models.module.Module.get_object","title":"get_object","text":"
    get_object(name: str) -> DocObject\n

    Retrieve a documented object by name.

    Parameters:

    Name Type Description Default name str

    Name of the object to retrieve.

    required

    Returns:

    Name Type Description DocObject DocObject

    The corresponding DocObject instance.

    Raises:

    Type Description KeyError

    If no object with the given name exists.

    "},{"location":"models/object/","title":"Object","text":""},{"location":"models/object/#docforge.models.object","title":"docforge.models.object","text":""},{"location":"models/object/#docforge.models.object--summary","title":"Summary","text":"

    Documentation model representing individual Python objects.

    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 "},{"location":"models/object/#docforge.models.object-classes","title":"Classes","text":""},{"location":"models/object/#docforge.models.object.DocObject","title":"DocObject","text":"
    DocObject(\n    name: str,\n    kind: str,\n    path: str,\n    signature: str | None = None,\n    docstring: str | None = None,\n)\n

    Representation of a documented Python object.

    A DocObject models a single Python entity discovered during introspection. Objects may contain nested members, allowing the structure of modules, classes, and other containers to be represented recursively.

    Attributes:

    Name Type Description name str

    Local name of the object.

    kind str

    Type of object (for example class, function, method, or attribute).

    path str

    Fully qualified dotted path to the object.

    signature str | None

    Callable signature if the object represents a callable.

    docstring str | None

    Raw docstring text extracted from the source code.

    members dict[str, DocObject]

    Mapping of member names to child DocObject instances.

    Initialize a DocObject instance.

    Parameters:

    Name Type Description Default name str

    Local name of the object.

    required kind str

    Object type identifier (for example class or function).

    required path str

    Fully qualified dotted path of the object.

    required signature str | None

    Callable signature if applicable.

    None docstring str | None

    Documentation string associated with the object.

    None"},{"location":"models/object/#docforge.models.object.DocObject-functions","title":"Functions","text":""},{"location":"models/object/#docforge.models.object.DocObject.add_member","title":"add_member","text":"
    add_member(obj: DocObject) -> None\n

    Add a child documentation object.

    This is typically used when attaching methods to classes or nested objects to their parent containers.

    Parameters:

    Name Type Description Default obj DocObject

    Documentation object to add as a member.

    required"},{"location":"models/object/#docforge.models.object.DocObject.get_all_members","title":"get_all_members","text":"
    get_all_members() -> Iterable[DocObject]\n

    Return all child members of the object.

    Returns:

    Type Description Iterable[DocObject]

    Iterable[DocObject]: An iterable of DocObject instances representing nested members.

    "},{"location":"models/object/#docforge.models.object.DocObject.get_member","title":"get_member","text":"
    get_member(name: str) -> DocObject\n

    Retrieve a member object by name.

    Parameters:

    Name Type Description Default name str

    Name of the member to retrieve.

    required

    Returns:

    Name Type Description DocObject DocObject

    The corresponding DocObject instance.

    Raises:

    Type Description KeyError

    If the member does not exist.

    "},{"location":"models/project/","title":"Project","text":""},{"location":"models/project/#docforge.models.project","title":"docforge.models.project","text":""},{"location":"models/project/#docforge.models.project--summary","title":"Summary","text":"

    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 "},{"location":"models/project/#docforge.models.project-classes","title":"Classes","text":""},{"location":"models/project/#docforge.models.project.Project","title":"Project","text":"
    Project(name: str)\n

    Representation of a documentation project.

    A Project serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.

    Attributes:

    Name Type Description name str

    Name of the project.

    modules dict[str, Module]

    Mapping of module paths to Module instances.

    Initialize a Project instance.

    Parameters:

    Name Type Description Default name str

    Name used to identify the documentation project.

    required Example

    Create a project and register a module:

    ```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n
    "},{"location":"models/project/#docforge.models.project.Project-functions","title":"Functions","text":""},{"location":"models/project/#docforge.models.project.Project.add_module","title":"add_module","text":"
    add_module(module: Module) -> None\n

    Register a module in the project.

    Parameters:

    Name Type Description Default module Module

    Module instance to add to the project.

    required"},{"location":"models/project/#docforge.models.project.Project.get_all_modules","title":"get_all_modules","text":"
    get_all_modules() -> Iterable[Module]\n

    Return all modules contained in the project.

    Returns:

    Type Description Iterable[Module]

    Iterable[Module]: An iterable of Module instances.

    "},{"location":"models/project/#docforge.models.project.Project.get_module","title":"get_module","text":"
    get_module(path: str) -> Module\n

    Retrieve a module by its dotted path.

    Parameters:

    Name Type Description Default path str

    Fully qualified dotted module path (for example pkg.module).

    required

    Returns:

    Name Type Description Module Module

    The corresponding Module instance.

    Raises:

    Type Description KeyError

    If the module does not exist in the project.

    "},{"location":"models/project/#docforge.models.project.Project.get_module_list","title":"get_module_list","text":"
    get_module_list() -> list[str]\n

    Return the list of module import paths.

    Returns:

    Type Description list[str]

    list[str]: A list containing the dotted paths of all modules in the project.

    "},{"location":"nav/","title":"Nav","text":""},{"location":"nav/#docforge.nav","title":"docforge.nav","text":"

    Navigation layer for doc-forge.

    The docforge.nav package manages the relationship between the logical documentation structure defined by the user and the physical documentation files generated on disk.

    "},{"location":"nav/#docforge.nav--workflow","title":"Workflow","text":"
    1. Specification \u2013 Users define navigation intent in docforge.nav.yml.
    2. Resolution \u2013 resolve_nav expands patterns and matches them against generated Markdown files.
    3. Emission \u2013 MkDocsNavEmitter converts the resolved structure into the YAML navigation format required by mkdocs.yml.

    This layer separates documentation organization from the underlying source code layout, enabling flexible grouping, ordering, and navigation structures independent of module hierarchy.

    "},{"location":"nav/#docforge.nav-classes","title":"Classes","text":""},{"location":"nav/#docforge.nav.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"

    Emit MkDocs navigation structures from resolved navigation data.

    The emitter transforms a ResolvedNav object into the YAML-compatible list structure expected by the MkDocs nav configuration field.

    "},{"location":"nav/#docforge.nav.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.MkDocsNavEmitter.emit","title":"emit","text":"
    emit(nav: ResolvedNav) -> list[dict[str, Any]]\n

    Generate a navigation structure for mkdocs.yml.

    Parameters:

    Name Type Description Default nav ResolvedNav

    Resolved navigation data describing documentation groups and their associated Markdown files.

    required

    Returns:

    Type Description list[dict[str, Any]]

    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.

    "},{"location":"nav/#docforge.nav.NavSpec","title":"NavSpec","text":"
    NavSpec(\n    home: str | None,\n    groups: dict[str, list[str]],\n    icon: dict[str, str] | None = None,\n)\n

    Parsed representation of a navigation specification.

    A NavSpec describes the intended documentation navigation layout before it is resolved against the filesystem.

    Attributes:

    Name Type Description home str | None

    Relative path to the documentation home page (for example index.md).

    groups dict[str, list[str]]

    Mapping of navigation group titles to lists of file patterns or glob expressions.

    icon

    Optional mapping of theme icon entries (for example {\"logo\": \"material/code-tags\"}) injected into the MkDocs theme as theme.icon.

    Initialize a NavSpec instance.

    Parameters:

    Name Type Description Default home str | None

    Relative path to the home document.

    required groups dict[str, list[str]]

    Mapping of group names to lists of path patterns (glob expressions).

    required icon dict[str, str] | None

    Optional mapping of theme icon entries applied to the generated MkDocs configuration.

    None"},{"location":"nav/#docforge.nav.NavSpec-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.NavSpec.all_patterns","title":"all_patterns","text":"
    all_patterns() -> list[str]\n

    Return all path patterns referenced by the specification.

    Returns:

    Type Description list[str]

    list[str]: A list containing the home document (if defined) and all group pattern entries.

    "},{"location":"nav/#docforge.nav.NavSpec.load","title":"load classmethod","text":"
    load(path: Path) -> NavSpec\n

    Load a navigation specification from a YAML file.

    Parameters:

    Name Type Description Default path Path

    Filesystem path to the navigation specification file.

    required

    Returns:

    Name Type Description NavSpec NavSpec

    A NavSpec instance representing the parsed configuration.

    Raises:

    Type Description FileNotFoundError

    If the specified file does not exist.

    ValueError

    If the file contents are not a valid navigation specification.

    "},{"location":"nav/#docforge.nav.ResolvedNav","title":"ResolvedNav","text":"
    ResolvedNav(\n    home: str | None,\n    groups: dict[str, list[Path]],\n    docs_root: Path | None = None,\n)\n

    Resolved navigation structure.

    A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.

    Attributes:

    Name Type Description home str | None

    Relative path to the documentation home page.

    groups dict[str, list[Path]]

    Mapping of navigation group titles to lists of resolved documentation file paths.

    Initialize a ResolvedNav instance.

    Parameters:

    Name Type Description Default home str | None

    Relative path to the home page within the documentation root.

    required groups dict[str, list[Path]]

    Mapping of group titles to resolved documentation file paths.

    required docs_root Path | None

    Root directory of the documentation source files.

    None"},{"location":"nav/#docforge.nav.ResolvedNav-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.ResolvedNav.all_files","title":"all_files","text":"
    all_files() -> Iterable[Path]\n

    Iterate over all files referenced by the navigation structure.

    Yields:

    Name Type Description Path Iterable[Path]

    A documentation file referenced by the navigation, including the home page when defined.

    Raises:

    Type Description RuntimeError

    If the home page is defined but the documentation root is not available for resolution.

    "},{"location":"nav/#docforge.nav-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.build_wiki_nav","title":"build_wiki_nav","text":"
    build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n

    Derive an MkDocs navigation block from a wiki directory.

    Returned paths are relative to the parent of wiki_dir and carry the wiki directory name as their leading component (for example wiki/01_overview.md when the wiki lives at docs/wiki). This makes the result directly usable in an MkDocs nav block with

    Parameters:

    Name Type Description Default wiki_dir Path

    Path to the hand-written wiki directory, for example docs/wiki.

    required

    Returns:

    Type Description 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.

    Raises:

    Type Description FileNotFoundError

    If the wiki directory does not exist.

    "},{"location":"nav/#docforge.nav.load_nav_spec","title":"load_nav_spec","text":"
    load_nav_spec(path: Path) -> NavSpec\n

    Load a navigation specification file.

    This helper function reads a YAML navigation file and constructs a corresponding NavSpec instance.

    Parameters:

    Name Type Description Default path Path

    Path to the navigation specification file.

    required

    Returns:

    Name Type Description NavSpec NavSpec

    A NavSpec instance representing the parsed specification.

    Raises:

    Type Description FileNotFoundError

    If the specification file does not exist.

    ValueError

    If the YAML structure is invalid.

    "},{"location":"nav/#docforge.nav.resolve_nav","title":"resolve_nav","text":"
    resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n

    Resolve a navigation specification against the filesystem.

    The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.

    Parameters:

    Name Type Description Default spec NavSpec

    Navigation specification describing documentation layout.

    required docs_root Path

    Root directory containing documentation Markdown files.

    required

    Returns:

    Name Type Description ResolvedNav ResolvedNav

    A ResolvedNav instance containing validated navigation paths.

    Raises:

    Type Description FileNotFoundError

    If the documentation root does not exist or a navigation pattern does not match any files.

    "},{"location":"nav/mkdocs/","title":"Mkdocs","text":""},{"location":"nav/mkdocs/#docforge.nav.mkdocs","title":"docforge.nav.mkdocs","text":"

    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 "},{"location":"nav/mkdocs/#docforge.nav.mkdocs-classes","title":"Classes","text":""},{"location":"nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"

    Emit MkDocs navigation structures from resolved navigation data.

    The emitter transforms a ResolvedNav object into the YAML-compatible list structure expected by the MkDocs nav configuration field.

    "},{"location":"nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter.emit","title":"emit","text":"
    emit(nav: ResolvedNav) -> list[dict[str, Any]]\n

    Generate a navigation structure for mkdocs.yml.

    Parameters:

    Name Type Description Default nav ResolvedNav

    Resolved navigation data describing documentation groups and their associated Markdown files.

    required

    Returns:

    Type Description list[dict[str, Any]]

    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.

    "},{"location":"nav/resolver/","title":"Resolver","text":""},{"location":"nav/resolver/#docforge.nav.resolver","title":"docforge.nav.resolver","text":"

    Navigation resolution utilities.

    This module resolves a NavSpec against the filesystem by expanding glob patterns and validating that referenced documentation files exist.

    Notes "},{"location":"nav/resolver/#docforge.nav.resolver-classes","title":"Classes","text":""},{"location":"nav/resolver/#docforge.nav.resolver.ResolvedNav","title":"ResolvedNav","text":"
    ResolvedNav(\n    home: str | None,\n    groups: dict[str, list[Path]],\n    docs_root: Path | None = None,\n)\n

    Resolved navigation structure.

    A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.

    Attributes:

    Name Type Description home str | None

    Relative path to the documentation home page.

    groups dict[str, list[Path]]

    Mapping of navigation group titles to lists of resolved documentation file paths.

    Initialize a ResolvedNav instance.

    Parameters:

    Name Type Description Default home str | None

    Relative path to the home page within the documentation root.

    required groups dict[str, list[Path]]

    Mapping of group titles to resolved documentation file paths.

    required docs_root Path | None

    Root directory of the documentation source files.

    None"},{"location":"nav/resolver/#docforge.nav.resolver.ResolvedNav-functions","title":"Functions","text":""},{"location":"nav/resolver/#docforge.nav.resolver.ResolvedNav.all_files","title":"all_files","text":"
    all_files() -> Iterable[Path]\n

    Iterate over all files referenced by the navigation structure.

    Yields:

    Name Type Description Path Iterable[Path]

    A documentation file referenced by the navigation, including the home page when defined.

    Raises:

    Type Description RuntimeError

    If the home page is defined but the documentation root is not available for resolution.

    "},{"location":"nav/resolver/#docforge.nav.resolver-functions","title":"Functions","text":""},{"location":"nav/resolver/#docforge.nav.resolver.resolve_nav","title":"resolve_nav","text":"
    resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n

    Resolve a navigation specification against the filesystem.

    The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.

    Parameters:

    Name Type Description Default spec NavSpec

    Navigation specification describing documentation layout.

    required docs_root Path

    Root directory containing documentation Markdown files.

    required

    Returns:

    Name Type Description ResolvedNav ResolvedNav

    A ResolvedNav instance containing validated navigation paths.

    Raises:

    Type Description FileNotFoundError

    If the documentation root does not exist or a navigation pattern does not match any files.

    "},{"location":"nav/spec/","title":"Spec","text":""},{"location":"nav/spec/#docforge.nav.spec","title":"docforge.nav.spec","text":"

    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 "},{"location":"nav/spec/#docforge.nav.spec-classes","title":"Classes","text":""},{"location":"nav/spec/#docforge.nav.spec.NavSpec","title":"NavSpec","text":"
    NavSpec(\n    home: str | None,\n    groups: dict[str, list[str]],\n    icon: dict[str, str] | None = None,\n)\n

    Parsed representation of a navigation specification.

    A NavSpec describes the intended documentation navigation layout before it is resolved against the filesystem.

    Attributes:

    Name Type Description home str | None

    Relative path to the documentation home page (for example index.md).

    groups dict[str, list[str]]

    Mapping of navigation group titles to lists of file patterns or glob expressions.

    icon

    Optional mapping of theme icon entries (for example {\"logo\": \"material/code-tags\"}) injected into the MkDocs theme as theme.icon.

    Initialize a NavSpec instance.

    Parameters:

    Name Type Description Default home str | None

    Relative path to the home document.

    required groups dict[str, list[str]]

    Mapping of group names to lists of path patterns (glob expressions).

    required icon dict[str, str] | None

    Optional mapping of theme icon entries applied to the generated MkDocs configuration.

    None"},{"location":"nav/spec/#docforge.nav.spec.NavSpec-functions","title":"Functions","text":""},{"location":"nav/spec/#docforge.nav.spec.NavSpec.all_patterns","title":"all_patterns","text":"
    all_patterns() -> list[str]\n

    Return all path patterns referenced by the specification.

    Returns:

    Type Description list[str]

    list[str]: A list containing the home document (if defined) and all group pattern entries.

    "},{"location":"nav/spec/#docforge.nav.spec.NavSpec.load","title":"load classmethod","text":"
    load(path: Path) -> NavSpec\n

    Load a navigation specification from a YAML file.

    Parameters:

    Name Type Description Default path Path

    Filesystem path to the navigation specification file.

    required

    Returns:

    Name Type Description NavSpec NavSpec

    A NavSpec instance representing the parsed configuration.

    Raises:

    Type Description FileNotFoundError

    If the specified file does not exist.

    ValueError

    If the file contents are not a valid navigation specification.

    "},{"location":"nav/spec/#docforge.nav.spec-functions","title":"Functions","text":""},{"location":"nav/spec/#docforge.nav.spec.load_nav_spec","title":"load_nav_spec","text":"
    load_nav_spec(path: Path) -> NavSpec\n

    Load a navigation specification file.

    This helper function reads a YAML navigation file and constructs a corresponding NavSpec instance.

    Parameters:

    Name Type Description Default path Path

    Path to the navigation specification file.

    required

    Returns:

    Name Type Description NavSpec NavSpec

    A NavSpec instance representing the parsed specification.

    Raises:

    Type Description FileNotFoundError

    If the specification file does not exist.

    ValueError

    If the YAML structure is invalid.

    "},{"location":"nav/wiki/","title":"Wiki","text":""},{"location":"nav/wiki/#docforge.nav.wiki","title":"docforge.nav.wiki","text":""},{"location":"nav/wiki/#docforge.nav.wiki--summary","title":"Summary","text":"

    Wiki navigation derivation.

    This module provides build_wiki_nav, which derives an MkDocs-ready navigation block from the file structure of a hand-written wiki directory (typically docs/wiki). wiki content is authored by hand and is never modified by doc-forge; only the navigation layout is inferred.

    "},{"location":"nav/wiki/#docforge.nav.wiki--notes","title":"Notes","text":""},{"location":"nav/wiki/#docforge.nav.wiki-functions","title":"Functions","text":""},{"location":"nav/wiki/#docforge.nav.wiki.build_wiki_nav","title":"build_wiki_nav","text":"
    build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n

    Derive an MkDocs navigation block from a wiki directory.

    Returned paths are relative to the parent of wiki_dir and carry the wiki directory name as their leading component (for example wiki/01_overview.md when the wiki lives at docs/wiki). This makes the result directly usable in an MkDocs nav block with

    Parameters:

    Name Type Description Default wiki_dir Path

    Path to the hand-written wiki directory, for example docs/wiki.

    required

    Returns:

    Type Description 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.

    Raises:

    Type Description FileNotFoundError

    If the wiki directory does not exist.

    "},{"location":"renderers/","title":"Renderers","text":""},{"location":"renderers/#docforge.renderers","title":"docforge.renderers","text":""},{"location":"renderers/#docforge.renderers--summary","title":"Summary","text":"

    Renderers layer for doc-forge.

    The docforge.renderers package transforms the internal documentation models into files formatted for specific documentation systems.

    "},{"location":"renderers/#docforge.renderers--overview","title":"Overview","text":"

    Renderers consume the doc-forge project model and generate output suitable for documentation tools or machine interfaces.

    Current implementations:

    "},{"location":"renderers/#docforge.renderers--extending","title":"Extending","text":"

    New renderers can be added by implementing the DocRenderer protocol defined in docforge.renderers.base.

    "},{"location":"renderers/#docforge.renderers-classes","title":"Classes","text":""},{"location":"renderers/#docforge.renderers.MCPRenderer","title":"MCPRenderer","text":"

    Renderer that generates MCP-compatible documentation resources.

    This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

    "},{"location":"renderers/#docforge.renderers.MCPRenderer-functions","title":"Functions","text":""},{"location":"renderers/#docforge.renderers.MCPRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(project: Project, out_dir: Path) -> None\n

    Generate MCP documentation resources for a project.

    The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

    Parameters:

    Name Type Description Default project Project

    Documentation project model to render.

    required out_dir Path

    Directory where MCP resources will be written.

    required"},{"location":"renderers/#docforge.renderers.MkDocsRenderer","title":"MkDocsRenderer","text":"

    Renderer that produces Markdown documentation for MkDocs.

    Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

    "},{"location":"renderers/#docforge.renderers.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"renderers/#docforge.renderers.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
    generate_readme(\n    project: Project,\n    docs_dir: Path,\n    module_is_source: bool | None = None,\n    readme_dir: Path | None = None,\n) -> None\n

    Generate a README.md file from the root module docstring.

    Notes

    Parameters:

    Name Type Description Default project Project

    Project model containing documentation metadata.

    required docs_dir Path

    Directory containing generated documentation sources.

    required module_is_source bool | None

    Whether the module is treated as the project source root.

    None readme_dir Path | None

    Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

    None"},{"location":"renderers/#docforge.renderers.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

    Generate Markdown documentation files for a project.

    This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

    Parameters:

    Name Type Description Default project Project

    Project model containing modules to document.

    required out_dir Path

    Directory where generated Markdown files will be written.

    required module_is_source bool | None

    If True, treat the specified module as the documentation root rather than nesting it inside a folder.

    None"},{"location":"renderers/base/","title":"Base","text":""},{"location":"renderers/base/#docforge.renderers.base","title":"docforge.renderers.base","text":""},{"location":"renderers/base/#docforge.renderers.base--summary","title":"Summary","text":"

    Renderer base interfaces and configuration models.

    This module defines the base protocol and configuration container used by doc-forge renderers. Concrete renderer implementations should implement the DocRenderer protocol.

    "},{"location":"renderers/base/#docforge.renderers.base-classes","title":"Classes","text":""},{"location":"renderers/base/#docforge.renderers.base.DocRenderer","title":"DocRenderer","text":"

    Bases: Protocol

    Protocol defining the interface for documentation renderers.

    Implementations of this protocol are responsible for transforming a Project model into renderer-specific documentation sources.

    "},{"location":"renderers/base/#docforge.renderers.base.DocRenderer-functions","title":"Functions","text":""},{"location":"renderers/base/#docforge.renderers.base.DocRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(project: Project, out_dir: Path) -> None\n

    Generate renderer-specific documentation sources.

    Parameters:

    Name Type Description Default project Project

    Project model containing modules and documentation objects.

    required out_dir Path

    Directory where generated documentation sources should be written.

    required"},{"location":"renderers/base/#docforge.renderers.base.RendererConfig","title":"RendererConfig","text":"
    RendererConfig(out_dir: Path, project: Project)\n

    Configuration container for documentation renderers.

    A RendererConfig instance groups together the project model and the output directory used during rendering.

    Attributes:

    Name Type Description out_dir Path

    Directory where generated documentation files will be written.

    project Project

    Documentation project model to be rendered.

    Initialize a RendererConfig instance.

    Parameters:

    Name Type Description Default out_dir Path

    Target directory where documentation files should be written.

    required project Project

    Introspected project model to render.

    required"},{"location":"renderers/base/#docforge.renderers.base.RendererConfig-functions","title":"Functions","text":""},{"location":"renderers/mcp_renderer/","title":"Mcp Renderer","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer","title":"docforge.renderers.mcp_renderer","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer--summary","title":"Summary","text":"

    MCP renderer implementation.

    This module defines the MCPRenderer class, which generates documentation resources compatible with the Model Context Protocol (MCP).

    "},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer-classes","title":"Classes","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer","title":"MCPRenderer","text":"

    Renderer that generates MCP-compatible documentation resources.

    This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

    "},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer-functions","title":"Functions","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(project: Project, out_dir: Path) -> None\n

    Generate MCP documentation resources for a project.

    The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

    Parameters:

    Name Type Description Default project Project

    Documentation project model to render.

    required out_dir Path

    Directory where MCP resources will be written.

    required"},{"location":"renderers/mkdocs_renderer/","title":"Mkdocs Renderer","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer","title":"docforge.renderers.mkdocs_renderer","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer--summary","title":"Summary","text":"

    MkDocs renderer implementation.

    This module defines the MkDocsRenderer class, which generates Markdown documentation sources compatible with MkDocs Material and the mkdocstrings plugin.

    The renderer ensures a consistent documentation structure by:

    "},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer-classes","title":"Classes","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer","title":"MkDocsRenderer","text":"

    Renderer that produces Markdown documentation for MkDocs.

    Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

    "},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
    generate_readme(\n    project: Project,\n    docs_dir: Path,\n    module_is_source: bool | None = None,\n    readme_dir: Path | None = None,\n) -> None\n

    Generate a README.md file from the root module docstring.

    Notes

    Parameters:

    Name Type Description Default project Project

    Project model containing documentation metadata.

    required docs_dir Path

    Directory containing generated documentation sources.

    required module_is_source bool | None

    Whether the module is treated as the project source root.

    None readme_dir Path | None

    Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

    None"},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

    Generate Markdown documentation files for a project.

    This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

    Parameters:

    Name Type Description Default project Project

    Project model containing modules to document.

    required out_dir Path

    Directory where generated Markdown files will be written.

    required module_is_source bool | None

    If True, treat the specified module as the documentation root rather than nesting it inside a folder.

    None"},{"location":"servers/","title":"Servers","text":""},{"location":"servers/#docforge.servers","title":"docforge.servers","text":""},{"location":"servers/#docforge.servers--summary","title":"Summary","text":"

    Server layer for doc-forge.

    This module exposes server implementations used to provide live access to generated documentation resources. Currently, it includes the MCP documentation server.

    "},{"location":"servers/#docforge.servers-classes","title":"Classes","text":""},{"location":"servers/#docforge.servers.MCPServer","title":"MCPServer","text":"
    MCPServer(mcp_root: Path, name: str)\n

    MCP server for serving a pre-generated documentation bundle.

    The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.

    Attributes:

    Name Type Description mcp_root Path

    Directory containing the generated MCP documentation bundle.

    app FastMCP

    Underlying FastMCP application instance that registers resources and tools.

    Initialize the MCP server.

    Parameters:

    Name Type Description Default mcp_root Path

    Directory containing the generated MCP documentation bundle (for example index.json, nav.json, and modules/).

    required name str

    Identifier used for the MCP server instance.

    required"},{"location":"servers/#docforge.servers.MCPServer-functions","title":"Functions","text":""},{"location":"servers/#docforge.servers.MCPServer.run","title":"run","text":"
    run(\n    transport: Literal[\n        \"stdio\", \"sse\", \"streamable-http\"\n    ] = \"streamable-http\",\n) -> None\n

    Start the MCP server.

    Parameters:

    Name Type Description Default transport Literal['stdio', 'sse', 'streamable-http']

    Transport mechanism used by the MCP server. Supported options include stdio, sse, and streamable-http.

    'streamable-http'"},{"location":"servers/mcp_server/","title":"Mcp Server","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server","title":"docforge.servers.mcp_server","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server--summary","title":"Summary","text":"

    MCP server implementation.

    This module defines the MCPServer class, which serves pre-generated documentation bundles through the Model Context Protocol (MCP).

    Notes "},{"location":"servers/mcp_server/#docforge.servers.mcp_server-classes","title":"Classes","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server.MCPServer","title":"MCPServer","text":"
    MCPServer(mcp_root: Path, name: str)\n

    MCP server for serving a pre-generated documentation bundle.

    The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.

    Attributes:

    Name Type Description mcp_root Path

    Directory containing the generated MCP documentation bundle.

    app FastMCP

    Underlying FastMCP application instance that registers resources and tools.

    Initialize the MCP server.

    Parameters:

    Name Type Description Default mcp_root Path

    Directory containing the generated MCP documentation bundle (for example index.json, nav.json, and modules/).

    required name str

    Identifier used for the MCP server instance.

    required"},{"location":"servers/mcp_server/#docforge.servers.mcp_server.MCPServer-functions","title":"Functions","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server.MCPServer.run","title":"run","text":"
    run(\n    transport: Literal[\n        \"stdio\", \"sse\", \"streamable-http\"\n    ] = \"streamable-http\",\n) -> None\n

    Start the MCP server.

    Parameters:

    Name Type Description Default transport Literal['stdio', 'sse', 'streamable-http']

    Transport mechanism used by the MCP server. Supported options include stdio, sse, and streamable-http.

    'streamable-http'"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"docforge","text":""},{"location":"#docforge","title":"docforge","text":""},{"location":"#docforge--summary","title":"Summary","text":"

    Renderer-agnostic Python documentation compiler that converts Python docstrings into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).

    doc-forge statically analyzes source code, builds a semantic model of modules, classes, functions, and attributes, and renders that model into documentation outputs without executing user code.

    "},{"location":"#docforge--installation","title":"Installation","text":"

    Install using pip:

    pip install doc-forge\n
    "},{"location":"#docforge--cli-usage","title":"CLI usage","text":"

    Each site kind (lib, api, wiki) is built independently into site/{kind}.

    "},{"location":"#docforge--build-the-library-reference-from-a-python-package","title":"Build the library reference from a Python package:","text":"
    doc-forge build --mkdocs --module my_package\n
    "},{"location":"#docforge--build-the-api-reference-from-an-openapi-spec","title":"Build the API reference from an OpenAPI spec:","text":"
    doc-forge build --api --openapi-spec spec.json\n
    "},{"location":"#docforge--build-the-hand-written-wiki","title":"Build the hand-written wiki:","text":"
    doc-forge build --wiki --site-name my_package\n
    "},{"location":"#docforge--generate-mcp-json-documentation","title":"Generate MCP JSON documentation:","text":"
    doc-forge build --mcp --module my_package\n
    "},{"location":"#docforge--build-several-kinds-in-one-pass","title":"Build several kinds in one pass:","text":"
    doc-forge build --mcp --mkdocs --wiki --module my_package\n

    Each enabled kind gets its own MkDocs config (docs/mkdocs.{lib,api,wiki}.yml) and its own site under site/.

    "},{"location":"#docforge--serve-a-site-locally","title":"Serve a site locally:","text":"
    doc-forge serve --wiki        # preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n
    "},{"location":"#docforge--serve-mcp-locally","title":"Serve MCP locally:","text":"
    doc-forge serve --mcp --module my_package\n
    "},{"location":"#docforge--core-concepts","title":"Core concepts","text":""},{"location":"#docforge--loader","title":"Loader","text":"

    Extracts symbols, signatures, and docstrings using static analysis.

    "},{"location":"#docforge--semantic-model","title":"Semantic model","text":"

    Structured, renderer-agnostic representation of the API.

    "},{"location":"#docforge--renderer","title":"Renderer","text":"

    Converts the semantic model into output formats such as MkDocs or MCP JSON.

    "},{"location":"#docforge--symbol","title":"Symbol","text":"

    Any documentable object

    "},{"location":"#docforge--architecture","title":"Architecture","text":"

    doc-forge follows a compiler architecture:

    "},{"location":"#docforge--front-end","title":"Front-end:","text":"

    Static analysis of modules, classes, functions, type hints, and docstrings.

    "},{"location":"#docforge--middle-end","title":"Middle-end:","text":"

    Builds a semantic model describing symbols and relationships.

    "},{"location":"#docforge--back-end","title":"Back-end:","text":"

    Renders documentation using interchangeable renderers.

    This architecture ensures deterministic documentation generation.

    "},{"location":"#docforge--rendering-pipeline","title":"Rendering pipeline","text":"

    Typical flow:

    Python package\n    |\nLoader (static analysis)\n    |\nSemantic model\n    |\nRenderer\n    |\nMkDocs site or MCP JSON\n
    "},{"location":"#docforge--google-styled-doc-forge-convention-gsdfc","title":"Google-Styled Doc-Forge Convention (GSDFC)","text":"

    GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.

    "},{"location":"#docforge--general-rules","title":"General rules","text":""},{"location":"#docforge--notes-subsection-grouping","title":"Notes subsection grouping","text":"

    Group related information using labeled subsections.

    Example:

    Notes:\n    **Guarantees:**\n\n        - deterministic behavior\n\n    **Lifecycle:**\n\n        - created during initialization\n        - reused across executions\n\n    **Thread safety:**\n\n        - safe for concurrent reads\n
    "},{"location":"#docforge--example-formatting","title":"Example formatting","text":" Example

    Single example:

    Example:\n\n    ```python\n    foo = Foo(\"example\")\n    process(foo, multiplier=2)\n    ```\n

    Multiple examples:

    Example:\n    Create foo:\n\n        ```python\n        foo = Foo(\"example\")\n        ```\n\n    Run engine:\n\n        ```python\n        engine = BarEngine([foo])\n        engine.run()\n        ```\n

    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.

    "},{"location":"#docforge--separator-rules","title":"Separator rules","text":"

    Use horizontal separators only at docstring root level to separate sections:

    ---\n

    Allowed locations:

    Do not use separators inside code sections.

    "},{"location":"#docforge--package-docstrings","title":"Package docstrings","text":"

    Package docstrings act as the documentation home page.

    Recommended sections:

    # Summary\n# Installation\n# Quick start\n# CLI usage\n# Core concepts\n# Architecture\n# Rendering pipeline\n# Examples\n# Notes\n
    Example

    Package Doc String:

    '''\n# Summary\n\nFoo-bar processing framework.\n\nProvides tools for defining Foo objects and executing Bar pipelines.\n\n---\n\n# Installation\n\n```bash\npip install foo-bar\n```\n\n---\n\n# Quick start\n\n```python\nfrom foobar import Foo, BarEngine\n\nfoo = Foo(\"example\")\nengine = BarEngine([foo])\n\nresult = engine.run()\n```\n\n---\n'''\n
    "},{"location":"#docforge--module-docstrings","title":"Module docstrings","text":"

    Module docstrings describe a subsystem.

    Recommended sections:

    # Summary\n# Examples\n# Notes\n
    Example

    Module Doc String:

    '''\n# Summary\n\nFoo execution subsystem.\n\nProvides utilities for executing Foo objects through Bar stages.\n\n---\n\nExample:\n\n    ```python\n    from foobar.engine import BarEngine\n    from foobar.foo import Foo\n\n    foo = Foo(\"example\")\n\n    engine = BarEngine([foo])\n    engine.run()\n    ```\n\n---\n'''\n
    "},{"location":"#docforge--class-docstrings","title":"Class docstrings","text":"

    Class docstrings define object responsibility, lifecycle, and attributes.

    Recommended sections:

    Attributes:\nNotes:\nExample:\nRaises:\n
    Example

    Simple Foo:

    class Foo:\n    '''\n    Represents a unit of work.\n\n    Attributes:\n        name (str):\n            Identifier of the foo instance.\n\n        value (int):\n            Numeric value associated with foo.\n\n    Notes:\n        Guarantees:\n\n            - instances are immutable after creation\n\n        Lifecycle:\n\n            - create instance\n            - pass to processing engine\n\n    Example:\n        Create and inspect a Foo:\n\n            ```python\n            foo = Foo(\"example\", value=42)\n            print(foo.name)\n            ```\n    '''\n

    Complex Bar:

    class BarEngine:\n    '''\n    Executes Foo objects through Bar stages.\n\n    Attributes:\n        foos (tuple[Foo, ...]):\n            Foo instances managed by the engine.\n\n    Notes:\n        Guarantees:\n\n            - deterministic execution order\n\n    Example:\n        Run engine:\n\n            ```python\n            foo1 = Foo(\"a\")\n            foo2 = Foo(\"b\")\n\n            engine = BarEngine([foo1, foo2])\n            engine.run()\n            ```\n    '''\n
    "},{"location":"#docforge--function-and-method-docstrings","title":"Function and method docstrings","text":"

    Function docstrings define API contracts.

    Recommended sections:

    Args:\nReturns:\nRaises:\nYields:\nNotes:\nExample:\n
    Example

    Simple process method:

    def process(foo: Foo, multiplier: int) -> int:\n    '''\n    Process a Foo instance.\n\n    Args:\n        foo (Foo):\n            Foo instance to process.\n\n        multiplier (int):\n            Value used to scale foo.\n\n    Returns:\n        int:\n            Processed result.\n\n    Raises:\n        ValueError:\n            If multiplier is negative.\n\n    Notes:\n        Guarantees:\n\n            - foo is not modified\n\n    Example:\n        Process foo:\n\n            ```python\n            foo = Foo(\"example\", value=10)\n\n            result = process(foo, multiplier=2)\n            print(result)\n            ```\n    '''\n

    Multiple Examples:

    def combine(foo_a: Foo, foo_b: Foo) -> Foo:\n    '''\n    Combine two Foo instances.\n\n    Args:\n        foo_a (Foo):\n            First foo.\n\n        foo_b (Foo):\n            Second foo.\n\n    Returns:\n        Foo:\n            Combined foo.\n\n    Example:\n        Basic usage:\n\n            ```python\n            foo1 = Foo(\"a\")\n            foo2 = Foo(\"b\")\n\n            combined = combine(foo1, foo2)\n            ```\n\n        Pipeline usage:\n\n            ```python\n            engine = BarEngine([foo1, foo2])\n            engine.run()\n            ```\n    '''\n
    "},{"location":"#docforge--property-docstrings","title":"Property docstrings","text":"

    Properties must document return values.

    Example

    Property Doc String:

    ```python\n@property\ndef foos(self) -> tuple[Foo, ...]:\n    '''\n    Return contained Foo instances.\n\n    Returns:\n        tuple[Foo, ...]:\n            Stored foo objects.\n\n    Example:\n        ```python\n        container = FooContainer()\n\n        foos = container.foos\n        ```\n    '''\n```\n
    "},{"location":"#docforge--attribute-documentation","title":"Attribute documentation","text":"

    Document attributes in class docstrings using Attributes:.

    Example

    Attribute Doc String:

    ```python\n'''\nRepresents a processing stage.\n\nAttributes:\n    id (str):\n        Unique identifier.\n\n    enabled (bool):\n        Whether the stage is active.\n'''\n```\n
    "},{"location":"#docforge--type-parity-pyi-stubs-and-pytyped","title":"Type parity (.pyi stubs and py.typed)","text":"

    Documented APIs ship matching type information:

    "},{"location":"#docforge--parsing-guarantees","title":"Parsing guarantees","text":"

    GSDFC ensures doc-forge can deterministically extract:

    This enables:

    Notes "},{"location":"#docforge-classes","title":"Classes","text":""},{"location":"#docforge.GriffeLoader","title":"GriffeLoader","text":"
    GriffeLoader()\n

    Load Python modules using Griffe and convert them into doc-forge models.

    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:

    Name Type Description _loader GriffeLoader

    Internal Griffe loader with dedicated module and line collections.

    Initialize the Griffe-backed loader.

    Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

    "},{"location":"#docforge.GriffeLoader-functions","title":"Functions","text":""},{"location":"#docforge.GriffeLoader.load_module","title":"load_module","text":"
    load_module(path: str) -> Module\n

    Load and convert a single Python module.

    The module is introspected using Griffe and then transformed into a doc-forge Module model.

    Parameters:

    Name Type Description Default path str

    Dotted import path of the module.

    required

    Returns:

    Name Type Description Module Module

    A populated Module instance.

    Raises:

    Type Description 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\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
    "},{"location":"#docforge.GriffeLoader.load_project","title":"load_project","text":"
    load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

    Load multiple modules and assemble them into a Project model.

    Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

    Parameters:

    Name Type Description Default module_paths list[str]

    List of dotted module import paths to load.

    required project_name str | None

    Optional override for the project name. Defaults to the top-level name of the first module.

    None skip_import_errors bool | None

    If True, modules that fail to load will be skipped instead of raising an error.

    None

    Returns:

    Name Type Description Project Project

    A populated Project instance containing the loaded modules.

    Raises:

    Type Description ValueError

    If no module paths are provided.

    ImportError

    If a module fails to load and skip_import_errors is False.

    "},{"location":"#docforge.MCPRenderer","title":"MCPRenderer","text":"

    Renderer that generates MCP-compatible documentation resources.

    This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

    "},{"location":"#docforge.MCPRenderer-functions","title":"Functions","text":""},{"location":"#docforge.MCPRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(project: Project, out_dir: Path) -> None\n

    Generate MCP documentation resources for a project.

    The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

    Parameters:

    Name Type Description Default project Project

    Documentation project model to render.

    required out_dir Path

    Directory where MCP resources will be written.

    required"},{"location":"#docforge.MkDocsRenderer","title":"MkDocsRenderer","text":"

    Renderer that produces Markdown documentation for MkDocs.

    Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

    "},{"location":"#docforge.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"#docforge.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
    generate_readme(\n    project: Project,\n    docs_dir: Path,\n    module_is_source: bool | None = None,\n    readme_dir: Path | None = None,\n) -> None\n

    Generate a README.md file from the root module docstring.

    Notes

    Parameters:

    Name Type Description Default project Project

    Project model containing documentation metadata.

    required docs_dir Path

    Directory containing generated documentation sources.

    required module_is_source bool | None

    Whether the module is treated as the project source root.

    None readme_dir Path | None

    Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

    None"},{"location":"#docforge.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

    Generate Markdown documentation files for a project.

    This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

    Parameters:

    Name Type Description Default project Project

    Project model containing modules to document.

    required out_dir Path

    Directory where generated Markdown files will be written.

    required module_is_source bool | None

    If True, treat the specified module as the documentation root rather than nesting it inside a folder.

    None"},{"location":"#docforge-functions","title":"Functions","text":""},{"location":"#docforge.discover_module_paths","title":"discover_module_paths","text":"
    discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

    Discover Python modules within a package directory.

    The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

    Discovery rules:

    Parameters:

    Name Type Description Default module_name str

    Top-level package name to discover modules from.

    required project_root Path | None

    Root directory used to resolve module paths. If not provided, the current working directory is used.

    None

    Returns:

    Type Description list[str]

    list[str]: A sorted list of unique dotted module import paths.

    Raises:

    Type Description FileNotFoundError

    If the specified package directory does not exist.

    "},{"location":"cli/","title":"Cli","text":""},{"location":"cli/#docforge.cli","title":"docforge.cli","text":""},{"location":"cli/#docforge.cli--summary","title":"Summary","text":"

    Command line interface entry point for doc-forge.

    This module exposes the primary CLI entry function used by the doc-forge command. The actual command implementation resides in docforge.cli.main, while this module provides a stable import path for external tools and the package entry point configuration.

    The CLI is responsible for orchestrating documentation workflows such as generating renderer sources, building documentation sites, exporting machine-readable documentation bundles, and starting development or MCP servers.

    "},{"location":"cli/#docforge.cli--typical-usage","title":"Typical usage","text":"

    The CLI is normally invoked through the installed command:

    doc-forge <command> [options]\n

    Programmatic invocation is also possible:

    Example:

    ```python\nfrom docforge.cli import main\nmain()\n```\n
    "},{"location":"cli/api_utils/","title":"Api Utils","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils","title":"docforge.cli.api_utils","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils--summary","title":"Summary","text":"

    Utilities for building API documentation from an OpenAPI specification.

    "},{"location":"cli/api_utils/#docforge.cli.api_utils-classes","title":"Classes","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils.OpenAPIMetadata","title":"OpenAPIMetadata dataclass","text":"
    OpenAPIMetadata(\n    site_name: str,\n    site_description: str | None,\n    site_author: str | None,\n)\n

    Metadata derived from the info block of an OpenAPI specification.

    Attributes:

    Name Type Description site_name str

    Spec title, used as the MkDocs site name.

    site_description str | None

    Spec description, used as the site description.

    site_author str | None

    Contact name (fallback: contact email), used as the site author.

    "},{"location":"cli/api_utils/#docforge.cli.api_utils-functions","title":"Functions","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils.derive_metadata","title":"derive_metadata","text":"
    derive_metadata(spec: dict[Any, Any]) -> OpenAPIMetadata\n

    Derive MkDocs site metadata from an OpenAPI spec info block.

    Parameters:

    Name Type Description Default spec dict

    Parsed OpenAPI specification.

    required

    Returns:

    Name Type Description OpenAPIMetadata OpenAPIMetadata

    Site name, description, and author derived from the spec.

    "},{"location":"cli/api_utils/#docforge.cli.api_utils.generate_api_sources","title":"generate_api_sources","text":"
    generate_api_sources(\n    spec: dict[Any, Any], docs_dir: Path\n) -> None\n

    Generate swagger-enabled Markdown sources and the spec copy.

    The specification is written as openapi.json inside docs_dir and an index.md embedding the swagger UI is generated alongside it.

    Parameters:

    Name Type Description Default spec dict

    Parsed OpenAPI specification.

    required docs_dir Path

    Directory (for example docs/api) where the swagger sources are written.

    required"},{"location":"cli/api_utils/#docforge.cli.api_utils.load_openapi_spec","title":"load_openapi_spec","text":"
    load_openapi_spec(spec_path: Path) -> dict[Any, Any]\n

    Load and validate an OpenAPI specification from a JSON file.

    Parameters:

    Name Type Description Default spec_path Path

    Path to the OpenAPI JSON specification file.

    required

    Returns:

    Name Type Description dict dict[Any, Any]

    The parsed OpenAPI specification.

    Raises:

    Type Description ClickException

    If the file cannot be read or the info block is invalid.

    "},{"location":"cli/commands/","title":"Commands","text":""},{"location":"cli/commands/#docforge.cli.commands","title":"docforge.cli.commands","text":""},{"location":"cli/commands/#docforge.cli.commands--summary","title":"Summary","text":"

    Command definitions for the doc-forge CLI.

    Provides the CLI structure using Click, including build, serve, and tree commands.

    Notes "},{"location":"cli/commands/#docforge.cli.commands-classes","title":"Classes","text":""},{"location":"cli/commands/#docforge.cli.commands-functions","title":"Functions","text":""},{"location":"cli/commands/#docforge.cli.commands.build","title":"build","text":"
    build(\n    mcp: bool,\n    mkdocs: bool,\n    api: bool,\n    wiki: bool,\n    refresh: bool,\n    module_is_source: bool,\n    module: str | None,\n    openapi_spec: Path | None,\n    project_name: str | None,\n    site_name: str | None,\n    docs_dir: Path,\n    wiki_dir: Path,\n    nav_file: Path,\n    template: Path | None,\n    out_dir: Path,\n) -> None\n

    Build documentation artifacts.

    This command runs the full documentation pipeline: it loads Python modules, generates renderer-specific documentation sources, and optionally builds the final output.

    Depending on the selected options, the build can target:

    Each enabled site kind produces its own MkDocs configuration (docs/mkdocs.{kind}.yml) and its own build (site/{kind}).

    Notes

    Parameters:

    Name Type Description Default mcp bool

    Enable MCP documentation generation.

    required mkdocs bool

    Enable the lib MkDocs documentation generation.

    required api bool

    Enable API documentation generation from an OpenAPI spec.

    required wiki bool

    Build a hand-written wiki directory as its own MkDocs site.

    required refresh bool

    Regenerate docs/mkdocs.{kind}.yml from templates even when it already exists. By default, existing configs are used as-is.

    required module_is_source bool

    Treat the specified module directory as the project root.

    required module str | None

    Python module import path to document.

    required openapi_spec Path | None

    Path to the OpenAPI JSON specification used for API docs.

    required project_name str | None

    Optional override for the project name.

    required site_name str | None

    Display name for the lib and wiki MkDocs sites.

    required docs_dir Path

    Shared documentation root used for generated sources.

    required wiki_dir Path

    Directory containing hand-written wiki markdown files.

    required nav_file Path

    Path to the navigation specification file.

    required template Path | None

    Optional custom MkDocs configuration template.

    required out_dir Path

    Output directory for generated MCP resources.

    required

    Raises:

    Type Description UsageError

    If required options are missing or conflicting.

    "},{"location":"cli/commands/#docforge.cli.commands.serve","title":"serve","text":"
    serve(\n    mcp: bool,\n    mkdocs: bool,\n    lib: bool,\n    api: bool,\n    wiki: bool,\n    module: str | None,\n    mkdocs_yml: Path,\n    out_dir: Path,\n) -> None\n

    Serve generated documentation locally.

    Depending on the selected mode, this command starts either:

    The kind flags (--lib, --api, --wiki) select the generated per-kind config (docs/mkdocs.{kind}.yml); --mkdocs serves the config passed via --mkdocs-yml.

    Parameters:

    Name Type Description Default mcp bool

    Serve documentation using the MCP server.

    required mkdocs bool

    Serve the MkDocs development site from --mkdocs-yml.

    required lib bool

    Serve the lib MkDocs site.

    required api bool

    Serve the API MkDocs site.

    required wiki bool

    Serve the wiki MkDocs site.

    required module str | None

    Python module import path to serve via MCP.

    required mkdocs_yml Path

    Path to the MkDocs configuration file.

    required out_dir Path

    Root directory containing MCP documentation resources.

    required

    Raises:

    Type Description UsageError

    If invalid or conflicting options are provided.

    "},{"location":"cli/commands/#docforge.cli.commands.tree","title":"tree","text":"
    tree(module: str, project_name: str | None) -> None\n

    Display the documentation object tree for a module.

    This command introspects the specified module and prints a hierarchical representation of the discovered documentation objects, including modules, classes, functions, and members.

    Parameters:

    Name Type Description Default module str

    Python module import path to introspect.

    required project_name str | None

    Optional name to display as the project root.

    required"},{"location":"cli/main/","title":"Main","text":""},{"location":"cli/main/#docforge.cli.main","title":"docforge.cli.main","text":""},{"location":"cli/main/#docforge.cli.main--summary","title":"Summary","text":"

    Command-line entry point for the doc-forge CLI.

    This module exposes the executable entry point that initializes the Click command group defined in docforge.cli.commands.

    "},{"location":"cli/main/#docforge.cli.main-functions","title":"Functions","text":""},{"location":"cli/main/#docforge.cli.main.main","title":"main","text":"
    main() -> None\n

    Run the doc-forge command-line interface.

    This function initializes and executes the Click CLI application. It is used as the console entry point when invoking doc-forge from the command line.

    "},{"location":"cli/mcp_utils/","title":"Mcp Utils","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils","title":"docforge.cli.mcp_utils","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils--summary","title":"Summary","text":"

    Utilities for working with MCP in the doc-forge CLI.

    Notes "},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils-classes","title":"Classes","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils-functions","title":"Functions","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils.generate_resources","title":"generate_resources","text":"
    generate_resources(\n    module: str, project_name: str | None, out_dir: Path\n) -> None\n

    Generate MCP documentation resources from a Python module.

    The function performs project introspection, builds the internal documentation model, and renders MCP-compatible JSON resources to the specified output directory.

    Parameters:

    Name Type Description Default module str

    Python module import path used as the entry point for documentation generation.

    required project_name str | None

    Optional override for the project name used in generated documentation metadata.

    required out_dir Path

    Directory where MCP resources (index.json, nav.json, and module data) will be written.

    required"},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils.serve","title":"serve","text":"
    serve(module: str, mcp_root: Path) -> None\n

    Start an MCP server for a pre-generated documentation bundle.

    The server exposes documentation resources such as project metadata, navigation structure, and module documentation through MCP endpoints.

    Parameters:

    Name Type Description Default module str

    Python module import path used to identify the served documentation instance.

    required mcp_root Path

    Path to the directory containing the MCP documentation bundle (index.json, nav.json, and modules/).

    required

    Raises:

    Type Description ClickException

    If the MCP documentation bundle is missing required files or directories.

    "},{"location":"cli/mkdocs_utils/","title":"Mkdocs Utils","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils","title":"docforge.cli.mkdocs_utils","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils--summary","title":"Summary","text":"

    Utilities for working with MkDocs in the doc-forge CLI.

    Notes "},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils-classes","title":"Classes","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils-functions","title":"Functions","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_configs","title":"build_configs","text":"
    build_configs(yml_paths: Iterable[Path]) -> None\n

    Build the MkDocs documentation site for every given configuration.

    Each configuration file is loaded and built in turn, producing the per-kind static sites (site/lib, site/api, site/wiki).

    Parameters:

    Name Type Description Default yml_paths Iterable[Path]

    Configuration files to build, in order.

    required

    Raises:

    Type Description ClickException

    If a configuration file does not exist.

    "},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_lib_nav","title":"build_lib_nav","text":"
    build_lib_nav(\n    nav_file: Path, docs_root: Path\n) -> tuple[list[dict[str, Any]], dict[str, str] | None]\n

    Build the re-rooted navigation block for a lib site.

    The navigation specification is resolved against the shared documentation root and every resulting path is re-rooted relative to the lib subdirectory by stripping its leading lib/ scope component.

    Parameters:

    Name Type Description Default nav_file Path

    Path to the docforge.nav.yml navigation specification.

    required docs_root Path

    Shared documentation root containing the lib sources.

    required

    Returns:

    Type Description tuple[list[dict[str, Any]], dict[str, str] | None]

    tuple[list[dict[str, Any]], dict[str, str] | None]: The re-rooted navigation block and the optional theme icon mapping from the specification.

    Raises:

    Type Description FileError

    If the navigation specification cannot be found.

    "},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_wiki_nav_block","title":"build_wiki_nav_block","text":"
    build_wiki_nav_block(\n    wiki_dir: Path,\n) -> list[dict[str, Any]]\n

    Build the re-rooted navigation block for a wiki site.

    The wiki navigation derived from the wiki file structure is re-rooted relative to the wiki directory itself by stripping the leading wiki/ scope component.

    Parameters:

    Name Type Description Default wiki_dir Path

    Path to the hand-written wiki directory, for example docs/wiki.

    required

    Returns:

    Type Description list[dict[str, Any]]

    list[dict[str, Any]]: Navigation entries relative to the wiki directory.

    Raises:

    Type Description FileError

    If the wiki directory does not exist.

    "},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_site_config","title":"generate_site_config","text":"
    generate_site_config(\n    kind: str,\n    kind_root: Path,\n    nav_block: list[dict[str, Any]],\n    out: Path,\n    site_name: str,\n    docs_dir: str,\n    site_dir: str,\n    template: Path | None = None,\n    site_description: str | None = None,\n    site_author: str | None = None,\n    theme_icon: dict[str, str] | None = None,\n) -> None\n

    Generate a per-kind mkdocs.{kind}.yml configuration file.

    The configuration is created by merging the shared mkdocs.common.yml template with the fragment contributed by the kind (lib, api, or wiki). Both docs_dir and site_dir are written relative to the configuration file's directory: the kind's sources when expressed as a sibling path (for example lib) and the per-kind site output (for example ../site/lib).

    Parameters:

    Name Type Description Default kind str

    Documentation kind, one of lib, api, or wiki.

    required kind_root Path

    Directory scoped to the kind (for example docs/lib) that serves as the MkDocs docs_dir.

    required nav_block list[dict[str, Any]]

    Re-rooted navigation entries for the kind's site.

    required out Path

    Destination path where the generated mkdocs.{kind}.yml file is written.

    required site_name str

    Display name for the generated documentation site.

    required docs_dir str

    MkDocs docs_dir value, relative to the configuration file's directory.

    required site_dir str

    MkDocs site_dir value, relative to the configuration file's directory.

    required template Path | None

    Optional path to a fully custom MkDocs configuration template that replaces the built-in templates entirely.

    None site_description str | None

    Optional site description written into the configuration.

    None site_author str | None

    Optional site author written into the configuration.

    None theme_icon dict[str, str] | None

    Optional mapping of theme icon entries injected as theme.icon.

    None"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_sources","title":"generate_sources","text":"
    generate_sources(\n    module: str,\n    docs_dir: Path,\n    project_name: str | None = None,\n    module_is_source: bool | None = None,\n    readme_dir: Path | None = None,\n) -> None\n

    Generate MkDocs Markdown sources for a Python module.

    This function introspects the specified module, builds the internal documentation model, and renders Markdown documentation files for use with MkDocs.

    Parameters:

    Name Type Description Default module str

    Python module import path used as the entry point for documentation generation.

    required docs_dir Path

    Directory where the generated Markdown files will be written.

    required project_name str | None

    Optional override for the project name used in documentation metadata.

    None module_is_source bool | None

    If True, treat the specified module directory as the project root rather than a nested module.

    None readme_dir Path | None

    Directory where the generated README.md should be written. If not provided, defaults to the parent of docs_dir.

    None"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.load_spec_icon","title":"load_spec_icon","text":"
    load_spec_icon(nav_file: Path) -> dict[str, str] | None\n

    Load the theme icon mapping from a navigation specification.

    Parameters:

    Name Type Description Default nav_file Path

    Path to the navigation specification file.

    required

    Returns:

    Type Description dict[str, str] | None

    dict[str, str] | None: The icon mapping, or None when the specification file is absent or cannot be parsed.

    "},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.serve","title":"serve","text":"
    serve(mkdocs_yml: Path) -> None\n

    Start an MkDocs development server with live reload.

    The server watches documentation files and automatically reloads the site when changes are detected.

    Parameters:

    Name Type Description Default mkdocs_yml Path

    Path to the mkdocs.yml configuration file.

    required

    Raises:

    Type Description ClickException

    If the configuration file does not exist.

    "},{"location":"loaders/","title":"Loaders","text":""},{"location":"loaders/#docforge.loaders","title":"docforge.loaders","text":""},{"location":"loaders/#docforge.loaders--summary","title":"Summary","text":"

    Loader layer for doc-forge.

    The docforge.loaders package is responsible for discovering Python modules and extracting documentation data using static analysis.

    "},{"location":"loaders/#docforge.loaders--overview","title":"Overview","text":"

    This layer converts Python source code into an intermediate documentation model used by doc-forge. It performs module discovery, introspection, and initial filtering before the data is passed to the core documentation models.

    Core capabilities include:

    "},{"location":"loaders/#docforge.loaders-classes","title":"Classes","text":""},{"location":"loaders/#docforge.loaders.GriffeLoader","title":"GriffeLoader","text":"
    GriffeLoader()\n

    Load Python modules using Griffe and convert them into doc-forge models.

    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:

    Name Type Description _loader GriffeLoader

    Internal Griffe loader with dedicated module and line collections.

    Initialize the Griffe-backed loader.

    Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

    "},{"location":"loaders/#docforge.loaders.GriffeLoader-functions","title":"Functions","text":""},{"location":"loaders/#docforge.loaders.GriffeLoader.load_module","title":"load_module","text":"
    load_module(path: str) -> Module\n

    Load and convert a single Python module.

    The module is introspected using Griffe and then transformed into a doc-forge Module model.

    Parameters:

    Name Type Description Default path str

    Dotted import path of the module.

    required

    Returns:

    Name Type Description Module Module

    A populated Module instance.

    Raises:

    Type Description 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\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
    "},{"location":"loaders/#docforge.loaders.GriffeLoader.load_project","title":"load_project","text":"
    load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

    Load multiple modules and assemble them into a Project model.

    Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

    Parameters:

    Name Type Description Default module_paths list[str]

    List of dotted module import paths to load.

    required project_name str | None

    Optional override for the project name. Defaults to the top-level name of the first module.

    None skip_import_errors bool | None

    If True, modules that fail to load will be skipped instead of raising an error.

    None

    Returns:

    Name Type Description Project Project

    A populated Project instance containing the loaded modules.

    Raises:

    Type Description ValueError

    If no module paths are provided.

    ImportError

    If a module fails to load and skip_import_errors is False.

    "},{"location":"loaders/#docforge.loaders-functions","title":"Functions","text":""},{"location":"loaders/#docforge.loaders.discover_module_paths","title":"discover_module_paths","text":"
    discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

    Discover Python modules within a package directory.

    The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

    Discovery rules:

    Parameters:

    Name Type Description Default module_name str

    Top-level package name to discover modules from.

    required project_root Path | None

    Root directory used to resolve module paths. If not provided, the current working directory is used.

    None

    Returns:

    Type Description list[str]

    list[str]: A sorted list of unique dotted module import paths.

    Raises:

    Type Description FileNotFoundError

    If the specified package directory does not exist.

    "},{"location":"loaders/griffe_loader/","title":"Griffe Loader","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader","title":"docforge.loaders.griffe_loader","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader--summary","title":"Summary","text":"

    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 "},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader-classes","title":"Classes","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader","title":"GriffeLoader","text":"
    GriffeLoader()\n

    Load Python modules using Griffe and convert them into doc-forge models.

    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:

    Name Type Description _loader GriffeLoader

    Internal Griffe loader with dedicated module and line collections.

    Initialize the Griffe-backed loader.

    Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

    "},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader-functions","title":"Functions","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_module","title":"load_module","text":"
    load_module(path: str) -> Module\n

    Load and convert a single Python module.

    The module is introspected using Griffe and then transformed into a doc-forge Module model.

    Parameters:

    Name Type Description Default path str

    Dotted import path of the module.

    required

    Returns:

    Name Type Description Module Module

    A populated Module instance.

    Raises:

    Type Description 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\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
    "},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_project","title":"load_project","text":"
    load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

    Load multiple modules and assemble them into a Project model.

    Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

    Parameters:

    Name Type Description Default module_paths list[str]

    List of dotted module import paths to load.

    required project_name str | None

    Optional override for the project name. Defaults to the top-level name of the first module.

    None skip_import_errors bool | None

    If True, modules that fail to load will be skipped instead of raising an error.

    None

    Returns:

    Name Type Description Project Project

    A populated Project instance containing the loaded modules.

    Raises:

    Type Description ValueError

    If no module paths are provided.

    ImportError

    If a module fails to load and skip_import_errors is False.

    "},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader-functions","title":"Functions","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.discover_module_paths","title":"discover_module_paths","text":"
    discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

    Discover Python modules within a package directory.

    The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

    Discovery rules:

    Parameters:

    Name Type Description Default module_name str

    Top-level package name to discover modules from.

    required project_root Path | None

    Root directory used to resolve module paths. If not provided, the current working directory is used.

    None

    Returns:

    Type Description list[str]

    list[str]: A sorted list of unique dotted module import paths.

    Raises:

    Type Description FileNotFoundError

    If the specified package directory does not exist.

    "},{"location":"models/","title":"Models","text":""},{"location":"models/#docforge.models","title":"docforge.models","text":""},{"location":"models/#docforge.models--summary","title":"Summary","text":"

    Model layer for doc-forge.

    The docforge.models package defines the core data structures used to represent Python source code as a structured documentation model.

    "},{"location":"models/#docforge.models--overview","title":"Overview","text":"

    The model layer forms the central intermediate representation used throughout doc-forge. Python modules and objects discovered during introspection are converted into a hierarchy of documentation models that can later be rendered into different documentation formats.

    Key components:

    These models are intentionally renderer-agnostic, allowing the same documentation structure to be transformed into multiple output formats (e.g., MkDocs, MCP, or other renderers).

    "},{"location":"models/#docforge.models-classes","title":"Classes","text":""},{"location":"models/#docforge.models.DocObject","title":"DocObject","text":"
    DocObject(\n    name: str,\n    kind: str,\n    path: str,\n    signature: str | None = None,\n    docstring: str | None = None,\n)\n

    Representation of a documented Python object.

    A DocObject models a single Python entity discovered during introspection. Objects may contain nested members, allowing the structure of modules, classes, and other containers to be represented recursively.

    Attributes:

    Name Type Description name str

    Local name of the object.

    kind str

    Type of object (for example class, function, method, or attribute).

    path str

    Fully qualified dotted path to the object.

    signature str | None

    Callable signature if the object represents a callable.

    docstring str | None

    Raw docstring text extracted from the source code.

    members dict[str, DocObject]

    Mapping of member names to child DocObject instances.

    Initialize a DocObject instance.

    Parameters:

    Name Type Description Default name str

    Local name of the object.

    required kind str

    Object type identifier (for example class or function).

    required path str

    Fully qualified dotted path of the object.

    required signature str | None

    Callable signature if applicable.

    None docstring str | None

    Documentation string associated with the object.

    None"},{"location":"models/#docforge.models.DocObject-functions","title":"Functions","text":""},{"location":"models/#docforge.models.DocObject.add_member","title":"add_member","text":"
    add_member(obj: DocObject) -> None\n

    Add a child documentation object.

    This is typically used when attaching methods to classes or nested objects to their parent containers.

    Parameters:

    Name Type Description Default obj DocObject

    Documentation object to add as a member.

    required"},{"location":"models/#docforge.models.DocObject.get_all_members","title":"get_all_members","text":"
    get_all_members() -> Iterable[DocObject]\n

    Return all child members of the object.

    Returns:

    Type Description Iterable[DocObject]

    Iterable[DocObject]: An iterable of DocObject instances representing nested members.

    "},{"location":"models/#docforge.models.DocObject.get_member","title":"get_member","text":"
    get_member(name: str) -> DocObject\n

    Retrieve a member object by name.

    Parameters:

    Name Type Description Default name str

    Name of the member to retrieve.

    required

    Returns:

    Name Type Description DocObject DocObject

    The corresponding DocObject instance.

    Raises:

    Type Description KeyError

    If the member does not exist.

    "},{"location":"models/#docforge.models.Module","title":"Module","text":"
    Module(path: str, docstring: str | None = None)\n

    Representation of a documented Python module or package.

    A Module stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.

    Attributes:

    Name Type Description path str

    Dotted import path of the module.

    docstring str | None

    Module-level documentation string, if present.

    members dict[str, DocObject]

    Mapping of object names to their corresponding DocObject representations.

    Initialize a Module instance.

    Parameters:

    Name Type Description Default path str

    Dotted import path identifying the module.

    required docstring str | None

    Module-level documentation text, if available.

    None"},{"location":"models/#docforge.models.Module-functions","title":"Functions","text":""},{"location":"models/#docforge.models.Module.add_object","title":"add_object","text":"
    add_object(obj: DocObject) -> None\n

    Add a documented object to the module.

    Parameters:

    Name Type Description Default obj DocObject

    Documentation object to register as a top-level member of the module.

    required"},{"location":"models/#docforge.models.Module.get_all_objects","title":"get_all_objects","text":"
    get_all_objects() -> Iterable[DocObject]\n

    Return all top-level documentation objects in the module.

    Returns:

    Type Description Iterable[DocObject]

    Iterable[DocObject]: An iterable of DocObject instances representing the module's public members.

    "},{"location":"models/#docforge.models.Module.get_object","title":"get_object","text":"
    get_object(name: str) -> DocObject\n

    Retrieve a documented object by name.

    Parameters:

    Name Type Description Default name str

    Name of the object to retrieve.

    required

    Returns:

    Name Type Description DocObject DocObject

    The corresponding DocObject instance.

    Raises:

    Type Description KeyError

    If no object with the given name exists.

    "},{"location":"models/#docforge.models.Project","title":"Project","text":"
    Project(name: str)\n

    Representation of a documentation project.

    A Project serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.

    Attributes:

    Name Type Description name str

    Name of the project.

    modules dict[str, Module]

    Mapping of module paths to Module instances.

    Initialize a Project instance.

    Parameters:

    Name Type Description Default name str

    Name used to identify the documentation project.

    required Example

    Create a project and register a module:

    ```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n
    "},{"location":"models/#docforge.models.Project-functions","title":"Functions","text":""},{"location":"models/#docforge.models.Project.add_module","title":"add_module","text":"
    add_module(module: Module) -> None\n

    Register a module in the project.

    Parameters:

    Name Type Description Default module Module

    Module instance to add to the project.

    required"},{"location":"models/#docforge.models.Project.get_all_modules","title":"get_all_modules","text":"
    get_all_modules() -> Iterable[Module]\n

    Return all modules contained in the project.

    Returns:

    Type Description Iterable[Module]

    Iterable[Module]: An iterable of Module instances.

    "},{"location":"models/#docforge.models.Project.get_module","title":"get_module","text":"
    get_module(path: str) -> Module\n

    Retrieve a module by its dotted path.

    Parameters:

    Name Type Description Default path str

    Fully qualified dotted module path (for example pkg.module).

    required

    Returns:

    Name Type Description Module Module

    The corresponding Module instance.

    Raises:

    Type Description KeyError

    If the module does not exist in the project.

    "},{"location":"models/#docforge.models.Project.get_module_list","title":"get_module_list","text":"
    get_module_list() -> list[str]\n

    Return the list of module import paths.

    Returns:

    Type Description list[str]

    list[str]: A list containing the dotted paths of all modules in the project.

    "},{"location":"models/module/","title":"Module","text":""},{"location":"models/module/#docforge.models.module","title":"docforge.models.module","text":""},{"location":"models/module/#docforge.models.module--summary","title":"Summary","text":"

    Documentation model representing a Python module or package.

    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 "},{"location":"models/module/#docforge.models.module-classes","title":"Classes","text":""},{"location":"models/module/#docforge.models.module.Module","title":"Module","text":"
    Module(path: str, docstring: str | None = None)\n

    Representation of a documented Python module or package.

    A Module stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.

    Attributes:

    Name Type Description path str

    Dotted import path of the module.

    docstring str | None

    Module-level documentation string, if present.

    members dict[str, DocObject]

    Mapping of object names to their corresponding DocObject representations.

    Initialize a Module instance.

    Parameters:

    Name Type Description Default path str

    Dotted import path identifying the module.

    required docstring str | None

    Module-level documentation text, if available.

    None"},{"location":"models/module/#docforge.models.module.Module-functions","title":"Functions","text":""},{"location":"models/module/#docforge.models.module.Module.add_object","title":"add_object","text":"
    add_object(obj: DocObject) -> None\n

    Add a documented object to the module.

    Parameters:

    Name Type Description Default obj DocObject

    Documentation object to register as a top-level member of the module.

    required"},{"location":"models/module/#docforge.models.module.Module.get_all_objects","title":"get_all_objects","text":"
    get_all_objects() -> Iterable[DocObject]\n

    Return all top-level documentation objects in the module.

    Returns:

    Type Description Iterable[DocObject]

    Iterable[DocObject]: An iterable of DocObject instances representing the module's public members.

    "},{"location":"models/module/#docforge.models.module.Module.get_object","title":"get_object","text":"
    get_object(name: str) -> DocObject\n

    Retrieve a documented object by name.

    Parameters:

    Name Type Description Default name str

    Name of the object to retrieve.

    required

    Returns:

    Name Type Description DocObject DocObject

    The corresponding DocObject instance.

    Raises:

    Type Description KeyError

    If no object with the given name exists.

    "},{"location":"models/object/","title":"Object","text":""},{"location":"models/object/#docforge.models.object","title":"docforge.models.object","text":""},{"location":"models/object/#docforge.models.object--summary","title":"Summary","text":"

    Documentation model representing individual Python objects.

    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 "},{"location":"models/object/#docforge.models.object-classes","title":"Classes","text":""},{"location":"models/object/#docforge.models.object.DocObject","title":"DocObject","text":"
    DocObject(\n    name: str,\n    kind: str,\n    path: str,\n    signature: str | None = None,\n    docstring: str | None = None,\n)\n

    Representation of a documented Python object.

    A DocObject models a single Python entity discovered during introspection. Objects may contain nested members, allowing the structure of modules, classes, and other containers to be represented recursively.

    Attributes:

    Name Type Description name str

    Local name of the object.

    kind str

    Type of object (for example class, function, method, or attribute).

    path str

    Fully qualified dotted path to the object.

    signature str | None

    Callable signature if the object represents a callable.

    docstring str | None

    Raw docstring text extracted from the source code.

    members dict[str, DocObject]

    Mapping of member names to child DocObject instances.

    Initialize a DocObject instance.

    Parameters:

    Name Type Description Default name str

    Local name of the object.

    required kind str

    Object type identifier (for example class or function).

    required path str

    Fully qualified dotted path of the object.

    required signature str | None

    Callable signature if applicable.

    None docstring str | None

    Documentation string associated with the object.

    None"},{"location":"models/object/#docforge.models.object.DocObject-functions","title":"Functions","text":""},{"location":"models/object/#docforge.models.object.DocObject.add_member","title":"add_member","text":"
    add_member(obj: DocObject) -> None\n

    Add a child documentation object.

    This is typically used when attaching methods to classes or nested objects to their parent containers.

    Parameters:

    Name Type Description Default obj DocObject

    Documentation object to add as a member.

    required"},{"location":"models/object/#docforge.models.object.DocObject.get_all_members","title":"get_all_members","text":"
    get_all_members() -> Iterable[DocObject]\n

    Return all child members of the object.

    Returns:

    Type Description Iterable[DocObject]

    Iterable[DocObject]: An iterable of DocObject instances representing nested members.

    "},{"location":"models/object/#docforge.models.object.DocObject.get_member","title":"get_member","text":"
    get_member(name: str) -> DocObject\n

    Retrieve a member object by name.

    Parameters:

    Name Type Description Default name str

    Name of the member to retrieve.

    required

    Returns:

    Name Type Description DocObject DocObject

    The corresponding DocObject instance.

    Raises:

    Type Description KeyError

    If the member does not exist.

    "},{"location":"models/project/","title":"Project","text":""},{"location":"models/project/#docforge.models.project","title":"docforge.models.project","text":""},{"location":"models/project/#docforge.models.project--summary","title":"Summary","text":"

    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 "},{"location":"models/project/#docforge.models.project-classes","title":"Classes","text":""},{"location":"models/project/#docforge.models.project.Project","title":"Project","text":"
    Project(name: str)\n

    Representation of a documentation project.

    A Project serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.

    Attributes:

    Name Type Description name str

    Name of the project.

    modules dict[str, Module]

    Mapping of module paths to Module instances.

    Initialize a Project instance.

    Parameters:

    Name Type Description Default name str

    Name used to identify the documentation project.

    required Example

    Create a project and register a module:

    ```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n
    "},{"location":"models/project/#docforge.models.project.Project-functions","title":"Functions","text":""},{"location":"models/project/#docforge.models.project.Project.add_module","title":"add_module","text":"
    add_module(module: Module) -> None\n

    Register a module in the project.

    Parameters:

    Name Type Description Default module Module

    Module instance to add to the project.

    required"},{"location":"models/project/#docforge.models.project.Project.get_all_modules","title":"get_all_modules","text":"
    get_all_modules() -> Iterable[Module]\n

    Return all modules contained in the project.

    Returns:

    Type Description Iterable[Module]

    Iterable[Module]: An iterable of Module instances.

    "},{"location":"models/project/#docforge.models.project.Project.get_module","title":"get_module","text":"
    get_module(path: str) -> Module\n

    Retrieve a module by its dotted path.

    Parameters:

    Name Type Description Default path str

    Fully qualified dotted module path (for example pkg.module).

    required

    Returns:

    Name Type Description Module Module

    The corresponding Module instance.

    Raises:

    Type Description KeyError

    If the module does not exist in the project.

    "},{"location":"models/project/#docforge.models.project.Project.get_module_list","title":"get_module_list","text":"
    get_module_list() -> list[str]\n

    Return the list of module import paths.

    Returns:

    Type Description list[str]

    list[str]: A list containing the dotted paths of all modules in the project.

    "},{"location":"nav/","title":"Nav","text":""},{"location":"nav/#docforge.nav","title":"docforge.nav","text":"

    Navigation layer for doc-forge.

    The docforge.nav package manages the relationship between the logical documentation structure defined by the user and the physical documentation files generated on disk.

    "},{"location":"nav/#docforge.nav--workflow","title":"Workflow","text":"
    1. Specification \u2013 Users define navigation intent in docforge.nav.yml.
    2. Resolution \u2013 resolve_nav expands patterns and matches them against generated Markdown files.
    3. Emission \u2013 MkDocsNavEmitter converts the resolved structure into the YAML navigation format required by mkdocs.yml.

    This layer separates documentation organization from the underlying source code layout, enabling flexible grouping, ordering, and navigation structures independent of module hierarchy.

    "},{"location":"nav/#docforge.nav-classes","title":"Classes","text":""},{"location":"nav/#docforge.nav.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"

    Emit MkDocs navigation structures from resolved navigation data.

    The emitter transforms a ResolvedNav object into the YAML-compatible list structure expected by the MkDocs nav configuration field.

    "},{"location":"nav/#docforge.nav.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.MkDocsNavEmitter.emit","title":"emit","text":"
    emit(nav: ResolvedNav) -> list[dict[str, Any]]\n

    Generate a navigation structure for mkdocs.yml.

    Parameters:

    Name Type Description Default nav ResolvedNav

    Resolved navigation data describing documentation groups and their associated Markdown files.

    required

    Returns:

    Type Description list[dict[str, Any]]

    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.

    "},{"location":"nav/#docforge.nav.NavSpec","title":"NavSpec","text":"
    NavSpec(\n    home: str | None,\n    groups: dict[str, list[str]],\n    icon: dict[str, str] | None = None,\n)\n

    Parsed representation of a navigation specification.

    A NavSpec describes the intended documentation navigation layout before it is resolved against the filesystem.

    Attributes:

    Name Type Description home str | None

    Relative path to the documentation home page (for example index.md).

    groups dict[str, list[str]]

    Mapping of navigation group titles to lists of file patterns or glob expressions.

    icon

    Optional mapping of theme icon entries (for example {\"logo\": \"material/code-tags\"}) injected into the MkDocs theme as theme.icon.

    Initialize a NavSpec instance.

    Parameters:

    Name Type Description Default home str | None

    Relative path to the home document.

    required groups dict[str, list[str]]

    Mapping of group names to lists of path patterns (glob expressions).

    required icon dict[str, str] | None

    Optional mapping of theme icon entries applied to the generated MkDocs configuration.

    None"},{"location":"nav/#docforge.nav.NavSpec-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.NavSpec.all_patterns","title":"all_patterns","text":"
    all_patterns() -> list[str]\n

    Return all path patterns referenced by the specification.

    Returns:

    Type Description list[str]

    list[str]: A list containing the home document (if defined) and all group pattern entries.

    "},{"location":"nav/#docforge.nav.NavSpec.load","title":"load classmethod","text":"
    load(path: Path) -> NavSpec\n

    Load a navigation specification from a YAML file.

    Parameters:

    Name Type Description Default path Path

    Filesystem path to the navigation specification file.

    required

    Returns:

    Name Type Description NavSpec NavSpec

    A NavSpec instance representing the parsed configuration.

    Raises:

    Type Description FileNotFoundError

    If the specified file does not exist.

    ValueError

    If the file contents are not a valid navigation specification.

    "},{"location":"nav/#docforge.nav.ResolvedNav","title":"ResolvedNav","text":"
    ResolvedNav(\n    home: str | None,\n    groups: dict[str, list[Path]],\n    docs_root: Path | None = None,\n)\n

    Resolved navigation structure.

    A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.

    Attributes:

    Name Type Description home str | None

    Relative path to the documentation home page.

    groups dict[str, list[Path]]

    Mapping of navigation group titles to lists of resolved documentation file paths.

    Initialize a ResolvedNav instance.

    Parameters:

    Name Type Description Default home str | None

    Relative path to the home page within the documentation root.

    required groups dict[str, list[Path]]

    Mapping of group titles to resolved documentation file paths.

    required docs_root Path | None

    Root directory of the documentation source files.

    None"},{"location":"nav/#docforge.nav.ResolvedNav-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.ResolvedNav.all_files","title":"all_files","text":"
    all_files() -> Iterable[Path]\n

    Iterate over all files referenced by the navigation structure.

    Yields:

    Name Type Description Path Iterable[Path]

    A documentation file referenced by the navigation, including the home page when defined.

    Raises:

    Type Description RuntimeError

    If the home page is defined but the documentation root is not available for resolution.

    "},{"location":"nav/#docforge.nav-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.build_wiki_nav","title":"build_wiki_nav","text":"
    build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n

    Derive an MkDocs navigation block from a wiki directory.

    Returned paths are relative to the parent of wiki_dir and carry the wiki directory name as their leading component (for example wiki/01_overview.md when the wiki lives at docs/wiki). This makes the result directly usable in an MkDocs nav block with

    Parameters:

    Name Type Description Default wiki_dir Path

    Path to the hand-written wiki directory, for example docs/wiki.

    required

    Returns:

    Type Description 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.

    Raises:

    Type Description FileNotFoundError

    If the wiki directory does not exist.

    "},{"location":"nav/#docforge.nav.load_nav_spec","title":"load_nav_spec","text":"
    load_nav_spec(path: Path) -> NavSpec\n

    Load a navigation specification file.

    This helper function reads a YAML navigation file and constructs a corresponding NavSpec instance.

    Parameters:

    Name Type Description Default path Path

    Path to the navigation specification file.

    required

    Returns:

    Name Type Description NavSpec NavSpec

    A NavSpec instance representing the parsed specification.

    Raises:

    Type Description FileNotFoundError

    If the specification file does not exist.

    ValueError

    If the YAML structure is invalid.

    "},{"location":"nav/#docforge.nav.resolve_nav","title":"resolve_nav","text":"
    resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n

    Resolve a navigation specification against the filesystem.

    The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.

    Parameters:

    Name Type Description Default spec NavSpec

    Navigation specification describing documentation layout.

    required docs_root Path

    Root directory containing documentation Markdown files.

    required

    Returns:

    Name Type Description ResolvedNav ResolvedNav

    A ResolvedNav instance containing validated navigation paths.

    Raises:

    Type Description FileNotFoundError

    If the documentation root does not exist or a navigation pattern does not match any files.

    "},{"location":"nav/mkdocs/","title":"Mkdocs","text":""},{"location":"nav/mkdocs/#docforge.nav.mkdocs","title":"docforge.nav.mkdocs","text":"

    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 "},{"location":"nav/mkdocs/#docforge.nav.mkdocs-classes","title":"Classes","text":""},{"location":"nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"

    Emit MkDocs navigation structures from resolved navigation data.

    The emitter transforms a ResolvedNav object into the YAML-compatible list structure expected by the MkDocs nav configuration field.

    "},{"location":"nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter.emit","title":"emit","text":"
    emit(nav: ResolvedNav) -> list[dict[str, Any]]\n

    Generate a navigation structure for mkdocs.yml.

    Parameters:

    Name Type Description Default nav ResolvedNav

    Resolved navigation data describing documentation groups and their associated Markdown files.

    required

    Returns:

    Type Description list[dict[str, Any]]

    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.

    "},{"location":"nav/resolver/","title":"Resolver","text":""},{"location":"nav/resolver/#docforge.nav.resolver","title":"docforge.nav.resolver","text":"

    Navigation resolution utilities.

    This module resolves a NavSpec against the filesystem by expanding glob patterns and validating that referenced documentation files exist.

    Notes "},{"location":"nav/resolver/#docforge.nav.resolver-classes","title":"Classes","text":""},{"location":"nav/resolver/#docforge.nav.resolver.ResolvedNav","title":"ResolvedNav","text":"
    ResolvedNav(\n    home: str | None,\n    groups: dict[str, list[Path]],\n    docs_root: Path | None = None,\n)\n

    Resolved navigation structure.

    A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.

    Attributes:

    Name Type Description home str | None

    Relative path to the documentation home page.

    groups dict[str, list[Path]]

    Mapping of navigation group titles to lists of resolved documentation file paths.

    Initialize a ResolvedNav instance.

    Parameters:

    Name Type Description Default home str | None

    Relative path to the home page within the documentation root.

    required groups dict[str, list[Path]]

    Mapping of group titles to resolved documentation file paths.

    required docs_root Path | None

    Root directory of the documentation source files.

    None"},{"location":"nav/resolver/#docforge.nav.resolver.ResolvedNav-functions","title":"Functions","text":""},{"location":"nav/resolver/#docforge.nav.resolver.ResolvedNav.all_files","title":"all_files","text":"
    all_files() -> Iterable[Path]\n

    Iterate over all files referenced by the navigation structure.

    Yields:

    Name Type Description Path Iterable[Path]

    A documentation file referenced by the navigation, including the home page when defined.

    Raises:

    Type Description RuntimeError

    If the home page is defined but the documentation root is not available for resolution.

    "},{"location":"nav/resolver/#docforge.nav.resolver-functions","title":"Functions","text":""},{"location":"nav/resolver/#docforge.nav.resolver.resolve_nav","title":"resolve_nav","text":"
    resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n

    Resolve a navigation specification against the filesystem.

    The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.

    Parameters:

    Name Type Description Default spec NavSpec

    Navigation specification describing documentation layout.

    required docs_root Path

    Root directory containing documentation Markdown files.

    required

    Returns:

    Name Type Description ResolvedNav ResolvedNav

    A ResolvedNav instance containing validated navigation paths.

    Raises:

    Type Description FileNotFoundError

    If the documentation root does not exist or a navigation pattern does not match any files.

    "},{"location":"nav/spec/","title":"Spec","text":""},{"location":"nav/spec/#docforge.nav.spec","title":"docforge.nav.spec","text":"

    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 "},{"location":"nav/spec/#docforge.nav.spec-classes","title":"Classes","text":""},{"location":"nav/spec/#docforge.nav.spec.NavSpec","title":"NavSpec","text":"
    NavSpec(\n    home: str | None,\n    groups: dict[str, list[str]],\n    icon: dict[str, str] | None = None,\n)\n

    Parsed representation of a navigation specification.

    A NavSpec describes the intended documentation navigation layout before it is resolved against the filesystem.

    Attributes:

    Name Type Description home str | None

    Relative path to the documentation home page (for example index.md).

    groups dict[str, list[str]]

    Mapping of navigation group titles to lists of file patterns or glob expressions.

    icon

    Optional mapping of theme icon entries (for example {\"logo\": \"material/code-tags\"}) injected into the MkDocs theme as theme.icon.

    Initialize a NavSpec instance.

    Parameters:

    Name Type Description Default home str | None

    Relative path to the home document.

    required groups dict[str, list[str]]

    Mapping of group names to lists of path patterns (glob expressions).

    required icon dict[str, str] | None

    Optional mapping of theme icon entries applied to the generated MkDocs configuration.

    None"},{"location":"nav/spec/#docforge.nav.spec.NavSpec-functions","title":"Functions","text":""},{"location":"nav/spec/#docforge.nav.spec.NavSpec.all_patterns","title":"all_patterns","text":"
    all_patterns() -> list[str]\n

    Return all path patterns referenced by the specification.

    Returns:

    Type Description list[str]

    list[str]: A list containing the home document (if defined) and all group pattern entries.

    "},{"location":"nav/spec/#docforge.nav.spec.NavSpec.load","title":"load classmethod","text":"
    load(path: Path) -> NavSpec\n

    Load a navigation specification from a YAML file.

    Parameters:

    Name Type Description Default path Path

    Filesystem path to the navigation specification file.

    required

    Returns:

    Name Type Description NavSpec NavSpec

    A NavSpec instance representing the parsed configuration.

    Raises:

    Type Description FileNotFoundError

    If the specified file does not exist.

    ValueError

    If the file contents are not a valid navigation specification.

    "},{"location":"nav/spec/#docforge.nav.spec-functions","title":"Functions","text":""},{"location":"nav/spec/#docforge.nav.spec.load_nav_spec","title":"load_nav_spec","text":"
    load_nav_spec(path: Path) -> NavSpec\n

    Load a navigation specification file.

    This helper function reads a YAML navigation file and constructs a corresponding NavSpec instance.

    Parameters:

    Name Type Description Default path Path

    Path to the navigation specification file.

    required

    Returns:

    Name Type Description NavSpec NavSpec

    A NavSpec instance representing the parsed specification.

    Raises:

    Type Description FileNotFoundError

    If the specification file does not exist.

    ValueError

    If the YAML structure is invalid.

    "},{"location":"nav/wiki/","title":"Wiki","text":""},{"location":"nav/wiki/#docforge.nav.wiki","title":"docforge.nav.wiki","text":""},{"location":"nav/wiki/#docforge.nav.wiki--summary","title":"Summary","text":"

    Wiki navigation derivation.

    This module provides build_wiki_nav, which derives an MkDocs-ready navigation block from the file structure of a hand-written wiki directory (typically docs/wiki). wiki content is authored by hand and is never modified by doc-forge; only the navigation layout is inferred.

    "},{"location":"nav/wiki/#docforge.nav.wiki--notes","title":"Notes","text":""},{"location":"nav/wiki/#docforge.nav.wiki-functions","title":"Functions","text":""},{"location":"nav/wiki/#docforge.nav.wiki.build_wiki_nav","title":"build_wiki_nav","text":"
    build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n

    Derive an MkDocs navigation block from a wiki directory.

    Returned paths are relative to the parent of wiki_dir and carry the wiki directory name as their leading component (for example wiki/01_overview.md when the wiki lives at docs/wiki). This makes the result directly usable in an MkDocs nav block with

    Parameters:

    Name Type Description Default wiki_dir Path

    Path to the hand-written wiki directory, for example docs/wiki.

    required

    Returns:

    Type Description 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.

    Raises:

    Type Description FileNotFoundError

    If the wiki directory does not exist.

    "},{"location":"renderers/","title":"Renderers","text":""},{"location":"renderers/#docforge.renderers","title":"docforge.renderers","text":""},{"location":"renderers/#docforge.renderers--summary","title":"Summary","text":"

    Renderers layer for doc-forge.

    The docforge.renderers package transforms the internal documentation models into files formatted for specific documentation systems.

    "},{"location":"renderers/#docforge.renderers--overview","title":"Overview","text":"

    Renderers consume the doc-forge project model and generate output suitable for documentation tools or machine interfaces.

    Current implementations:

    "},{"location":"renderers/#docforge.renderers--extending","title":"Extending","text":"

    New renderers can be added by implementing the DocRenderer protocol defined in docforge.renderers.base.

    "},{"location":"renderers/#docforge.renderers-classes","title":"Classes","text":""},{"location":"renderers/#docforge.renderers.MCPRenderer","title":"MCPRenderer","text":"

    Renderer that generates MCP-compatible documentation resources.

    This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

    "},{"location":"renderers/#docforge.renderers.MCPRenderer-functions","title":"Functions","text":""},{"location":"renderers/#docforge.renderers.MCPRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(project: Project, out_dir: Path) -> None\n

    Generate MCP documentation resources for a project.

    The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

    Parameters:

    Name Type Description Default project Project

    Documentation project model to render.

    required out_dir Path

    Directory where MCP resources will be written.

    required"},{"location":"renderers/#docforge.renderers.MkDocsRenderer","title":"MkDocsRenderer","text":"

    Renderer that produces Markdown documentation for MkDocs.

    Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

    "},{"location":"renderers/#docforge.renderers.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"renderers/#docforge.renderers.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
    generate_readme(\n    project: Project,\n    docs_dir: Path,\n    module_is_source: bool | None = None,\n    readme_dir: Path | None = None,\n) -> None\n

    Generate a README.md file from the root module docstring.

    Notes

    Parameters:

    Name Type Description Default project Project

    Project model containing documentation metadata.

    required docs_dir Path

    Directory containing generated documentation sources.

    required module_is_source bool | None

    Whether the module is treated as the project source root.

    None readme_dir Path | None

    Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

    None"},{"location":"renderers/#docforge.renderers.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

    Generate Markdown documentation files for a project.

    This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

    Parameters:

    Name Type Description Default project Project

    Project model containing modules to document.

    required out_dir Path

    Directory where generated Markdown files will be written.

    required module_is_source bool | None

    If True, treat the specified module as the documentation root rather than nesting it inside a folder.

    None"},{"location":"renderers/base/","title":"Base","text":""},{"location":"renderers/base/#docforge.renderers.base","title":"docforge.renderers.base","text":""},{"location":"renderers/base/#docforge.renderers.base--summary","title":"Summary","text":"

    Renderer base interfaces and configuration models.

    This module defines the base protocol and configuration container used by doc-forge renderers. Concrete renderer implementations should implement the DocRenderer protocol.

    "},{"location":"renderers/base/#docforge.renderers.base-classes","title":"Classes","text":""},{"location":"renderers/base/#docforge.renderers.base.DocRenderer","title":"DocRenderer","text":"

    Bases: Protocol

    Protocol defining the interface for documentation renderers.

    Implementations of this protocol are responsible for transforming a Project model into renderer-specific documentation sources.

    "},{"location":"renderers/base/#docforge.renderers.base.DocRenderer-functions","title":"Functions","text":""},{"location":"renderers/base/#docforge.renderers.base.DocRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(project: Project, out_dir: Path) -> None\n

    Generate renderer-specific documentation sources.

    Parameters:

    Name Type Description Default project Project

    Project model containing modules and documentation objects.

    required out_dir Path

    Directory where generated documentation sources should be written.

    required"},{"location":"renderers/base/#docforge.renderers.base.RendererConfig","title":"RendererConfig","text":"
    RendererConfig(out_dir: Path, project: Project)\n

    Configuration container for documentation renderers.

    A RendererConfig instance groups together the project model and the output directory used during rendering.

    Attributes:

    Name Type Description out_dir Path

    Directory where generated documentation files will be written.

    project Project

    Documentation project model to be rendered.

    Initialize a RendererConfig instance.

    Parameters:

    Name Type Description Default out_dir Path

    Target directory where documentation files should be written.

    required project Project

    Introspected project model to render.

    required"},{"location":"renderers/base/#docforge.renderers.base.RendererConfig-functions","title":"Functions","text":""},{"location":"renderers/mcp_renderer/","title":"Mcp Renderer","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer","title":"docforge.renderers.mcp_renderer","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer--summary","title":"Summary","text":"

    MCP renderer implementation.

    This module defines the MCPRenderer class, which generates documentation resources compatible with the Model Context Protocol (MCP).

    "},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer-classes","title":"Classes","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer","title":"MCPRenderer","text":"

    Renderer that generates MCP-compatible documentation resources.

    This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

    "},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer-functions","title":"Functions","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(project: Project, out_dir: Path) -> None\n

    Generate MCP documentation resources for a project.

    The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

    Parameters:

    Name Type Description Default project Project

    Documentation project model to render.

    required out_dir Path

    Directory where MCP resources will be written.

    required"},{"location":"renderers/mkdocs_renderer/","title":"Mkdocs Renderer","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer","title":"docforge.renderers.mkdocs_renderer","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer--summary","title":"Summary","text":"

    MkDocs renderer implementation.

    This module defines the MkDocsRenderer class, which generates Markdown documentation sources compatible with MkDocs Material and the mkdocstrings plugin.

    The renderer ensures a consistent documentation structure by:

    "},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer-classes","title":"Classes","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer","title":"MkDocsRenderer","text":"

    Renderer that produces Markdown documentation for MkDocs.

    Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

    "},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
    generate_readme(\n    project: Project,\n    docs_dir: Path,\n    module_is_source: bool | None = None,\n    readme_dir: Path | None = None,\n) -> None\n

    Generate a README.md file from the root module docstring.

    Notes

    Parameters:

    Name Type Description Default project Project

    Project model containing documentation metadata.

    required docs_dir Path

    Directory containing generated documentation sources.

    required module_is_source bool | None

    Whether the module is treated as the project source root.

    None readme_dir Path | None

    Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

    None"},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
    generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

    Generate Markdown documentation files for a project.

    This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

    Parameters:

    Name Type Description Default project Project

    Project model containing modules to document.

    required out_dir Path

    Directory where generated Markdown files will be written.

    required module_is_source bool | None

    If True, treat the specified module as the documentation root rather than nesting it inside a folder.

    None"},{"location":"servers/","title":"Servers","text":""},{"location":"servers/#docforge.servers","title":"docforge.servers","text":""},{"location":"servers/#docforge.servers--summary","title":"Summary","text":"

    Server layer for doc-forge.

    This module exposes server implementations used to provide live access to generated documentation resources. Currently, it includes the MCP documentation server.

    "},{"location":"servers/#docforge.servers-classes","title":"Classes","text":""},{"location":"servers/#docforge.servers.MCPServer","title":"MCPServer","text":"
    MCPServer(mcp_root: Path, name: str)\n

    MCP server for serving a pre-generated documentation bundle.

    The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.

    Attributes:

    Name Type Description mcp_root Path

    Directory containing the generated MCP documentation bundle.

    app FastMCP

    Underlying FastMCP application instance that registers resources and tools.

    Initialize the MCP server.

    Parameters:

    Name Type Description Default mcp_root Path

    Directory containing the generated MCP documentation bundle (for example index.json, nav.json, and modules/).

    required name str

    Identifier used for the MCP server instance.

    required"},{"location":"servers/#docforge.servers.MCPServer-functions","title":"Functions","text":""},{"location":"servers/#docforge.servers.MCPServer.run","title":"run","text":"
    run(\n    transport: Literal[\n        \"stdio\", \"sse\", \"streamable-http\"\n    ] = \"streamable-http\",\n) -> None\n

    Start the MCP server.

    Parameters:

    Name Type Description Default transport Literal['stdio', 'sse', 'streamable-http']

    Transport mechanism used by the MCP server. Supported options include stdio, sse, and streamable-http.

    'streamable-http'"},{"location":"servers/mcp_server/","title":"Mcp Server","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server","title":"docforge.servers.mcp_server","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server--summary","title":"Summary","text":"

    MCP server implementation.

    This module defines the MCPServer class, which serves pre-generated documentation bundles through the Model Context Protocol (MCP).

    Notes "},{"location":"servers/mcp_server/#docforge.servers.mcp_server-classes","title":"Classes","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server.MCPServer","title":"MCPServer","text":"
    MCPServer(mcp_root: Path, name: str)\n

    MCP server for serving a pre-generated documentation bundle.

    The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.

    Attributes:

    Name Type Description mcp_root Path

    Directory containing the generated MCP documentation bundle.

    app FastMCP

    Underlying FastMCP application instance that registers resources and tools.

    Initialize the MCP server.

    Parameters:

    Name Type Description Default mcp_root Path

    Directory containing the generated MCP documentation bundle (for example index.json, nav.json, and modules/).

    required name str

    Identifier used for the MCP server instance.

    required"},{"location":"servers/mcp_server/#docforge.servers.mcp_server.MCPServer-functions","title":"Functions","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server.MCPServer.run","title":"run","text":"
    run(\n    transport: Literal[\n        \"stdio\", \"sse\", \"streamable-http\"\n    ] = \"streamable-http\",\n) -> None\n

    Start the MCP server.

    Parameters:

    Name Type Description Default transport Literal['stdio', 'sse', 'streamable-http']

    Transport mechanism used by the MCP server. Supported options include stdio, sse, and streamable-http.

    'streamable-http'"}]} \ No newline at end of file diff --git a/doc-forge/lib/sitemap.xml.gz b/doc-forge/lib/sitemap.xml.gz index 2984a5c0604425d6c75a5222b5179590ee6a2ad7..01465253604ef76b3b2b517f1166919160e58317 100644 GIT binary patch delta 13 Ucmb=gXP58h;ArStF_FCj03F=~f&c&j delta 13 Ucmb=gXP58h;9#&^K9Riw02xFBumAu6 diff --git a/hexa/lib/404.html b/hexa/lib/404.html index a438586..f85d18a 100644 --- a/hexa/lib/404.html +++ b/hexa/lib/404.html @@ -244,8 +244,6 @@ - - @@ -269,7 +267,7 @@ - Concepts + Shared Model @@ -279,108 +277,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - -
  • - - - - - - - - - - -
    • - - - - - - - - - - - - - - - - - - - - - - - -
  • - - - - - - - - - - -
    • + +
  • + + + Notes + + +
  • @@ -862,30 +767,6 @@ - -
    • @@ -940,10 +821,10 @@ - + -