1 line
18 KiB
JSON
1 line
18 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83d\udd28 docforge \u2014 Docstring-Driven Documentation Forge","text":"<p><code>docforge</code> 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.</p>"},{"location":"#key-features","title":"\ud83d\ude80 Key Features","text":"<ul> <li>\ud83e\uddea GSDFC docstring extraction via Griffe</li> <li>\ud83e\udded Auto-derived navigation for hand-written wiki pages</li> <li>\ud83d\uddc2 Independent MkDocs builds per kind (lib, api, wiki) into <code>site/{kind}</code></li> <li>\ud83d\udd0c Material MkDocs theming out of the box</li> <li>\ud83d\udce6 MCP structured documentation resources</li> </ul>"},{"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, <code>.pyi</code> 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":"<ul> <li>Source Code: the <code>doc-forge</code> repository</li> <li>Wiki Kind: hand-written content lives in <code>docs/wiki/</code></li> <li>MCP Bundle: generated by <code>doc-forge build --mcp --module docforge</code> into <code>docs/mcp/</code></li> </ul> <p>\u00a9 Aetoskia Internal</p>"},{"location":"01_overview/","title":"Overview","text":"<p><code>docforge</code> 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.</p>"},{"location":"01_overview/#what-it-generates","title":"What it generates","text":"Kind Source Output <code>lib</code> GSDFC docstrings <code>docs/lib/**</code> rendered markdown <code>api</code> OpenAPI JSON spec <code>docs/api/**</code> rendered markdown <code>wiki</code> Hand-written markdown <code>docs/wiki/**</code> (unchanged) <code>mcp</code> GSDFC docstrings + renderers <code>docs/mcp/**</code> structured JSON"},{"location":"01_overview/#per-kind-mkdocs-builds","title":"Per-kind MkDocs builds","text":"<p>Each enabled site kind produces its own MkDocs configuration and build:</p> <ol> <li><code>--mkdocs</code> (lib) writes <code>docs/mkdocs.lib.yml</code> and builds <code>site/lib/</code>.</li> <li><code>--api</code> writes <code>docs/mkdocs.api.yml</code> and builds <code>site/api/</code>.</li> <li><code>--wiki</code> writes <code>docs/mkdocs.wiki.yml</code> and builds <code>site/wiki/</code>.</li> </ol> <p>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.</p>"},{"location":"01_overview/#mcp-bundle","title":"MCP bundle","text":"<p><code>docs/mcp/**</code> is a self-contained, machine-readable reference generated from docforge's own GSDFC docstrings. <code>doc-forge serve --mcp --module docforge</code> serves it over MCP. See the MCP Guide.</p>"},{"location":"02_architecture/","title":"Architecture","text":"<p><code>docforge</code> is split into four horizontal layers. Everything flows top to bottom through the CLI.</p>"},{"location":"02_architecture/#loaders-models","title":"Loaders \u2192 Models","text":"<p>The <code>docforge/loaders</code> package wraps <code>griffe</code> to extract modules, functions, classes, and Google-style docstring sections. Loaded data is normalized into the object model under <code>docforge/models</code> (<code>Project</code>, <code>Module</code>, <code>DocObject</code>).</p>"},{"location":"02_architecture/#navigation","title":"Navigation","text":"<p><code>docforge/nav</code> parses <code>docforge.nav.yml</code> specs (<code>NavSpec</code>, <code>Resolver</code>, and the MkDocs nav emitter) and, since the wiki kind, derives wiki navigation from the file structure via <code>build_wiki_nav</code>.</p>"},{"location":"02_architecture/#renderers","title":"Renderers","text":"<p><code>docforge/renderers</code> turn model data into artifacts:</p> <ul> <li><code>MkDocsRenderer</code> \u2192 <code>docs/lib/**</code> reference markdown</li> <li><code>MCPRenderer</code> \u2192 <code>docs/mcp/**</code> structured documentation</li> </ul>"},{"location":"02_architecture/#servers","title":"Servers","text":"<p><code>docforge/servers</code> serves generated artifacts over live protocols:</p> <ul> <li><code>MCPServer</code> \u2192 serves a pre-generated <code>docs/mcp/**</code> bundle through MCP resources (<code>docs://index</code>, <code>docs://nav</code>, <code>docs://modules/{module}</code>)</li> </ul>"},{"location":"02_architecture/#cli","title":"CLI","text":"<p><code>docforge/cli</code> wires it all together:</p> <ul> <li><code>commands.py</code> \u2014 the <code>build</code> command and its <code>--mkdocs</code> / <code>--api</code> / <code>--wiki</code> / <code>--mcp</code> modes</li> <li><code>mkdocs_utils.py</code> \u2014 per-kind config generation (<code>docs/mkdocs.{lib,api,wiki}.yml</code>) with navigation re-rooted to each kind's <code>docs_dir</code></li> <li><code>api_utils.py</code> \u2014 OpenAPI loading and API docs generation</li> </ul>"},{"location":"03_conventions/","title":"Conventions","text":""},{"location":"03_conventions/#gsdfc-docstrings","title":"GSDFC docstrings","text":"<p>All documented source uses the Google-Styled Doc-Forge Convention (GSDFC): <code>Args:</code>, <code>Returns:</code>, <code>Raises:</code>, and <code>Attributes:</code> sections with properly typed signatures.</p> <p>The authoritative GSDFC specification lives in the <code>docforge/__init__.py</code> package docstring, which is exported verbatim into <code>docs/mcp/modules/docforge.json</code>, so the MCP bundle is self-documenting.</p> <p>Key rules:</p> <ul> <li>Use parenthesized types in prose entries (<code>name (Type):</code>) that match the signature types.</li> <li>Use <code># Summary</code>, <code># Examples</code>, and <code># Notes</code> sections at module level.</li> <li>Use <code>Args:</code>, <code>Returns:</code>, <code>Raises:</code>, <code>Yields:</code>, <code>Notes:</code>, and <code>Example:</code> sections at function and method level.</li> <li>Always update the matching <code>.pyi</code> stub alongside the <code>.py</code> implementation.</li> </ul>"},{"location":"03_conventions/#pyi-stubs","title":"<code>.pyi</code> stubs","text":"<p>Every module ships a matching <code>.pyi</code> stub kept in sync with the <code>.py</code> implementation. When signatures change, update both files.</p>"},{"location":"03_conventions/#wiki-pages","title":"Wiki pages","text":"<ul> <li>Hand-written markdown lives in <code>docs/wiki/**</code> and is never generated.</li> <li>File names use a numeric prefix: <code>01_overview.md</code>, <code>02_architecture.md</code>.</li> <li>Nested directories become nested navigation groups: <code>05_development/01_environment.md</code> \u2192 group Development.</li> <li><code>index.md</code> is the site <code>Home</code> at the root, and a section root inside a directory.</li> <li>Navigation labels are derived by stripping the numeric prefix and applying title case on the remaining words.</li> </ul>"},{"location":"03_conventions/#templates","title":"Templates","text":"<p>MkDocs config fragments live in <code>docforge/templates</code>. The <code>mkdocs.wiki.yml</code> fragment carries only the <code>search</code> plugin, since wiki pages contain no mkdocstrings directives.</p>"},{"location":"04_iterative_workflow/","title":"Iterative Workflow","text":"<p>A docs build runs through the CLI in a single pass.</p>"},{"location":"04_iterative_workflow/#build-commands","title":"Build commands","text":"<pre><code># 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</code></pre>"},{"location":"04_iterative_workflow/#what-a-build-does","title":"What a build does","text":"<ol> <li>Validates the requested modes (<code>--mkdocs</code>, <code>--api</code>, <code>--wiki</code>, <code>--mcp</code>).</li> <li>Generates library sources under <code>docs/lib/**</code> with <code>MkDocsRenderer</code>.</li> <li>Generates API sources under <code>docs/api/**</code> when <code>--api</code> is given.</li> <li>Derives the wiki navigation from <code>docs/wiki/**</code>.</li> <li>Writes one MkDocs config per site kind (<code>docs/mkdocs.{lib,api,wiki}.yml</code>), re-rooting navigation paths to each kind's <code>docs_dir</code>.</li> <li>Runs <code>mkdocs build</code> once per config, emitting self-contained sites <code>site/lib/</code>, <code>site/api/</code>, and <code>site/wiki/</code>.</li> </ol>"},{"location":"04_iterative_workflow/#explore-the-sites","title":"Explore the sites","text":"<pre><code>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</code></pre>"},{"location":"04_iterative_workflow/#serve-the-mcp-bundle","title":"Serve the MCP bundle","text":"<pre><code>doc-forge build --mcp --module docforge\ndoc-forge serve --mcp --module docforge\n</code></pre>"},{"location":"05_development/01_environment/","title":"Environment Setup","text":""},{"location":"05_development/01_environment/#create-the-environment","title":"Create the environment","text":"<pre><code>python -m venv .venv\n.venv\\Scripts\\activate\npip install -e .\n</code></pre> <p>Requires Python 3.10+ (per <code>pyproject.toml</code>).</p>"},{"location":"05_development/01_environment/#dependencies","title":"Dependencies","text":"<p>Development extras include:</p> <ul> <li><code>pytest</code>, <code>pytest-cov</code> \u2014 test suite and coverage</li> <li><code>ruff</code> \u2014 lint and format checking</li> <li><code>black</code> \u2014 auto-formatting</li> <li><code>mypy</code> \u2014 strict typing checks</li> <li><code>pydoclint</code> \u2014 docstring \u2194 signature consistency checks</li> </ul>"},{"location":"05_development/02_quality_gates/","title":"Quality Gates","text":"<p>Run all checks before pushing:</p> <pre><code>.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</code></pre>"},{"location":"05_development/02_quality_gates/#test-layout","title":"Test layout","text":"Path Covers <code>tests/nav/</code> Nav spec, resolver, wiki nav <code>tests/cli/</code> Build command flows and modes <code>tests/renderers/</code> MkDocs / MCP rendering <p>CLI tests use the <code>cli_runner</code> fixture with <code>mock_mkdocs_build</code> and <code>mock_mkdocs_load_config</code> so they exercise the full flow without invoking a real MkDocs build.</p>"},{"location":"05_development/03_gsdfc_guide/","title":"GSDFC Docstring Guide","text":"<p>This page is the practical companion to the authoritative GSDFC specification in the <code>docforge/__init__.py</code> package docstring. It describes how to write docstrings that render correctly in MkDocs and stay machine-parseable by doc-forge, MkDocs, and MCP clients.</p>"},{"location":"05_development/03_gsdfc_guide/#overview","title":"Overview","text":"<ul> <li>Docstrings are the single source of truth.</li> <li><code>doc-forge</code> compiles docstrings but never rewrites them.</li> <li>Every public symbol should have a complete, accurate docstring.</li> <li>Type hints live in signatures; prose entries repeat the type in parentheses and must match the signature.</li> </ul>"},{"location":"05_development/03_gsdfc_guide/#module-docstrings","title":"Module docstrings","text":"<p>Modules use Markdown headings and <code>---</code> separators.</p> <p>Recommended sections:</p> <ul> <li><code># Summary</code> \u2014 what the subsystem does</li> <li><code># Examples</code> \u2014 a representative usage snippet</li> <li><code># Notes</code> \u2014 guarantees, lifecycle, and thread-safety notes</li> </ul>"},{"location":"05_development/03_gsdfc_guide/#class-docstrings","title":"Class docstrings","text":"<p>Recommended sections, in order:</p> <ul> <li>summary line describing responsibility</li> <li><code>Attributes:</code> \u2014 instance attributes with <code>name (Type):</code> entries</li> <li><code>Notes:</code> \u2014 grouped subsections such as Guarantees, Lifecycle</li> <li><code>Example:</code> \u2014 indented <code>python</code> code block</li> </ul>"},{"location":"05_development/03_gsdfc_guide/#function-and-method-docstrings","title":"Function and method docstrings","text":"<p>Recommended section order:</p> <ol> <li><code>Args:</code></li> <li><code>Returns:</code></li> <li><code>Raises:</code></li> <li><code>Yields:</code></li> <li><code>Notes:</code></li> <li><code>Example:</code></li> </ol> <p>Formatting rules:</p> <ul> <li><code>Args:</code> entries are <code>name (Type):</code> followed by an indented description.</li> <li><code>Returns:</code> entries are <code>Type:</code> followed by an indented description.</li> <li><code>Raises:</code> entries are <code>ExceptionType:</code> followed by an indented condition.</li> <li><code>Yields:</code> replaces <code>Returns:</code> for generators.</li> <li>Summaries are written in the imperative mood.</li> <li>Fenced <code>python</code> blocks are allowed inside <code>Example:</code> sections, indented four spaces.</li> </ul>"},{"location":"05_development/03_gsdfc_guide/#property-docstrings","title":"Property docstrings","text":"<p>Properties document their return values with a <code>Returns:</code> section and, when meaningful, an <code>Example:</code>.</p>"},{"location":"05_development/03_gsdfc_guide/#example","title":"Example","text":"<pre><code>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</code></pre>"},{"location":"05_development/03_gsdfc_guide/#keeping-stubs-in-sync","title":"Keeping stubs in sync","text":"<p>Every <code>.py</code> module ships a matching <code>.pyi</code> stub. When a signature or a public symbol changes, update both files. Signature annotations in the stub must match the implementation.</p>"},{"location":"05_development/03_gsdfc_guide/#enforcement","title":"Enforcement","text":"<p><code>pydoclint</code> (Google style) runs in CI and verifies that <code>Args:</code>/<code>Returns:</code> sections match function signatures, including types.</p> <ul> <li><code>allow-init-docstring = true</code> \u2014 <code>__init__</code> docstrings are allowed.</li> <li><code>skip-checking-raises = true</code> \u2014 <code>Raises:</code> sections are descriptive and are not required to map to literal <code>raise</code> statements.</li> <li><code>check-class-attributes = false</code> \u2014 <code>Attributes:</code> sections document instance attributes without class-level annotations.</li> </ul>"},{"location":"05_development/04_mcp_guide/","title":"MCP Guide","text":"<p>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.</p>"},{"location":"05_development/04_mcp_guide/#building-the-bundle","title":"Building the bundle","text":"<pre><code>doc-forge build --mcp --module docforge\n</code></pre> <p>This writes structured JSON into <code>docs/mcp/</code>:</p> <ul> <li><code>index.json</code> \u2014 project metadata and module count</li> <li><code>nav.json</code> \u2014 module list with <code>docs://modules/{module}</code> resource URIs</li> <li><code>modules/{dotted.path}.json</code> \u2014 per-module serialized documentation</li> </ul>"},{"location":"05_development/04_mcp_guide/#serving-the-bundle","title":"Serving the bundle","text":"<pre><code>doc-forge serve --mcp --module docforge\n</code></pre> <p>The <code>MCPServer</code> (in <code>docforge/servers/mcp_server.py</code>) exposes:</p> Resource Description <code>docs://index</code> Project metadata <code>docs://nav</code> Navigation structure <code>docs://modules/{module}</code> Individual module documentation <p>The server also registers a single diagnostic tool, <code>ping</code>, and is read-only. Missing resources are returned as structured error dictionaries rather than exceptions. The default transport is <code>streamable-http</code>; <code>stdio</code> and <code>sse</code> are supported via <code>MCPServer.run</code>.</p>"},{"location":"05_development/04_mcp_guide/#bundle-contents","title":"Bundle contents","text":"<p>Each module resource contains:</p> <ul> <li><code>path</code> \u2014 dotted module path</li> <li><code>docstring</code> \u2014 the raw GSDFC module docstring</li> <li><code>objects</code> \u2014 a recursive mapping of public symbols with <code>name</code>, <code>kind</code>, <code>path</code>, <code>signature</code>, and <code>docstring</code>, plus nested <code>members</code></li> </ul> <p>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 <code>modules/docforge.json</code> via the <code>docforge/__init__.py</code> package docstring, making the bundle self-documenting.</p>"}]} |