{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83e\udde9 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.

Doc model: this wiki is written for humans \u2014 how\u2011to guides, examples, and testing recipes. The authoritative API contracts live in the code (docstrings) and the machine\u2011readable bundle under docs/mcp/.

"},{"location":"#key-features","title":"\ud83d\ude80 Key Features","text":""},{"location":"#installation","title":"\ud83d\udce6 Installation","text":"
# Internal PyPI (TBD)\npip install docforge\n
"},{"location":"#documentation-structure","title":"\ud83d\udcc1 Documentation Structure","text":"Section Description Overview What docforge is and how it fits the pipeline Components Loaders, models, nav, renderers, CLI, servers Conventions GSDFC, .pyi stubs, and template conventions Iterative Workflow How a docs build runs end to end Environment Environment setup Quality Gates Test layout and quality checks GSDFC Guide How to write GSDFC-conformant docstrings MCP Guide Building, serving, and consuming the MCP bundle MkDocs Configs MkDocs config generation and templates"},{"location":"#related-resources","title":"\ud83d\udd17 Related Resources","text":"

\u00a9 Aetoskia Internal \u2014 docforge 1.0

"},{"location":"01_overview/","title":"Library 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/#which-build-should-you-use","title":"\ud83e\udded Which Build Should You Use?","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/#architecture","title":"\ud83c\udfd7\ufe0f Architecture","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/#lifecycle-rules","title":"\ud83d\udd04 Lifecycle Rules","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":"01_overview/#read-next","title":"\u27a1\ufe0f Read Next","text":""},{"location":"02_components/","title":"Components","text":"

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

"},{"location":"02_components/#1-loaders-models","title":"1. Loaders & 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_components/#2-navigation","title":"2. 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_components/#3-renderers","title":"3. Renderers","text":"

docforge/renderers turn model data into artifacts:

"},{"location":"02_components/#4-servers","title":"4. Servers","text":"

docforge/servers serves generated artifacts over live protocols:

"},{"location":"02_components/#5-cli","title":"5. CLI","text":"

docforge/cli wires it all together:

"},{"location":"02_components/#related","title":"Related","text":""},{"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:

  1. Use parenthesized types in prose entries (name (Type):) that match the signature types.
  2. Use # Summary, # Examples, and # Notes sections at module level.
  3. Use Args:, Returns:, Raises:, Yields:, Notes:, and Example: sections at function and method level.
  4. Always update the matching .pyi stub alongside the .py implementation.
  5. Every distributable package ships a py.typed marker so type checkers consume the authored signatures instead of Any.
"},{"location":"03_conventions/#pyi-stubs-and-pytyped","title":".pyi stubs and py.typed","text":"

Every module ships a matching .pyi stub kept in sync with the .py implementation. When signatures change, update both files. Packages expose a py.typed marker so consumers and type checkers use the authored signatures.

"},{"location":"03_conventions/#wiki-pages","title":"Wiki pages","text":"
  1. Hand-written markdown lives in docs/wiki/** and is never generated.
  2. File names use a numeric prefix: 01_overview.md, 02_components.md.
  3. Nested directories become nested navigation groups: 05_development/01_environment.md \u2192 group Development.
  4. index.md is the site Home at the root, and a section root inside a directory.
  5. Navigation labels are derived by stripping the numeric prefix and applying title case on the remaining words.
"},{"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":"03_conventions/#related","title":"Related","text":""},{"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":"\ud83d\ude80 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":"\ud83d\udd04 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":"\ud83e\udded 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":"\ud83d\udce6 Serve the MCP bundle","text":"
doc-forge build --mcp --module docforge\ndoc-forge serve --mcp --module docforge\n
"},{"location":"04_iterative_workflow/#related","title":"Related","text":""},{"location":"05_development/01_environment/","title":"Environment Setup","text":""},{"location":"05_development/01_environment/#create-the-environment","title":"\ud83d\ude80 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":"\ud83d\udce6 Dependencies","text":"

Development extras include:

"},{"location":"05_development/01_environment/#related","title":"Related","text":""},{"location":"05_development/02_quality_gates/","title":"Quality Gates","text":"

Run all checks before pushing:

"},{"location":"05_development/02_quality_gates/#commands","title":"\ud83d\ude80 Commands","text":"
.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":"\ud83d\udcc1 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/02_quality_gates/#related","title":"Related","text":""},{"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":"\ud83e\udded Overview","text":""},{"location":"05_development/03_gsdfc_guide/#module-docstrings","title":"\ud83d\udce6 Module docstrings","text":"

Modules use Markdown headings and --- separators.

Recommended sections:

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

Recommended sections, in order:

"},{"location":"05_development/03_gsdfc_guide/#function-and-method-docstrings","title":"\ud83d\udce6 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":"\ud83d\udce6 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":"\ud83d\ude80 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":"\ud83d\udd04 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":"\ud83d\udee1\ufe0f Enforcement","text":"

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

"},{"location":"05_development/03_gsdfc_guide/#related","title":"Related","text":""},{"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":"\ud83d\ude80 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":"\ud83d\ude80 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":"\ud83d\udce6 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.

"},{"location":"05_development/04_mcp_guide/#related","title":"Related","text":""},{"location":"05_development/05_mkdocs_configs/","title":"MkDocs Configuration Model","text":"

Each documentation kind (lib, api, wiki) is built by its own MkDocs site. A repo that documents kind {kind} carries a config at docs/mkdocs.{kind}.yml that sets docs_dir to the kind's source directory and site_dir to ../site/{kind}.

"},{"location":"05_development/05_mkdocs_configs/#file-wins","title":"\ud83d\udcc4 File wins","text":"

docs/mkdocs.{kind}.yml is a repo-owned file, not a build byproduct:

Because a present file is never rewritten, rerunning a build is a no-op for versioned configs: the working tree stays clean.

"},{"location":"05_development/05_mkdocs_configs/#templates","title":"\ud83e\udde9 Templates","text":"

The built-in defaults live in docforge/templates/:

File Role mkdocs.common.yml Shared theme + markdown extensions mkdocs.lib.yml mkdocstrings handler for library reference mkdocs.api.yml Swagger/OpenAPI plugins and API-side features mkdocs.wiki.yml Wiki look: horizontal navigation.tabs header, blue grey/teal palette, Roboto

A per-kind config is generated by deep-merging the common template with the kind fragment, then filling in generation-time values (site_name, docs_dir, site_dir, nav, API site_description/site_author, and the theme icon from docforge.nav.yml). Pass --template <path> to replace the built-in templates entirely.

"},{"location":"05_development/05_mkdocs_configs/#supported-layouts","title":"\ud83c\udfd7\ufe0f Supported layouts","text":"

Commit docs/mkdocs.{kind}.yml so served docs are reproducible from source.

"},{"location":"05_development/05_mkdocs_configs/#related","title":"Related","text":""}]}