From 42e5ed290e5de925f857fc308e1ab75a9683ac75 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Fri, 11 Sep 2026 23:38:31 +0530 Subject: [PATCH] feat: list each declared doc kind as its own homepage card - compute per-kind home URLs (lib/, api/, wiki/) via _find_home_for_kind - emit one card per declared kind so multi-kind repos (e.g. doc-forge with lib + wiki) appear in each matching homepage section - declare the doc-forge wiki kind and refresh its vendored site with the combined lib + wiki build --- _index/index.html | 5 + collect.py | 41 +- config.yml | 5 +- doc-forge/404.html | 234 +- doc-forge/lib/cli/api_utils/index.html | 236 +- doc-forge/lib/cli/commands/index.html | 291 +- doc-forge/lib/cli/index.html | 234 +- doc-forge/lib/cli/main/index.html | 234 +- doc-forge/lib/cli/mcp_utils/index.html | 234 +- doc-forge/lib/cli/mkdocs_utils/index.html | 271 +- .../lib/docforge/cli/api_utils/index.html | 1707 +++++++++ .../lib/docforge/cli/commands/index.html | 1879 ++++++++++ doc-forge/lib/docforge/cli/index.html | 1348 +++++++ doc-forge/lib/docforge/cli/main/index.html | 1357 +++++++ .../lib/docforge/cli/mcp_utils/index.html | 1526 ++++++++ .../lib/docforge/cli/mkdocs_utils/index.html | 1857 ++++++++++ doc-forge/lib/docforge/index.html | 3213 +++++++++++++++++ .../docforge/loaders/griffe_loader/index.html | 1783 +++++++++ doc-forge/lib/docforge/loaders/index.html | 1807 +++++++++ doc-forge/lib/docforge/models/index.html | 2597 +++++++++++++ .../lib/docforge/models/module/index.html | 1703 +++++++++ .../lib/docforge/models/object/index.html | 1792 +++++++++ .../lib/docforge/models/project/index.html | 1728 +++++++++ doc-forge/lib/docforge/nav/index.html | 2499 +++++++++++++ doc-forge/lib/docforge/nav/mkdocs/index.html | 1487 ++++++++ .../lib/docforge/nav/resolver/index.html | 1700 +++++++++ doc-forge/lib/docforge/nav/spec/index.html | 1815 ++++++++++ doc-forge/lib/docforge/nav/wiki/index.html | 1465 ++++++++ .../lib/docforge/renderers/base/index.html | 1614 +++++++++ doc-forge/lib/docforge/renderers/index.html | 1790 +++++++++ .../renderers/mcp_renderer/index.html | 1469 ++++++++ .../renderers/mkdocs_renderer/index.html | 1616 +++++++++ doc-forge/lib/docforge/servers/index.html | 1512 ++++++++ .../docforge/servers/mcp_server/index.html | 1508 ++++++++ doc-forge/lib/index.html | 751 ++-- .../lib/loaders/griffe_loader/index.html | 234 +- doc-forge/lib/loaders/index.html | 236 +- doc-forge/lib/models/index.html | 234 +- doc-forge/lib/models/module/index.html | 234 +- doc-forge/lib/models/object/index.html | 234 +- doc-forge/lib/models/project/index.html | 234 +- doc-forge/lib/nav/index.html | 352 +- doc-forge/lib/nav/mkdocs/index.html | 234 +- doc-forge/lib/nav/resolver/index.html | 234 +- doc-forge/lib/nav/spec/index.html | 234 +- doc-forge/lib/renderers/base/index.html | 234 +- doc-forge/lib/renderers/index.html | 234 +- .../lib/renderers/mcp_renderer/index.html | 234 +- .../lib/renderers/mkdocs_renderer/index.html | 234 +- doc-forge/lib/servers/index.html | 234 +- doc-forge/lib/servers/mcp_server/index.html | 234 +- doc-forge/mcp/index.json | 2 +- .../mcp/modules/docforge.cli.api_utils.json | 102 + .../mcp/modules/docforge.cli.commands.json | 119 +- doc-forge/mcp/modules/docforge.cli.json | 238 +- .../modules/docforge.cli.mkdocs_utils.json | 17 +- doc-forge/mcp/modules/docforge.json | 273 +- doc-forge/mcp/modules/docforge.nav.json | 35 +- .../mcp/modules/docforge.nav.resolver.json | 9 +- doc-forge/mcp/modules/docforge.nav.spec.json | 17 +- doc-forge/mcp/nav.json | 4 + doc-forge/objects.inv | Bin 1198 -> 1283 bytes doc-forge/search/search_index.json | 2 +- doc-forge/wiki/01_overview/index.html | 1375 +++++++ doc-forge/wiki/02_architecture/index.html | 1393 +++++++ doc-forge/wiki/03_conventions/index.html | 1389 +++++++ .../wiki/04_iterative_workflow/index.html | 1382 +++++++ .../05_development/01_environment/index.html | 1347 +++++++ .../02_quality_gates/index.html | 1348 +++++++ doc-forge/wiki/index.html | 1400 +++++++ 70 files changed, 58518 insertions(+), 1106 deletions(-) create mode 100644 doc-forge/lib/docforge/cli/api_utils/index.html create mode 100644 doc-forge/lib/docforge/cli/commands/index.html create mode 100644 doc-forge/lib/docforge/cli/index.html create mode 100644 doc-forge/lib/docforge/cli/main/index.html create mode 100644 doc-forge/lib/docforge/cli/mcp_utils/index.html create mode 100644 doc-forge/lib/docforge/cli/mkdocs_utils/index.html create mode 100644 doc-forge/lib/docforge/index.html create mode 100644 doc-forge/lib/docforge/loaders/griffe_loader/index.html create mode 100644 doc-forge/lib/docforge/loaders/index.html create mode 100644 doc-forge/lib/docforge/models/index.html create mode 100644 doc-forge/lib/docforge/models/module/index.html create mode 100644 doc-forge/lib/docforge/models/object/index.html create mode 100644 doc-forge/lib/docforge/models/project/index.html create mode 100644 doc-forge/lib/docforge/nav/index.html create mode 100644 doc-forge/lib/docforge/nav/mkdocs/index.html create mode 100644 doc-forge/lib/docforge/nav/resolver/index.html create mode 100644 doc-forge/lib/docforge/nav/spec/index.html create mode 100644 doc-forge/lib/docforge/nav/wiki/index.html create mode 100644 doc-forge/lib/docforge/renderers/base/index.html create mode 100644 doc-forge/lib/docforge/renderers/index.html create mode 100644 doc-forge/lib/docforge/renderers/mcp_renderer/index.html create mode 100644 doc-forge/lib/docforge/renderers/mkdocs_renderer/index.html create mode 100644 doc-forge/lib/docforge/servers/index.html create mode 100644 doc-forge/lib/docforge/servers/mcp_server/index.html create mode 100644 doc-forge/mcp/modules/docforge.cli.api_utils.json create mode 100644 doc-forge/wiki/01_overview/index.html create mode 100644 doc-forge/wiki/02_architecture/index.html create mode 100644 doc-forge/wiki/03_conventions/index.html create mode 100644 doc-forge/wiki/04_iterative_workflow/index.html create mode 100644 doc-forge/wiki/05_development/01_environment/index.html create mode 100644 doc-forge/wiki/05_development/02_quality_gates/index.html create mode 100644 doc-forge/wiki/index.html diff --git a/_index/index.html b/_index/index.html index f287dfa..231d9a6 100644 --- a/_index/index.html +++ b/_index/index.html @@ -125,6 +125,11 @@

