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:

    @@ -940,10 +821,10 @@ - + -