{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83d\udd28 docforge \u2014 Docstring-Driven Documentation Forge","text":"

docforge is an internal documentation tool that generates reference documentation from Google-Styled Doc-Forge Convention (GSDFC) docstrings and assembles it into per-kind MkDocs sites, alongside hand-written wiki pages and OpenAPI-based API docs.

"},{"location":"#key-features","title":"\ud83d\ude80 Key Features","text":""},{"location":"#documentation-structure","title":"\ud83d\udcc1 Documentation Structure","text":"Section Description Overview What docforge is and how it fits the pipeline Architecture Loaders, models, nav, renderers, CLI, servers Conventions GSDFC, .pyi stubs, and template conventions Iterative Workflow How a docs build runs end to end Development Environment setup and quality gates Docstring Guide How to write GSDFC-conformant docstrings MCP Guide Building, serving, and consuming the MCP bundle"},{"location":"#related-resources","title":"\ud83d\udd17 Related Resources","text":"

\u00a9 Aetoskia Internal

"},{"location":"01_overview/","title":"Overview","text":"

docforge turns GSDFC-compliant Python docstrings into maintainable reference documentation. It never edits source docstrings; it reads them, renders them, and assembles documentation sites from all available material.

"},{"location":"01_overview/#what-it-generates","title":"What it generates","text":"Kind Source Output lib GSDFC docstrings docs/lib/** rendered markdown api OpenAPI JSON spec docs/api/** rendered markdown wiki Hand-written markdown docs/wiki/** (unchanged) mcp GSDFC docstrings + renderers docs/mcp/** structured JSON"},{"location":"01_overview/#per-kind-mkdocs-builds","title":"Per-kind MkDocs builds","text":"

Each enabled site kind produces its own MkDocs configuration and build:

  1. --mkdocs (lib) writes docs/mkdocs.lib.yml and builds site/lib/.
  2. --api writes docs/mkdocs.api.yml and builds site/api/.
  3. --wiki writes docs/mkdocs.wiki.yml and builds site/wiki/.

Every site is self-contained (own theme assets and search index) with navigation derived or scoped to that kind. Hand-written wiki content is never overwritten or regenerated \u2014 only its navigation is derived automatically.

"},{"location":"01_overview/#mcp-bundle","title":"MCP bundle","text":"

docs/mcp/** is a self-contained, machine-readable reference generated from docforge's own GSDFC docstrings. doc-forge serve --mcp --module docforge serves it over MCP. See the MCP Guide.

"},{"location":"02_architecture/","title":"Architecture","text":"

docforge is split into four horizontal layers. Everything flows top to bottom through the CLI.

"},{"location":"02_architecture/#loaders-models","title":"Loaders \u2192 Models","text":"

The docforge/loaders package wraps griffe to extract modules, functions, classes, and Google-style docstring sections. Loaded data is normalized into the object model under docforge/models (Project, Module, DocObject).

"},{"location":"02_architecture/#navigation","title":"Navigation","text":"

docforge/nav parses docforge.nav.yml specs (NavSpec, Resolver, and the MkDocs nav emitter) and, since the wiki kind, derives wiki navigation from the file structure via build_wiki_nav.

"},{"location":"02_architecture/#renderers","title":"Renderers","text":"

docforge/renderers turn model data into artifacts:

"},{"location":"02_architecture/#servers","title":"Servers","text":"

docforge/servers serves generated artifacts over live protocols:

"},{"location":"02_architecture/#cli","title":"CLI","text":"

docforge/cli wires it all together:

"},{"location":"03_conventions/","title":"Conventions","text":""},{"location":"03_conventions/#gsdfc-docstrings","title":"GSDFC docstrings","text":"

All documented source uses the Google-Styled Doc-Forge Convention (GSDFC): Args:, Returns:, Raises:, and Attributes: sections with properly typed signatures.

The authoritative GSDFC specification lives in the docforge/__init__.py package docstring, which is exported verbatim into docs/mcp/modules/docforge.json, so the MCP bundle is self-documenting.

Key rules:

"},{"location":"03_conventions/#pyi-stubs","title":".pyi stubs","text":"

Every module ships a matching .pyi stub kept in sync with the .py implementation. When signatures change, update both files.

"},{"location":"03_conventions/#wiki-pages","title":"Wiki pages","text":""},{"location":"03_conventions/#templates","title":"Templates","text":"

MkDocs config fragments live in docforge/templates. The mkdocs.wiki.yml fragment carries only the search plugin, since wiki pages contain no mkdocstrings directives.

"},{"location":"04_iterative_workflow/","title":"Iterative Workflow","text":"

A docs build runs through the CLI in a single pass.

"},{"location":"04_iterative_workflow/#build-commands","title":"Build commands","text":"
# Library reference only\ndoc-forge build --mkdocs --module docforge\n\n# Wiki + library (each an independent MkDocs build)\ndoc-forge build --wiki --mkdocs --module docforge\n\n# Wiki only \u2014 no module required\ndoc-forge build --wiki --site-name docforge\n\n# MCP structured bundle\ndoc-forge build --mcp --module docforge\n
"},{"location":"04_iterative_workflow/#what-a-build-does","title":"What a build does","text":"
  1. Validates the requested modes (--mkdocs, --api, --wiki, --mcp).
  2. Generates library sources under docs/lib/** with MkDocsRenderer.
  3. Generates API sources under docs/api/** when --api is given.
  4. Derives the wiki navigation from docs/wiki/**.
  5. Writes one MkDocs config per site kind (docs/mkdocs.{lib,api,wiki}.yml), re-rooting navigation paths to each kind's docs_dir.
  6. Runs mkdocs build once per config, emitting self-contained sites site/lib/, site/api/, and site/wiki/.
"},{"location":"04_iterative_workflow/#explore-the-sites","title":"Explore the sites","text":"
doc-forge build --wiki --mkdocs --module docforge\ndoc-forge serve --wiki       # serves site preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or target any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n
"},{"location":"04_iterative_workflow/#serve-the-mcp-bundle","title":"Serve the MCP bundle","text":"
doc-forge build --mcp --module docforge\ndoc-forge serve --mcp --module docforge\n
"},{"location":"05_development/01_environment/","title":"Environment Setup","text":""},{"location":"05_development/01_environment/#create-the-environment","title":"Create the environment","text":"
python -m venv .venv\n.venv\\Scripts\\activate\npip install -e .\n

Requires Python 3.10+ (per pyproject.toml).

"},{"location":"05_development/01_environment/#dependencies","title":"Dependencies","text":"

Development extras include:

"},{"location":"05_development/02_quality_gates/","title":"Quality Gates","text":"

Run all checks before pushing:

.venv\\Scripts\\python.exe -m pytest\n.venv\\Scripts\\python.exe -m ruff check docforge tests\n.venv\\Scripts\\python.exe -m black --check docforge tests\n.venv\\Scripts\\python.exe -m mypy docforge\n.venv\\Scripts\\pydoclint.exe docforge\n
"},{"location":"05_development/02_quality_gates/#test-layout","title":"Test layout","text":"Path Covers tests/nav/ Nav spec, resolver, wiki nav tests/cli/ Build command flows and modes tests/renderers/ MkDocs / MCP rendering

CLI tests use the cli_runner fixture with mock_mkdocs_build and mock_mkdocs_load_config so they exercise the full flow without invoking a real MkDocs build.

"},{"location":"05_development/03_gsdfc_guide/","title":"GSDFC Docstring Guide","text":"

This page is the practical companion to the authoritative GSDFC specification in the docforge/__init__.py package docstring. It describes how to write docstrings that render correctly in MkDocs and stay machine-parseable by doc-forge, MkDocs, and MCP clients.

"},{"location":"05_development/03_gsdfc_guide/#overview","title":"Overview","text":""},{"location":"05_development/03_gsdfc_guide/#module-docstrings","title":"Module docstrings","text":"

Modules use Markdown headings and --- separators.

Recommended sections:

"},{"location":"05_development/03_gsdfc_guide/#class-docstrings","title":"Class docstrings","text":"

Recommended sections, in order:

"},{"location":"05_development/03_gsdfc_guide/#function-and-method-docstrings","title":"Function and method docstrings","text":"

Recommended section order:

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

Formatting rules:

"},{"location":"05_development/03_gsdfc_guide/#property-docstrings","title":"Property docstrings","text":"

Properties document their return values with a Returns: section and, when meaningful, an Example:.

"},{"location":"05_development/03_gsdfc_guide/#example","title":"Example","text":"
def process(foo: Foo, multiplier: int) -> int:\n    \"\"\"Process a Foo instance.\n\n    Args:\n        foo (Foo):\n            Foo instance to process.\n\n        multiplier (int):\n            Value used to scale foo.\n\n    Returns:\n        int:\n            Processed result.\n\n    Raises:\n        ValueError:\n            If multiplier is negative.\n\n    Example:\n        Process foo:\n\n            ```python\n            foo = Foo(\"example\", value=10)\n            result = process(foo, multiplier=2)\n            print(result)\n            ```\n    \"\"\"\n
"},{"location":"05_development/03_gsdfc_guide/#keeping-stubs-in-sync","title":"Keeping stubs in sync","text":"

Every .py module ships a matching .pyi stub. When a signature or a public symbol changes, update both files. Signature annotations in the stub must match the implementation.

"},{"location":"05_development/03_gsdfc_guide/#enforcement","title":"Enforcement","text":"

pydoclint (Google style) runs in CI and verifies that Args:/Returns: sections match function signatures, including types.

"},{"location":"05_development/04_mcp_guide/","title":"MCP Guide","text":"

Doc-forge can export a machine-readable MCP bundle from a project's GSDFC docstrings and serve that bundle over the Model Context Protocol (MCP). The bundle is self-contained: readers can derive the full API reference \u2014 signatures, docstrings, and structure \u2014 for the documented project.

"},{"location":"05_development/04_mcp_guide/#building-the-bundle","title":"Building the bundle","text":"
doc-forge build --mcp --module docforge\n

This writes structured JSON into docs/mcp/:

"},{"location":"05_development/04_mcp_guide/#serving-the-bundle","title":"Serving the bundle","text":"
doc-forge serve --mcp --module docforge\n

The MCPServer (in docforge/servers/mcp_server.py) exposes:

Resource Description docs://index Project metadata docs://nav Navigation structure docs://modules/{module} Individual module documentation

The server also registers a single diagnostic tool, ping, and is read-only. Missing resources are returned as structured error dictionaries rather than exceptions. The default transport is streamable-http; stdio and sse are supported via MCPServer.run.

"},{"location":"05_development/04_mcp_guide/#bundle-contents","title":"Bundle contents","text":"

Each module resource contains:

Because the bundle is generated from docstrings, the quality of the bundle equals the quality of the project's GSDFC docstrings. For docforge itself, the GSDFC specification is carried in modules/docforge.json via the docforge/__init__.py package docstring, making the bundle self-documenting.

"}]}