Wiki

+
+

Doc Forge

+

Renderer-agnostic Python documentation compiler powering MkDocs and MCP generation across Aetoskia projects.

+ View Documentation → +

Mongo Ops

A modular, async MongoDB operations layer for FastAPI microservices. Simplifies CRUD, transactions, and model management.

diff --git a/collect.py b/collect.py index 7d307cd..27b79a3 100644 --- a/collect.py +++ b/collect.py @@ -61,6 +61,18 @@ def _find_home(dest: Path) -> str: return "" +def _find_home_for_kind(dest: Path, kind: str) -> str: + """After copying a site into *dest*, return the relative URL path for a + specific doc kind. A root index.html serves every kind; otherwise each + kind is found under its own subdirectory (lib/, api/, wiki/).""" + if (dest / "index.html").exists(): + return "" + sub = dest / kind + if kind in ("lib", "api", "wiki") and (sub / "index.html").exists(): + return f"{kind}/" + return _find_home(dest) + + # ── index.html generator ──────────────────────────────────────────────────── INDEX_TEMPLATE = r""" @@ -154,24 +166,33 @@ def _render_section(title: str, cards: list[tuple[str, str, str, str]]) -> str: return "\n".join(lines) -def build_index_html(config: dict, home_urls: dict[str, str]) -> str: +def build_index_html( + config: dict, + home_urls: dict[str, str], + kind_urls: dict[tuple[str, str], str] | None = None, +) -> str: lib_cards: list[tuple[str, str, str, str]] = [] api_cards: list[tuple[str, str, str, str]] = [] wiki_cards: list[tuple[str, str, str, str]] = [] tutorial_cards: list[tuple[str, str, str, str]] = [] + kind_urls = kind_urls or {} + for entry in config.get("repos", []): docs = entry.get("docs") or {} name = entry["name"] title = _safe_title(entry) desc = _safe_description(entry) - url = home_urls.get(name, f"/{name}/") + base_url = home_urls.get(name, f"/{name}/") if docs.get("lib"): + url = kind_urls.get((name, "lib"), base_url) lib_cards.append((title, desc, url, "View Documentation")) - elif docs.get("api"): - api_cards.append((title, desc, url, "View Documentation")) - elif docs.get("wiki"): + if docs.get("wiki"): + url = kind_urls.get((name, "wiki"), base_url) wiki_cards.append((title, desc, url, "View Documentation")) + if docs.get("api"): + url = kind_urls.get((name, "api"), base_url) + api_cards.append((title, desc, url, "View Documentation")) for entry in config.get("static", []): kind = entry.get("kind") @@ -273,13 +294,19 @@ def collect(config: dict, dry_run: bool = False) -> list[str]: # ── compute home URLs ─────────────────────────────────────────────────── if not dry_run: + kind_urls: dict[tuple[str, str], str] = {} for entry in config.get("repos", []): - home_urls[entry["name"]] = f"/{entry['name']}/{_find_home(ROOT / entry['name'])}" + name = entry["name"] + dest = ROOT / name + home_urls[name] = f"/{name}/{_find_home(dest)}" + for kind in ("lib", "api", "wiki"): + if (entry.get("docs") or {}).get(kind): + kind_urls[(name, kind)] = f"/{name}/{_find_home_for_kind(dest, kind)}" for entry in config.get("static", []): home_urls[entry["repo"]] = f"/{entry['repo']}/{_find_home(ROOT / entry['repo'])}" # ── regenerate outputs ────────────────────────────────────────────── - index_html = build_index_html(config, home_urls) + index_html = build_index_html(config, home_urls, kind_urls) (ROOT / "_index" / "index.html").write_text(index_html, encoding="utf-8") nginx_conf = build_nginx_conf(service["html_port"]) (ROOT / "nginx.conf").write_text(nginx_conf, encoding="utf-8") diff --git a/config.yml b/config.yml index 507d0ec..3442e8b 100644 --- a/config.yml +++ b/config.yml @@ -9,8 +9,10 @@ # Served layout (flat, one dir per repo; no redirects): # lib -> //lib/ # api -> //api/ (or // when the site has a root index.html) -# wiki -> // +# wiki -> // when the wiki is the whole site (e.g. mongo-ops) +# -> //wiki/ in combined sites (e.g. doc-forge with lib + wiki) # mcp -> MCP server on its configured port +# The docs homepage lists a repo once per declared kind (lib, api, wiki). service: name: aetos-docs @@ -31,6 +33,7 @@ repos: title: Doc Forge description: Renderer-agnostic Python documentation compiler powering MkDocs and MCP generation across Aetoskia projects. docs: + wiki: site lib: site mcp: { bundle: docs/mcp, server: docforge, port: 8001 } diff --git a/doc-forge/404.html b/doc-forge/404.html index 2abaaf4..5e8f617 100644 --- a/doc-forge/404.html +++ b/doc-forge/404.html @@ -218,7 +218,7 @@
  • - + @@ -236,6 +236,198 @@ + + + +
  • + + + + + + Overview + + + + + +
    • + + + + + + + + + +
  • + + + + + + Architecture + + + + + +
    • + + + + + + + + + +
  • + + + + + + Conventions + + + + + +
    • + + + + + + + + + +
  • + + + + + + Iterative Workflow + + + + + +
    • + + + + + + + + + + + + + + + + + + + + + + + + + +
  • + + + + + + + + + + + + +
    • + + + + + + @@ -263,7 +455,7 @@ - +
    @@ -280,14 +472,14 @@ -
    -
    @@ -1266,6 +1462,7 @@ documentation sources, and optionally builds the final output.

    • MkDocs static documentation sites for library reference docs
    • Swagger-enabled API docs generated from an OpenAPI spec
      • +
    • Hand-written wiki pages included in the MkDocs site
    • MCP structured documentation resources
    @@ -1323,6 +1520,20 @@ documentation sources, and optionally builds the final output.

    required + + wiki + + bool + + +
    +

    Include a hand-written wiki directory in the MkDocs site.

    +
    + + + required + + module_is_source @@ -1407,6 +1618,20 @@ documentation sources, and optionally builds the final output.

    required + + wiki_dir + + Path + + +
    +

    Directory containing hand-written wiki markdown files.

    +
    + + + required + + nav_file diff --git a/doc-forge/lib/cli/index.html b/doc-forge/lib/cli/index.html index c8facf8..51e5d02 100644 --- a/doc-forge/lib/cli/index.html +++ b/doc-forge/lib/cli/index.html @@ -227,7 +227,7 @@
  • - + @@ -245,6 +245,198 @@ + + + +
  • + + + + + + Overview + + + + + +
    • + + + + + + + + + +
  • + + + + + + Architecture + + + + + +
    • + + + + + + + + + +
  • + + + + + + Conventions + + + + + +
    • + + + + + + + + + +
  • + + + + + + Iterative Workflow + + + + + +
    • + + + + + + + + + + + + + + + + + + + + + + + + + +
  • + + + + + + + + + + + + +
    • + + + + + + @@ -272,7 +464,7 @@ - +
    @@ -289,14 +481,14 @@ -
    - 
    generate_config(
+10
+11
    generate_config(
     docs_dir: Path,
     nav_file: Path,
     template: Path | None,
@@ -1331,7 +1524,8 @@ build command to generate the final static documentation site.
    
         modes: Iterable[str] | None = None,
     site_description: str | None = None,
     site_author: str | None = None,
-) -> None
+    wiki_dir: Path | None = None,
+) -> None
    @@ -1339,10 +1533,12 @@ build command to generate the final static documentation site.

    Generate an mkdocs.yml configuration file.

    The configuration is created by combining a template configuration with a navigation structure derived from the docforge navigation -specification.

    +specification (and, when a wiki directory is provided, from the wiki +file structure).

    The docs_dir is always written relative to the MkDocs root and is expected to be the shared documentation parent (for example docs), -with generated sources nested under lib/ or api/ subdirectories.

    +with generated sources nested under lib/ or api/ subdirectories +and hand-written wiki content under a wiki/ subdirectory.

    Parameters:

    @@ -1436,8 +1632,9 @@ template replaces the built-in templates entirely.

    Documentation modes to enable. Each mode contributes its own -built-in template fragment (for example lib or api), -merged on top of the shared mkdocs.common.yml template.

    +built-in template fragment (for example lib, api, or +wiki), merged on top of the shared mkdocs.common.yml +template.

    @@ -1472,6 +1669,23 @@ merged on top of the shared mkdocs.common.yml template.

    None + + wiki_dir + + Optional[Path] + + +
    +

    Optional path to a hand-written wiki directory (for example +docs/wiki). When provided, the site navigation is derived +from the wiki file structure and placed before the navigation +groups defined in nav_file.

    +
    + + + None + + @@ -1491,7 +1705,8 @@ merged on top of the shared mkdocs.common.yml template.

    -

    If the navigation specification or template file cannot be found.

    +

    If the navigation specification, template, or wiki directory +cannot be found.

    diff --git a/doc-forge/lib/docforge/cli/api_utils/index.html b/doc-forge/lib/docforge/cli/api_utils/index.html new file mode 100644 index 0000000..353d0ca --- /dev/null +++ b/doc-forge/lib/docforge/cli/api_utils/index.html @@ -0,0 +1,1707 @@ + + + + + + + + + + + + + + + + + + + Api Utils - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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[Any, Any] + +
    +

    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[Any, Any] + +
    +

    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 new file mode 100644 index 0000000..aa9ad55 --- /dev/null +++ b/doc-forge/lib/docforge/cli/commands/index.html @@ -0,0 +1,1879 @@ + + + + + + + + + + + + + + + + + + + Commands - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    Commands

    + + +
    + + + +

    + docforge.cli.commands + + +

    + +
    + +

    Summary

    +

    Command definitions for the doc-forge CLI.

    +

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

    + + + +
    + + + + + + +

    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,
+    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,
+    mkdocs_yml: Path,
+    out_dir: Path,
+) -> None
+
    + +
    + +

    Build documentation artifacts.

    +

    This command performs the full documentation build pipeline: +style of the selected platform, generates renderer-specific +documentation sources, and optionally builds the final output.

    +

    Depending on the selected options, the build can target:

    +
      +
    • MkDocs static documentation sites for library reference docs
      • +
    • Swagger-enabled API docs generated from an OpenAPI spec
      • +
    • Hand-written wiki pages included in the MkDocs site
      • +
    • MCP structured documentation resources
      • +
    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    mcp + bool + +
    +

    Enable MCP documentation generation.

    +
    +     		+ required +
    mkdocs + bool + +
    +

    Enable MkDocs library documentation generation.

    +
    +     		+ required +
    api + bool + +
    +

    Enable API documentation generation from an OpenAPI spec.

    +
    +     		+ required +
    wiki + bool + +
    +

    Include a hand-written wiki directory in the MkDocs site.

    +
    +     		+ required +
    module_is_source + bool + +
    +

    Treat the specified module directory as the project root.

    +
    +     		+ required +
    module + Optional[str] + +
    +

    Python module import path to document.

    +
    +     		+ required +
    openapi_spec + Optional[Path] + +
    +

    Path to the OpenAPI JSON specification used for API docs.

    +
    +     		+ required +
    project_name + Optional[str] + +
    +

    Optional override for the project name.

    +
    +     		+ required +
    site_name + Optional[str] + +
    +

    Display name for the MkDocs site.

    +
    +     		+ required +
    docs_dir + Path + +
    +

    Shared documentation root used as the MkDocs docs_dir.

    +
    +     		+ required +
    wiki_dir + Path + +
    +

    Directory containing hand-written wiki markdown files.

    +
    +     		+ required +
    nav_file + Path + +
    +

    Path to the navigation specification file.

    +
    +     		+ required +
    template + Optional[Path] + +
    +

    Optional custom MkDocs configuration template.

    +
    +     		+ required +
    mkdocs_yml + Path + +
    +

    Output path for the generated MkDocs configuration.

    +
    +     		+ 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
    serve(
+    mcp: bool,
+    mkdocs: 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 documentation
      • +
    • An MCP server exposing structured documentation resources
      • +
    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    mcp + bool + +
    +

    Serve documentation using the MCP server.

    +
    +     		+ required +
    mkdocs + bool + +
    +

    Serve the MkDocs development site.

    +
    +     		+ required +
    module + Optional[str] + +
    +

    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 + Optional[str] + +
    +

    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 new file mode 100644 index 0000000..741905f --- /dev/null +++ b/doc-forge/lib/docforge/cli/index.html @@ -0,0 +1,1348 @@ + + + + + + + + + + + + + + + + + + + Cli - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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 new file mode 100644 index 0000000..3877d1d --- /dev/null +++ b/doc-forge/lib/docforge/cli/main/index.html @@ -0,0 +1,1357 @@ + + + + + + + + + + + + + + + + + + + Main - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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 new file mode 100644 index 0000000..7c16802 --- /dev/null +++ b/doc-forge/lib/docforge/cli/mcp_utils/index.html @@ -0,0 +1,1526 @@ + + + + + + + + + + + + + + + + + + + Mcp Utils - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    Mcp Utils

    + + +
    + + + +

    + docforge.cli.mcp_utils + + +

    + +
    + +

    Summary

    +

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

    + + + +
    + + + + + + +

    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 + Optional[str] + +
    +

    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 new file mode 100644 index 0000000..8413897 --- /dev/null +++ b/doc-forge/lib/docforge/cli/mkdocs_utils/index.html @@ -0,0 +1,1857 @@ + + + + + + + + + + + + + + + + + + + Mkdocs Utils - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    Mkdocs Utils

    + + +
    + + + +

    + docforge.cli.mkdocs_utils + + +

    + +
    + +

    Summary

    +

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

    + + + +
    + + + + + + +

    Classes

    +

    Functions

    + +
    + + +

    + build + + +

    +
    1
    build(mkdocs_yml: Path) -> None
+
    + +
    + +

    Build the MkDocs documentation site.

    +

    This function loads the MkDocs configuration and runs the MkDocs +build command to generate the final static documentation site.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    mkdocs_yml + Path + +
    +

    Path to the mkdocs.yml configuration file.

    +
    +     		+ required +
    + + +

    Raises:

    + + + + + + + + + + + + + +
    TypeDescription
    + ClickException + +
    +

    If the configuration file does not exist.

    +
    +
    + +
    + +
    + +
    + + +

    + generate_config + + +

    +
     1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
    generate_config(
+    docs_dir: Path,
+    nav_file: Path,
+    template: Path | None,
+    out: Path,
+    site_name: str,
+    modes: Iterable[str] | None = None,
+    site_description: str | None = None,
+    site_author: str | None = None,
+    wiki_dir: Path | None = None,
+) -> None
+
    + +
    + +

    Generate an mkdocs.yml configuration file.

    +

    The configuration is created by combining a template configuration +with a navigation structure derived from the docforge navigation +specification (and, when a wiki directory is provided, from the wiki +file structure).

    +

    The docs_dir is always written relative to the MkDocs root and is +expected to be the shared documentation parent (for example docs), +with generated sources nested under lib/ or api/ subdirectories +and hand-written wiki content under a wiki/ subdirectory.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    docs_dir + Path + +
    +

    Shared documentation root used as the MkDocs docs_dir.

    +
    +     		+ required +
    nav_file + Path + +
    +

    Path to the docforge.nav.yml navigation specification.

    +
    +     		+ required +
    template + Optional[Path] + +
    +

    Optional path to a fully custom MkDocs configuration template. +If not provided, built-in templates are merged; the provided +template replaces the built-in templates entirely.

    +
    +     		+ required +
    out + Path + +
    +

    Destination path where the generated mkdocs.yml file will be written.

    +
    +     		+ required +
    site_name + str + +
    +

    Display name for the generated documentation site.

    +
    +     		+ required +
    modes + Optional[Iterable[str]] + +
    +

    Documentation modes to enable. Each mode contributes its own +built-in template fragment (for example lib, api, or +wiki), merged on top of the shared mkdocs.common.yml +template.

    +
    +     		+ None +
    site_description + Optional[str] + +
    +

    Optional site description written into the configuration.

    +
    +     		+ None +
    site_author + Optional[str] + +
    +

    Optional site author written into the configuration.

    +
    +     		+ None +
    wiki_dir + Optional[Path] + +
    +

    Optional path to a hand-written wiki directory (for example +docs/wiki). When provided, the site navigation is derived +from the wiki file structure and placed before the navigation +groups defined in nav_file.

    +
    +     		+ None +
    + + +

    Raises:

    + + + + + + + + + + + + + +
    TypeDescription
    + FileError + +
    +

    If the navigation specification, template, or wiki directory +cannot be found.

    +
    +
    + +
    + +
    + +
    + + +

    + 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 + Optional[str] + +
    +

    Optional override for the project name used in documentation metadata.

    +
    +     		+ None +
    module_is_source + Optional[bool] + +
    +

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

    +
    +     		+ None +
    readme_dir + Optional[Path] + +
    +

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

    +
    +     		+ None +
    + +
    + +
    + +
    + + +

    + 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 new file mode 100644 index 0000000..6c71b09 --- /dev/null +++ b/doc-forge/lib/docforge/index.html @@ -0,0 +1,3213 @@ + + + + + + + + + + + + + + + + + + + Docforge - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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

    +

    Generate an MkDocs site from a Python package:

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

    Generate MCP JSON documentation:

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

    Generate MkDocs site and MCP JSON documentation:

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

    Serve MkDocs locally:

    +
    1
    doc-forge serve --mkdocs --module my_package
+
    +

    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 instead of duplicating types in prose.
      • +
    • 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 structured sections.

    +
    +

    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.

    + +

    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.

    +
    +
    + +
    + +
    + +
    + + +
    + load_project + + +
    +
    1
+2
+3
+4
+5
    load_project(
+    module_paths: list[str],
+    project_name: str | None = None,
+    skip_import_errors: bool = 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 + +
    +

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

    +
    +     		+ None +
    skip_import_errors + bool + +
    +

    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.

    +

    Behavior:

    +
      +
    • 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 + Optional[bool] + +
    +

    Whether the module is treated as the project source root.

    +
    +     		+ None +
    readme_dir + Optional[Path] + +
    +

    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 + +
    +

    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 + +
    +

    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 new file mode 100644 index 0000000..2ad0059 --- /dev/null +++ b/doc-forge/lib/docforge/loaders/griffe_loader/index.html @@ -0,0 +1,1783 @@ + + + + + + + + + + + + + + + + + + + Griffe Loader - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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.

    + + + +
    + + + + + + +

    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.

    + +

    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.

    +
    +
    + +
    + +
    + +
    + + +
    + load_project + + +
    +
    1
+2
+3
+4
+5
    load_project(
+    module_paths: list[str],
+    project_name: str | None = None,
+    skip_import_errors: bool = 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 + +
    +

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

    +
    +     		+ None +
    skip_import_errors + bool + +
    +

    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 + +
    +

    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 new file mode 100644 index 0000000..d2c5d70 --- /dev/null +++ b/doc-forge/lib/docforge/loaders/index.html @@ -0,0 +1,1807 @@ + + + + + + + + + + + + + + + + + + + Loaders - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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.

    + +

    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.

    +
    +
    + +
    + +
    + +
    + + +
    + load_project + + +
    +
    1
+2
+3
+4
+5
    load_project(
+    module_paths: list[str],
+    project_name: str | None = None,
+    skip_import_errors: bool = 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 + +
    +

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

    +
    +     		+ None +
    skip_import_errors + bool + +
    +

    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 + +
    +

    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 new file mode 100644 index 0000000..f18f1a9 --- /dev/null +++ b/doc-forge/lib/docforge/models/index.html @@ -0,0 +1,2597 @@ + + + + + + + + + + + + + + + + + + + Models - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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 + Optional[str] + +
    +

    Callable signature if the object represents a callable.

    +
    +
    docstring + Optional[str] + +
    +

    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 + Optional[str] + +
    +

    Callable signature if applicable.

    +
    +     		+ None +
    docstring + Optional[str] + +
    +

    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 + Optional[str] + +
    +

    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 + Optional[str] + +
    +

    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 +
    + + + + +
    + + + + + + + +
    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 new file mode 100644 index 0000000..334e7ad --- /dev/null +++ b/doc-forge/lib/docforge/models/module/index.html @@ -0,0 +1,1703 @@ + + + + + + + + + + + + + + + + + + + Module - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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.

    + + + +
    + + + + + + +

    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 + Optional[str] + +
    +

    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 + Optional[str] + +
    +

    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 new file mode 100644 index 0000000..e1a51ae --- /dev/null +++ b/doc-forge/lib/docforge/models/object/index.html @@ -0,0 +1,1792 @@ + + + + + + + + + + + + + + + + + + + Object - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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.

    + + + +
    + + + + + + +

    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 + Optional[str] + +
    +

    Callable signature if the object represents a callable.

    +
    +
    docstring + Optional[str] + +
    +

    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 + Optional[str] + +
    +

    Callable signature if applicable.

    +
    +     		+ None +
    docstring + Optional[str] + +
    +

    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 new file mode 100644 index 0000000..d4a56f0 --- /dev/null +++ b/doc-forge/lib/docforge/models/project/index.html @@ -0,0 +1,1728 @@ + + + + + + + + + + + + + + + + + + + Project - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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.

    + + + +
    + + + + + + +

    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 +
    + + + + +
    + + + + + + + +
    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 new file mode 100644 index 0000000..b139caf --- /dev/null +++ b/doc-forge/lib/docforge/nav/index.html @@ -0,0 +1,2499 @@ + + + + + + + + + + + + + + + + + + + Nav - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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]] + +
    +

    A list of dictionaries representing the MkDocs navigation layout.

    +
    +
    + list[dict[str, Any]] + +
    +

    Each dictionary maps a navigation label to a page or a list of

    +
    +
    + list[dict[str, Any]] + +
    +

    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] + +
    +

    A list containing the home document (if defined) and all

    +
    +
    + list[str] + +
    +

    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:

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

    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + Iterable[Path] + +
    +

    An iterable of Path objects representing documentation files.

    +
    +
    + + +

    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:

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

    + + + + + + + + + + + + + +
    TypeDescription
    + 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 new file mode 100644 index 0000000..7a1e961 --- /dev/null +++ b/doc-forge/lib/docforge/nav/mkdocs/index.html @@ -0,0 +1,1487 @@ + + + + + + + + + + + + + + + + + + + Mkdocs - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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.

    + + + +
    + + + + + + +

    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]] + +
    +

    A list of dictionaries representing the MkDocs navigation layout.

    +
    +
    + list[dict[str, Any]] + +
    +

    Each dictionary maps a navigation label to a page or a list of

    +
    +
    + list[dict[str, Any]] + +
    +

    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 new file mode 100644 index 0000000..160809f --- /dev/null +++ b/doc-forge/lib/docforge/nav/resolver/index.html @@ -0,0 +1,1700 @@ + + + + + + + + + + + + + + + + + + + Resolver - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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.

    + + + +
    + + + + + + +

    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.

    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + Iterable[Path] + +
    +

    An iterable of Path objects representing documentation files.

    +
    +
    + + +

    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:

    + + + + + + + + + + + + + +
    TypeDescription
    + 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 new file mode 100644 index 0000000..b32db3f --- /dev/null +++ b/doc-forge/lib/docforge/nav/spec/index.html @@ -0,0 +1,1815 @@ + + + + + + + + + + + + + + + + + + + Spec - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

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

    + + + +
    + + + + + + +

    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] + +
    +

    A list containing the home document (if defined) and all

    +
    +
    + list[str] + +
    +

    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:

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

    + + + + + + + + + + + + + +
    TypeDescription
    + 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 new file mode 100644 index 0000000..924f0ea --- /dev/null +++ b/doc-forge/lib/docforge/nav/wiki/index.html @@ -0,0 +1,1465 @@ + + + + + + + + + + + + + + + + + + + Wiki - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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 new file mode 100644 index 0000000..45aea6a --- /dev/null +++ b/doc-forge/lib/docforge/renderers/base/index.html @@ -0,0 +1,1614 @@ + + + + + + + + + + + + + + + + + + + Base - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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 new file mode 100644 index 0000000..b855575 --- /dev/null +++ b/doc-forge/lib/docforge/renderers/index.html @@ -0,0 +1,1790 @@ + + + + + + + + + + + + + + + + + + + Renderers - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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.

    +

    Behavior:

    +
      +
    • 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 + Optional[bool] + +
    +

    Whether the module is treated as the project source root.

    +
    +     		+ None +
    readme_dir + Optional[Path] + +
    +

    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 + +
    +

    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 new file mode 100644 index 0000000..0365f55 --- /dev/null +++ b/doc-forge/lib/docforge/renderers/mcp_renderer/index.html @@ -0,0 +1,1469 @@ + + + + + + + + + + + + + + + + + + + Mcp Renderer - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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 new file mode 100644 index 0000000..44546fd --- /dev/null +++ b/doc-forge/lib/docforge/renderers/mkdocs_renderer/index.html @@ -0,0 +1,1616 @@ + + + + + + + + + + + + + + + + + + + Mkdocs Renderer - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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.

    +

    Behavior:

    +
      +
    • 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 + Optional[bool] + +
    +

    Whether the module is treated as the project source root.

    +
    +     		+ None +
    readme_dir + Optional[Path] + +
    +

    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 + +
    +

    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 new file mode 100644 index 0000000..615c80f --- /dev/null +++ b/doc-forge/lib/docforge/servers/index.html @@ -0,0 +1,1512 @@ + + + + + + + + + + + + + + + + + + + Servers - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

    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.

    + +

    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 new file mode 100644 index 0000000..e50585c --- /dev/null +++ b/doc-forge/lib/docforge/servers/mcp_server/index.html @@ -0,0 +1,1508 @@ + + + + + + + + + + + + + + + + + + + Mcp Server - docforge + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + +

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

    + + + +
    + + + + + + +

    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.

    + +

    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 77cea23..1190ba7 100644 --- a/doc-forge/lib/index.html +++ b/doc-forge/lib/index.html @@ -10,15 +10,13 @@ - - - Home - docforge + docforge - docforge @@ -110,7 +108,7 @@
    - Home + docforge
    @@ -222,32 +220,10 @@ - - -
  • - - - - - - - - - - +
  • + @@ -258,508 +234,197 @@ - - +
    • + - + + + Development + + + + + + + + @@ -795,7 +460,7 @@ - +
    @@ -812,14 +477,14 @@ -
    -
    - + diff --git a/doc-forge/lib/loaders/griffe_loader/index.html b/doc-forge/lib/loaders/griffe_loader/index.html index df6127c..7462c28 100644 --- a/doc-forge/lib/loaders/griffe_loader/index.html +++ b/doc-forge/lib/loaders/griffe_loader/index.html @@ -227,7 +227,7 @@
  • - + @@ -246,6 +246,198 @@ + + +
  • + + + + + + Overview + + + + + +
    • + + + + + + + + + +
  • + + + + + + Architecture + + + + + +
    • + + + + + + + + + +
  • + + + + + + Conventions + + + + + +
    • + + + + + + + + + +
  • + + + + + + Iterative Workflow + + + + + +
    • + + + + + + + + + + + + + + + + + + + + + + + + + +
  • + + + + + + + + + + + + +
    • + + + + + + + @@ -272,7 +464,7 @@ - +
    @@ -289,14 +481,14 @@ -
    -