docs(wiki): align wiki structure with Aetoskia AGENTS.md guidelines

- Renamed `02_architecture.md` to `02_components.md` to match the standard component page naming convention.
- Updated `docs/mkdocs.wiki.yml` to reflect renamed pages and fix navigation label acronym casing (GSDFC, MCP, MkDocs).
- Updated `index.md` to include the mandatory doc model blockquote, standardize section headers with emojis, and accurately map the `Documentation Structure` table to the navigation menu.
- Standardized all wiki pages (`01_overview.md`, `02_components.md`, `03_conventions.md`, `04_iterative_workflow.md`, and `05_development/*`) by:
  - Adding horizontal rules (`---`) between major sections.
  - Applying emoji-prefixed H2 headings for recognizable section types.
  - Appending `## Related` or `## ➡️ Read Next` footers with standard relative cross-links.
  - Adjusting H1 headers to match guide anatomy (e.g., `# Library Overview` on the overview page).
This commit is contained in:
2026-09-14 23:30:51 +05:30
parent 37f2fbf4b9
commit 48631b57c5
12 changed files with 896 additions and 701 deletions

View File

@@ -12,7 +12,7 @@
<link rel="prev" href=".."> <link rel="prev" href="..">
<link rel="next" href="../02_architecture/"> <link rel="next" href="../02_components/">
<link rel="icon" href="../assets/images/favicon.png"> <link rel="icon" href="../assets/images/favicon.png">
@@ -72,7 +72,7 @@
<div data-md-component="skip"> <div data-md-component="skip">
<a href="#overview" class="md-skip"> <a href="#library-overview" class="md-skip">
Skip to content Skip to content
</a> </a>
@@ -226,13 +226,13 @@
<li class="md-tabs__item"> <li class="md-tabs__item">
<a href="../02_architecture/" class="md-tabs__link"> <a href="../02_components/" class="md-tabs__link">
Architecture Components
</a> </a>
</li> </li>
@@ -413,27 +413,36 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#what-it-generates" class="md-nav__link"> <a href="#which-build-should-you-use" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
What it generates 🧭 Which Build Should You Use?
</span> </span>
</a> </a>
</li> </li>
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#per-kind-mkdocs-builds" class="md-nav__link"> <a href="#architecture" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Per-kind MkDocs builds 🏗️ Architecture
</span> </span>
</a> </a>
</li> </li>
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#mcp-bundle" class="md-nav__link"> <a href="#lifecycle-rules" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
MCP bundle 🔄 Lifecycle Rules
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#read-next" class="md-nav__link">
<span class="md-ellipsis">
➡️ Read Next
</span> </span>
</a> </a>
@@ -454,12 +463,12 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="../02_architecture/" class="md-nav__link"> <a href="../02_components/" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Architecture Components
</span> </span>
@@ -628,7 +637,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Gsdfc Guide GSDFC Guide
</span> </span>
@@ -651,7 +660,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mcp Guide MCP Guide
</span> </span>
@@ -674,7 +683,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mkdocs Configs MkDocs Configs
</span> </span>
@@ -708,11 +717,12 @@
<h1 id="overview">Overview</h1> <h1 id="library-overview">Library Overview</h1>
<p><code>docforge</code> turns GSDFC-compliant Python docstrings into maintainable reference <p><code>docforge</code> turns GSDFC-compliant Python docstrings into maintainable reference
documentation. It never edits source docstrings; it reads them, renders them, documentation. It never edits source docstrings; it reads them, renders them,
and assembles documentation sites from all available material.</p> and assembles documentation sites from all available material.</p>
<h2 id="what-it-generates">What it generates</h2> <hr />
<h2 id="which-build-should-you-use">🧭 Which Build Should You Use?</h2>
<table> <table>
<thead> <thead>
<tr> <tr>
@@ -744,7 +754,8 @@ and assembles documentation sites from all available material.</p>
</tr> </tr>
</tbody> </tbody>
</table> </table>
<h2 id="per-kind-mkdocs-builds">Per-kind MkDocs builds</h2> <hr />
<h2 id="architecture">🏗️ Architecture</h2>
<p>Each enabled site kind produces its own MkDocs configuration and build:</p> <p>Each enabled site kind produces its own MkDocs configuration and build:</p>
<ol> <ol>
<li><code>--mkdocs</code> (lib) writes <code>docs/mkdocs.lib.yml</code> and builds <code>site/lib/</code>.</li> <li><code>--mkdocs</code> (lib) writes <code>docs/mkdocs.lib.yml</code> and builds <code>site/lib/</code>.</li>
@@ -754,10 +765,16 @@ and assembles documentation sites from all available material.</p>
<p>Every site is self-contained (own theme assets and search index) with <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 navigation derived or scoped to that kind. Hand-written wiki content is never
overwritten or regenerated — only its navigation is derived automatically.</p> overwritten or regenerated — only its navigation is derived automatically.</p>
<h2 id="mcp-bundle">MCP bundle</h2> <hr />
<h2 id="lifecycle-rules">🔄 Lifecycle Rules</h2>
<p><code>docs/mcp/**</code> is a self-contained, machine-readable reference generated from <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> docforge's own GSDFC docstrings. <code>doc-forge serve --mcp --module docforge</code>
serves it over MCP. See the <a href="../05_development/04_mcp_guide/">MCP Guide</a>.</p> serves it over MCP. See the <a href="../05_development/04_mcp_guide/">MCP Guide</a>.</p>
<hr />
<h2 id="read-next">➡️ Read Next</h2>
<ul>
<li><a href="../02_components/">02 – Components</a> · <a href="../03_conventions/">03 – Conventions</a></li>
</ul>

View File

@@ -20,7 +20,7 @@
<title>Architecture - doc-forge</title> <title>Components - doc-forge</title>
@@ -72,7 +72,7 @@
<div data-md-component="skip"> <div data-md-component="skip">
<a href="#architecture" class="md-skip"> <a href="#components" class="md-skip">
Skip to content Skip to content
</a> </a>
@@ -106,7 +106,7 @@
<div class="md-header__topic" data-md-component="header-topic"> <div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis"> <span class="md-ellipsis">
Architecture Components
</span> </span>
</div> </div>
@@ -232,7 +232,7 @@
Architecture Components
</a> </a>
</li> </li>
@@ -399,7 +399,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Architecture Components
</span> </span>
@@ -412,7 +412,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Architecture Components
</span> </span>
@@ -435,45 +435,54 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#loaders-models" class="md-nav__link"> <a href="#1-loaders-models" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Loaders → Models 1. Loaders &amp; Models
</span> </span>
</a> </a>
</li> </li>
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#navigation" class="md-nav__link"> <a href="#2-navigation" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Navigation 2. Navigation
</span> </span>
</a> </a>
</li> </li>
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#renderers" class="md-nav__link"> <a href="#3-renderers" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Renderers 3. Renderers
</span> </span>
</a> </a>
</li> </li>
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#servers" class="md-nav__link"> <a href="#4-servers" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Servers 4. Servers
</span> </span>
</a> </a>
</li> </li>
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#cli" class="md-nav__link"> <a href="#5-cli" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
CLI 5. CLI
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#related" class="md-nav__link">
<span class="md-ellipsis">
Related
</span> </span>
</a> </a>
@@ -646,7 +655,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Gsdfc Guide GSDFC Guide
</span> </span>
@@ -669,7 +678,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mcp Guide MCP Guide
</span> </span>
@@ -692,7 +701,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mkdocs Configs MkDocs Configs
</span> </span>
@@ -726,30 +735,35 @@
<h1 id="architecture">Architecture</h1> <h1 id="components">Components</h1>
<p><code>docforge</code> is split into four horizontal layers. Everything flows top to <p><code>docforge</code> is split into four horizontal layers. Everything flows top to
bottom through the CLI.</p> bottom through the CLI.</p>
<h2 id="loaders-models">Loaders → Models</h2> <hr />
<h2 id="1-loaders-models">1. Loaders &amp; Models</h2>
<p>The <code>docforge/loaders</code> package wraps <code>griffe</code> to extract modules, functions, <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 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> the object model under <code>docforge/models</code> (<code>Project</code>, <code>Module</code>, <code>DocObject</code>).</p>
<h2 id="navigation">Navigation</h2> <hr />
<h2 id="2-navigation">2. Navigation</h2>
<p><code>docforge/nav</code> parses <code>docforge.nav.yml</code> specs (<code>NavSpec</code>, <code>Resolver</code>, and the <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 MkDocs nav emitter) and, since the wiki kind, derives wiki navigation from the
file structure via <code>build_wiki_nav</code>.</p> file structure via <code>build_wiki_nav</code>.</p>
<h2 id="renderers">Renderers</h2> <hr />
<h2 id="3-renderers">3. Renderers</h2>
<p><code>docforge/renderers</code> turn model data into artifacts:</p> <p><code>docforge/renderers</code> turn model data into artifacts:</p>
<ul> <ul>
<li><code>MkDocsRenderer</code> → <code>docs/lib/**</code> reference markdown</li> <li><code>MkDocsRenderer</code> → <code>docs/lib/**</code> reference markdown</li>
<li><code>MCPRenderer</code> → <code>docs/mcp/**</code> structured documentation</li> <li><code>MCPRenderer</code> → <code>docs/mcp/**</code> structured documentation</li>
</ul> </ul>
<h2 id="servers">Servers</h2> <hr />
<h2 id="4-servers">4. Servers</h2>
<p><code>docforge/servers</code> serves generated artifacts over live protocols:</p> <p><code>docforge/servers</code> serves generated artifacts over live protocols:</p>
<ul> <ul>
<li><code>MCPServer</code> → serves a pre-generated <code>docs/mcp/**</code> bundle through MCP <li><code>MCPServer</code> → 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> resources (<code>docs://index</code>, <code>docs://nav</code>, <code>docs://modules/{module}</code>)</li>
</ul> </ul>
<h2 id="cli">CLI</h2> <hr />
<h2 id="5-cli">5. CLI</h2>
<p><code>docforge/cli</code> wires it all together:</p> <p><code>docforge/cli</code> wires it all together:</p>
<ul> <ul>
<li><code>commands.py</code> — the <code>build</code> command and its <code>--mkdocs</code> / <code>--api</code> / <code>--wiki</code> <li><code>commands.py</code> — the <code>build</code> command and its <code>--mkdocs</code> / <code>--api</code> / <code>--wiki</code>
@@ -758,6 +772,11 @@ file structure via <code>build_wiki_nav</code>.</p>
with navigation re-rooted to each kind's <code>docs_dir</code></li> with navigation re-rooted to each kind's <code>docs_dir</code></li>
<li><code>api_utils.py</code> — OpenAPI loading and API docs generation</li> <li><code>api_utils.py</code> — OpenAPI loading and API docs generation</li>
</ul> </ul>
<hr />
<h2 id="related">Related</h2>
<ul>
<li><a href="../01_overview/">01 – Overview</a> · <a href="../03_conventions/">03 – Conventions</a></li>
</ul>

View File

@@ -9,7 +9,7 @@
<link rel="prev" href="../02_architecture/"> <link rel="prev" href="../02_components/">
<link rel="next" href="../04_iterative_workflow/"> <link rel="next" href="../04_iterative_workflow/">
@@ -224,13 +224,13 @@
<li class="md-tabs__item"> <li class="md-tabs__item">
<a href="../02_architecture/" class="md-tabs__link"> <a href="../02_components/" class="md-tabs__link">
Architecture Components
</a> </a>
</li> </li>
@@ -385,12 +385,12 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="../02_architecture/" class="md-nav__link"> <a href="../02_components/" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Architecture Components
</span> </span>
@@ -490,6 +490,15 @@
</span> </span>
</a> </a>
</li>
<li class="md-nav__item">
<a href="#related" class="md-nav__link">
<span class="md-ellipsis">
Related
</span>
</a>
</li> </li>
</ul> </ul>
@@ -637,7 +646,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Gsdfc Guide GSDFC Guide
</span> </span>
@@ -660,7 +669,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mcp Guide MCP Guide
</span> </span>
@@ -683,7 +692,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mkdocs Configs MkDocs Configs
</span> </span>
@@ -718,6 +727,7 @@
<h1 id="conventions">Conventions</h1> <h1 id="conventions">Conventions</h1>
<hr />
<h2 id="gsdfc-docstrings">GSDFC docstrings</h2> <h2 id="gsdfc-docstrings">GSDFC docstrings</h2>
<p>All documented source uses the Google-Styled Doc-Forge Convention (GSDFC): <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 <code>Args:</code>, <code>Returns:</code>, <code>Raises:</code>, and <code>Attributes:</code> sections with properly typed
@@ -726,32 +736,40 @@ signatures.</p>
package docstring, which is exported verbatim into package docstring, which is exported verbatim into
<code>docs/mcp/modules/docforge.json</code>, so the MCP bundle is self-documenting.</p> <code>docs/mcp/modules/docforge.json</code>, so the MCP bundle is self-documenting.</p>
<p>Key rules:</p> <p>Key rules:</p>
<ul> <ol>
<li>Use parenthesized types in prose entries (<code>name (Type):</code>) that match the <li>Use parenthesized types in prose entries (<code>name (Type):</code>) that match the
signature types.</li> signature types.</li>
<li>Use <code># Summary</code>, <code># Examples</code>, and <code># Notes</code> sections at module level.</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> <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> sections at function and method level.</li>
<li>Always update the matching <code>.pyi</code> stub alongside the <code>.py</code> implementation.</li> <li>Always update the matching <code>.pyi</code> stub alongside the <code>.py</code> implementation.</li>
</ul> </ol>
<hr />
<h2 id="pyi-stubs"><code>.pyi</code> stubs</h2> <h2 id="pyi-stubs"><code>.pyi</code> stubs</h2>
<p>Every module ships a matching <code>.pyi</code> stub kept in sync with the <code>.py</code> <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> implementation. When signatures change, update both files.</p>
<hr />
<h2 id="wiki-pages">Wiki pages</h2> <h2 id="wiki-pages">Wiki pages</h2>
<ul> <ol>
<li>Hand-written markdown lives in <code>docs/wiki/**</code> and is never generated.</li> <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>File names use a numeric prefix: <code>01_overview.md</code>, <code>02_components.md</code>.</li>
<li>Nested directories become nested navigation groups: <li>Nested directories become nested navigation groups:
<code>05_development/01_environment.md</code> → group <em>Development</em>.</li> <code>05_development/01_environment.md</code> → group <em>Development</em>.</li>
<li><code>index.md</code> is the site <code>Home</code> at the root, and a section root inside a <li><code>index.md</code> is the site <code>Home</code> at the root, and a section root inside a
directory.</li> directory.</li>
<li>Navigation labels are derived by stripping the numeric prefix and applying <li>Navigation labels are derived by stripping the numeric prefix and applying
title case on the remaining words.</li> title case on the remaining words.</li>
</ul> </ol>
<hr />
<h2 id="templates">Templates</h2> <h2 id="templates">Templates</h2>
<p>MkDocs config fragments live in <code>docforge/templates</code>. The <code>mkdocs.wiki.yml</code> <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 fragment carries only the <code>search</code> plugin, since wiki pages contain no
mkdocstrings directives.</p> mkdocstrings directives.</p>
<hr />
<h2 id="related">Related</h2>
<ul>
<li><a href="../02_components/">02 – Components</a> · <a href="../04_iterative_workflow/">04 – Iterative Workflow</a></li>
</ul>

View File

@@ -224,13 +224,13 @@
<li class="md-tabs__item"> <li class="md-tabs__item">
<a href="../02_architecture/" class="md-tabs__link"> <a href="../02_components/" class="md-tabs__link">
Architecture Components
</a> </a>
</li> </li>
@@ -385,12 +385,12 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="../02_architecture/" class="md-nav__link"> <a href="../02_components/" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Architecture Components
</span> </span>
@@ -481,7 +481,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#build-commands" class="md-nav__link"> <a href="#build-commands" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Build commands 🚀 Build commands
</span> </span>
</a> </a>
@@ -490,7 +490,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#what-a-build-does" class="md-nav__link"> <a href="#what-a-build-does" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
What a build does 🔄 What a build does
</span> </span>
</a> </a>
@@ -499,7 +499,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#explore-the-sites" class="md-nav__link"> <a href="#explore-the-sites" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Explore the sites 🧭 Explore the sites
</span> </span>
</a> </a>
@@ -508,7 +508,16 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#serve-the-mcp-bundle" class="md-nav__link"> <a href="#serve-the-mcp-bundle" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Serve the MCP bundle 📦 Serve the MCP bundle
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#related" class="md-nav__link">
<span class="md-ellipsis">
Related
</span> </span>
</a> </a>
@@ -637,7 +646,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Gsdfc Guide GSDFC Guide
</span> </span>
@@ -660,7 +669,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mcp Guide MCP Guide
</span> </span>
@@ -683,7 +692,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mkdocs Configs MkDocs Configs
</span> </span>
@@ -719,7 +728,8 @@
<h1 id="iterative-workflow">Iterative Workflow</h1> <h1 id="iterative-workflow">Iterative Workflow</h1>
<p>A docs build runs through the CLI in a single pass.</p> <p>A docs build runs through the CLI in a single pass.</p>
<h2 id="build-commands">Build commands</h2> <hr />
<h2 id="build-commands">🚀 Build commands</h2>
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1"> 1</a></span> <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1"> 1</a></span>
<span class="normal"><a href="#__codelineno-0-2"> 2</a></span> <span class="normal"><a href="#__codelineno-0-2"> 2</a></span>
<span class="normal"><a href="#__codelineno-0-3"> 3</a></span> <span class="normal"><a href="#__codelineno-0-3"> 3</a></span>
@@ -742,7 +752,8 @@
</span><span id="__span-0-10"><a id="__codelineno-0-10" name="__codelineno-0-10"></a><span class="c1"># MCP structured bundle</span> </span><span id="__span-0-10"><a id="__codelineno-0-10" name="__codelineno-0-10"></a><span class="c1"># MCP structured bundle</span>
</span><span id="__span-0-11"><a id="__codelineno-0-11" name="__codelineno-0-11"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--mcp<span class="w"> </span>--module<span class="w"> </span>docforge </span><span id="__span-0-11"><a id="__codelineno-0-11" name="__codelineno-0-11"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--mcp<span class="w"> </span>--module<span class="w"> </span>docforge
</span></code></pre></div></td></tr></table></div> </span></code></pre></div></td></tr></table></div>
<h2 id="what-a-build-does">What a build does</h2> <hr />
<h2 id="what-a-build-does">🔄 What a build does</h2>
<ol> <ol>
<li>Validates the requested modes (<code>--mkdocs</code>, <code>--api</code>, <code>--wiki</code>, <code>--mcp</code>).</li> <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 library sources under <code>docs/lib/**</code> with <code>MkDocsRenderer</code>.</li>
@@ -753,7 +764,8 @@
<li>Runs <code>mkdocs build</code> once per config, emitting self-contained sites <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> <code>site/lib/</code>, <code>site/api/</code>, and <code>site/wiki/</code>.</li>
</ol> </ol>
<h2 id="explore-the-sites">Explore the sites</h2> <hr />
<h2 id="explore-the-sites">🧭 Explore the sites</h2>
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-1-1">1</a></span> <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-1-1">1</a></span>
<span class="normal"><a href="#__codelineno-1-2">2</a></span> <span class="normal"><a href="#__codelineno-1-2">2</a></span>
<span class="normal"><a href="#__codelineno-1-3">3</a></span> <span class="normal"><a href="#__codelineno-1-3">3</a></span>
@@ -766,11 +778,17 @@
</span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5"></a><span class="c1"># or target any config directly:</span> </span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5"></a><span class="c1"># or target any config directly:</span>
</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--mkdocs<span class="w"> </span>--mkdocs-yml<span class="w"> </span>docs/mkdocs.wiki.yml </span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--mkdocs<span class="w"> </span>--mkdocs-yml<span class="w"> </span>docs/mkdocs.wiki.yml
</span></code></pre></div></td></tr></table></div> </span></code></pre></div></td></tr></table></div>
<h2 id="serve-the-mcp-bundle">Serve the MCP bundle</h2> <hr />
<h2 id="serve-the-mcp-bundle">📦 Serve the MCP bundle</h2>
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-2-1">1</a></span> <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-2-1">1</a></span>
<span class="normal"><a href="#__codelineno-2-2">2</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--mcp<span class="w"> </span>--module<span class="w"> </span>docforge <span class="normal"><a href="#__codelineno-2-2">2</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--mcp<span class="w"> </span>--module<span class="w"> </span>docforge
</span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--mcp<span class="w"> </span>--module<span class="w"> </span>docforge </span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--mcp<span class="w"> </span>--module<span class="w"> </span>docforge
</span></code></pre></div></td></tr></table></div> </span></code></pre></div></td></tr></table></div>
<hr />
<h2 id="related">Related</h2>
<ul>
<li><a href="../03_conventions/">03 – Conventions</a> · <a href="../05_development/01_environment/">01 – Environment</a></li>
</ul>

View File

@@ -224,13 +224,13 @@
<li class="md-tabs__item"> <li class="md-tabs__item">
<a href="../../02_architecture/" class="md-tabs__link"> <a href="../../02_components/" class="md-tabs__link">
Architecture Components
</a> </a>
</li> </li>
@@ -385,12 +385,12 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="../../02_architecture/" class="md-nav__link"> <a href="../../02_components/" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Architecture Components
</span> </span>
@@ -563,7 +563,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#create-the-environment" class="md-nav__link"> <a href="#create-the-environment" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Create the environment 🚀 Create the environment
</span> </span>
</a> </a>
@@ -572,7 +572,16 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#dependencies" class="md-nav__link"> <a href="#dependencies" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Dependencies 📦 Dependencies
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#related" class="md-nav__link">
<span class="md-ellipsis">
Related
</span> </span>
</a> </a>
@@ -622,7 +631,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Gsdfc Guide GSDFC Guide
</span> </span>
@@ -645,7 +654,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mcp Guide MCP Guide
</span> </span>
@@ -668,7 +677,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mkdocs Configs MkDocs Configs
</span> </span>
@@ -703,7 +712,8 @@
<h1 id="environment-setup">Environment Setup</h1> <h1 id="environment-setup">Environment Setup</h1>
<h2 id="create-the-environment">Create the environment</h2> <hr />
<h2 id="create-the-environment">🚀 Create the environment</h2>
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span> <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span>
<span class="normal"><a href="#__codelineno-0-2">2</a></span> <span class="normal"><a href="#__codelineno-0-2">2</a></span>
<span class="normal"><a href="#__codelineno-0-3">3</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a>python<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>.venv <span class="normal"><a href="#__codelineno-0-3">3</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a>python<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>.venv
@@ -711,7 +721,8 @@
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3"></a>pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span>. </span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3"></a>pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span>.
</span></code></pre></div></td></tr></table></div> </span></code></pre></div></td></tr></table></div>
<p>Requires Python 3.10+ (per <code>pyproject.toml</code>).</p> <p>Requires Python 3.10+ (per <code>pyproject.toml</code>).</p>
<h2 id="dependencies">Dependencies</h2> <hr />
<h2 id="dependencies">📦 Dependencies</h2>
<p>Development extras include:</p> <p>Development extras include:</p>
<ul> <ul>
<li><code>pytest</code>, <code>pytest-cov</code> — test suite and coverage</li> <li><code>pytest</code>, <code>pytest-cov</code> — test suite and coverage</li>
@@ -720,6 +731,11 @@
<li><code>mypy</code> — strict typing checks</li> <li><code>mypy</code> — strict typing checks</li>
<li><code>pydoclint</code> — docstring ↔ signature consistency checks</li> <li><code>pydoclint</code> — docstring ↔ signature consistency checks</li>
</ul> </ul>
<hr />
<h2 id="related">Related</h2>
<ul>
<li><a href="../../04_iterative_workflow/">04 – Iterative Workflow</a> · <a href="../02_quality_gates/">02 – Quality Gates</a></li>
</ul>

View File

@@ -224,13 +224,13 @@
<li class="md-tabs__item"> <li class="md-tabs__item">
<a href="../../02_architecture/" class="md-tabs__link"> <a href="../../02_components/" class="md-tabs__link">
Architecture Components
</a> </a>
</li> </li>
@@ -385,12 +385,12 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="../../02_architecture/" class="md-nav__link"> <a href="../../02_components/" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Architecture Components
</span> </span>
@@ -583,10 +583,28 @@
</label> </label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#commands" class="md-nav__link">
<span class="md-ellipsis">
🚀 Commands
</span>
</a>
</li>
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#test-layout" class="md-nav__link"> <a href="#test-layout" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Test layout 📁 Test layout
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#related" class="md-nav__link">
<span class="md-ellipsis">
Related
</span> </span>
</a> </a>
@@ -613,7 +631,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Gsdfc Guide GSDFC Guide
</span> </span>
@@ -636,7 +654,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mcp Guide MCP Guide
</span> </span>
@@ -659,7 +677,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mkdocs Configs MkDocs Configs
</span> </span>
@@ -695,6 +713,8 @@
<h1 id="quality-gates">Quality Gates</h1> <h1 id="quality-gates">Quality Gates</h1>
<p>Run all checks before pushing:</p> <p>Run all checks before pushing:</p>
<hr />
<h2 id="commands">🚀 Commands</h2>
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span> <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span>
<span class="normal"><a href="#__codelineno-0-2">2</a></span> <span class="normal"><a href="#__codelineno-0-2">2</a></span>
<span class="normal"><a href="#__codelineno-0-3">3</a></span> <span class="normal"><a href="#__codelineno-0-3">3</a></span>
@@ -705,7 +725,8 @@
</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4"></a>.venv<span class="se">\S</span>cripts<span class="se">\p</span>ython.exe<span class="w"> </span>-m<span class="w"> </span>mypy<span class="w"> </span>docforge </span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4"></a>.venv<span class="se">\S</span>cripts<span class="se">\p</span>ython.exe<span class="w"> </span>-m<span class="w"> </span>mypy<span class="w"> </span>docforge
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5"></a>.venv<span class="se">\S</span>cripts<span class="se">\p</span>ydoclint.exe<span class="w"> </span>docforge </span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5"></a>.venv<span class="se">\S</span>cripts<span class="se">\p</span>ydoclint.exe<span class="w"> </span>docforge
</span></code></pre></div></td></tr></table></div> </span></code></pre></div></td></tr></table></div>
<h2 id="test-layout">Test layout</h2> <hr />
<h2 id="test-layout">📁 Test layout</h2>
<table> <table>
<thead> <thead>
<tr> <tr>
@@ -731,6 +752,11 @@
<p>CLI tests use the <code>cli_runner</code> fixture with <code>mock_mkdocs_build</code> and <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 <code>mock_mkdocs_load_config</code> so they exercise the full flow without invoking a
real MkDocs build.</p> real MkDocs build.</p>
<hr />
<h2 id="related">Related</h2>
<ul>
<li><a href="../01_environment/">01 – Environment</a> · <a href="../03_gsdfc_guide/">03 – GSDFC Guide</a></li>
</ul>

View File

@@ -20,7 +20,7 @@
<title>Gsdfc Guide - doc-forge</title> <title>GSDFC Guide - doc-forge</title>
@@ -106,7 +106,7 @@
<div class="md-header__topic" data-md-component="header-topic"> <div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis"> <span class="md-ellipsis">
Gsdfc Guide GSDFC Guide
</span> </span>
</div> </div>
@@ -224,13 +224,13 @@
<li class="md-tabs__item"> <li class="md-tabs__item">
<a href="../../02_architecture/" class="md-tabs__link"> <a href="../../02_components/" class="md-tabs__link">
Architecture Components
</a> </a>
</li> </li>
@@ -385,12 +385,12 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="../../02_architecture/" class="md-nav__link"> <a href="../../02_components/" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Architecture Components
</span> </span>
@@ -571,7 +571,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Gsdfc Guide GSDFC Guide
</span> </span>
@@ -584,7 +584,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Gsdfc Guide GSDFC Guide
</span> </span>
@@ -609,7 +609,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#overview" class="md-nav__link"> <a href="#overview" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Overview 🧭 Overview
</span> </span>
</a> </a>
@@ -618,7 +618,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#module-docstrings" class="md-nav__link"> <a href="#module-docstrings" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Module docstrings 📦 Module docstrings
</span> </span>
</a> </a>
@@ -627,7 +627,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#class-docstrings" class="md-nav__link"> <a href="#class-docstrings" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Class docstrings 📦 Class docstrings
</span> </span>
</a> </a>
@@ -636,7 +636,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#function-and-method-docstrings" class="md-nav__link"> <a href="#function-and-method-docstrings" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Function and method docstrings 📦 Function and method docstrings
</span> </span>
</a> </a>
@@ -645,7 +645,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#property-docstrings" class="md-nav__link"> <a href="#property-docstrings" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Property docstrings 📦 Property docstrings
</span> </span>
</a> </a>
@@ -654,7 +654,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#example" class="md-nav__link"> <a href="#example" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Example 🚀 Example
</span> </span>
</a> </a>
@@ -663,7 +663,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#keeping-stubs-in-sync" class="md-nav__link"> <a href="#keeping-stubs-in-sync" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Keeping stubs in sync 🔄 Keeping stubs in sync
</span> </span>
</a> </a>
@@ -672,7 +672,16 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#enforcement" class="md-nav__link"> <a href="#enforcement" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Enforcement 🛡️ Enforcement
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#related" class="md-nav__link">
<span class="md-ellipsis">
Related
</span> </span>
</a> </a>
@@ -699,7 +708,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mcp Guide MCP Guide
</span> </span>
@@ -722,7 +731,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mkdocs Configs MkDocs Configs
</span> </span>
@@ -761,7 +770,8 @@
in the <code>docforge/__init__.py</code> package docstring. It describes how to write 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 docstrings that render correctly in MkDocs and stay machine-parseable by
doc-forge, MkDocs, and MCP clients.</p> doc-forge, MkDocs, and MCP clients.</p>
<h2 id="overview">Overview</h2> <hr />
<h2 id="overview">🧭 Overview</h2>
<ul> <ul>
<li>Docstrings are the single source of truth.</li> <li>Docstrings are the single source of truth.</li>
<li><code>doc-forge</code> compiles docstrings but never rewrites them.</li> <li><code>doc-forge</code> compiles docstrings but never rewrites them.</li>
@@ -769,7 +779,8 @@ doc-forge, MkDocs, and MCP clients.</p>
<li>Type hints live in signatures; prose entries repeat the type in <li>Type hints live in signatures; prose entries repeat the type in
parentheses and must match the signature.</li> parentheses and must match the signature.</li>
</ul> </ul>
<h2 id="module-docstrings">Module docstrings</h2> <hr />
<h2 id="module-docstrings">📦 Module docstrings</h2>
<p>Modules use Markdown headings and <code>---</code> separators.</p> <p>Modules use Markdown headings and <code>---</code> separators.</p>
<p>Recommended sections:</p> <p>Recommended sections:</p>
<ul> <ul>
@@ -777,7 +788,8 @@ doc-forge, MkDocs, and MCP clients.</p>
<li><code># Examples</code> — a representative usage snippet</li> <li><code># Examples</code> — a representative usage snippet</li>
<li><code># Notes</code> — guarantees, lifecycle, and thread-safety notes</li> <li><code># Notes</code> — guarantees, lifecycle, and thread-safety notes</li>
</ul> </ul>
<h2 id="class-docstrings">Class docstrings</h2> <hr />
<h2 id="class-docstrings">📦 Class docstrings</h2>
<p>Recommended sections, in order:</p> <p>Recommended sections, in order:</p>
<ul> <ul>
<li>summary line describing responsibility</li> <li>summary line describing responsibility</li>
@@ -785,7 +797,8 @@ doc-forge, MkDocs, and MCP clients.</p>
<li><code>Notes:</code> — grouped subsections such as <strong>Guarantees</strong>, <strong>Lifecycle</strong></li> <li><code>Notes:</code> — grouped subsections such as <strong>Guarantees</strong>, <strong>Lifecycle</strong></li>
<li><code>Example:</code> — indented <code>python</code> code block</li> <li><code>Example:</code> — indented <code>python</code> code block</li>
</ul> </ul>
<h2 id="function-and-method-docstrings">Function and method docstrings</h2> <hr />
<h2 id="function-and-method-docstrings">📦 Function and method docstrings</h2>
<p>Recommended section order:</p> <p>Recommended section order:</p>
<ol> <ol>
<li><code>Args:</code></li> <li><code>Args:</code></li>
@@ -805,10 +818,12 @@ doc-forge, MkDocs, and MCP clients.</p>
<li>Fenced <code>python</code> blocks are allowed inside <code>Example:</code> sections, indented <li>Fenced <code>python</code> blocks are allowed inside <code>Example:</code> sections, indented
four spaces.</li> four spaces.</li>
</ul> </ul>
<h2 id="property-docstrings">Property docstrings</h2> <hr />
<h2 id="property-docstrings">📦 Property docstrings</h2>
<p>Properties document their return values with a <code>Returns:</code> section and, when <p>Properties document their return values with a <code>Returns:</code> section and, when
meaningful, an <code>Example:</code>.</p> meaningful, an <code>Example:</code>.</p>
<h2 id="example">Example</h2> <hr />
<h2 id="example">🚀 Example</h2>
<div class="language-python highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1"> 1</a></span> <div class="language-python highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1"> 1</a></span>
<span class="normal"><a href="#__codelineno-0-2"> 2</a></span> <span class="normal"><a href="#__codelineno-0-2"> 2</a></span>
<span class="normal"><a href="#__codelineno-0-3"> 3</a></span> <span class="normal"><a href="#__codelineno-0-3"> 3</a></span>
@@ -863,11 +878,13 @@ meaningful, an <code>Example:</code>.</p>
</span><span id="__span-0-26"><a id="__codelineno-0-26" name="__codelineno-0-26"></a><span class="sd"> ```</span> </span><span id="__span-0-26"><a id="__codelineno-0-26" name="__codelineno-0-26"></a><span class="sd"> ```</span>
</span><span id="__span-0-27"><a id="__codelineno-0-27" name="__codelineno-0-27"></a><span class="sd"> &quot;&quot;&quot;</span> </span><span id="__span-0-27"><a id="__codelineno-0-27" name="__codelineno-0-27"></a><span class="sd"> &quot;&quot;&quot;</span>
</span></code></pre></div></td></tr></table></div> </span></code></pre></div></td></tr></table></div>
<h2 id="keeping-stubs-in-sync">Keeping stubs in sync</h2> <hr />
<h2 id="keeping-stubs-in-sync">🔄 Keeping stubs in sync</h2>
<p>Every <code>.py</code> module ships a matching <code>.pyi</code> stub. When a signature or a public <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 symbol changes, update both files. Signature annotations in the stub must
match the implementation.</p> match the implementation.</p>
<h2 id="enforcement">Enforcement</h2> <hr />
<h2 id="enforcement">🛡️ Enforcement</h2>
<p><code>pydoclint</code> (Google style) runs in CI and verifies that <code>Args:</code>/<code>Returns:</code> <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> sections match function signatures, including types.</p>
<ul> <ul>
@@ -877,6 +894,11 @@ sections match function signatures, including types.</p>
<li><code>check-class-attributes = false</code> — <code>Attributes:</code> sections document instance <li><code>check-class-attributes = false</code> — <code>Attributes:</code> sections document instance
attributes without class-level annotations.</li> attributes without class-level annotations.</li>
</ul> </ul>
<hr />
<h2 id="related">Related</h2>
<ul>
<li><a href="../02_quality_gates/">02 – Quality Gates</a> · <a href="../04_mcp_guide/">04 – MCP Guide</a></li>
</ul>

View File

@@ -20,7 +20,7 @@
<title>Mcp Guide - doc-forge</title> <title>MCP Guide - doc-forge</title>
@@ -106,7 +106,7 @@
<div class="md-header__topic" data-md-component="header-topic"> <div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis"> <span class="md-ellipsis">
Mcp Guide MCP Guide
</span> </span>
</div> </div>
@@ -224,13 +224,13 @@
<li class="md-tabs__item"> <li class="md-tabs__item">
<a href="../../02_architecture/" class="md-tabs__link"> <a href="../../02_components/" class="md-tabs__link">
Architecture Components
</a> </a>
</li> </li>
@@ -385,12 +385,12 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="../../02_architecture/" class="md-nav__link"> <a href="../../02_components/" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Architecture Components
</span> </span>
@@ -562,7 +562,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Gsdfc Guide GSDFC Guide
</span> </span>
@@ -594,7 +594,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mcp Guide MCP Guide
</span> </span>
@@ -607,7 +607,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mcp Guide MCP Guide
</span> </span>
@@ -632,7 +632,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#building-the-bundle" class="md-nav__link"> <a href="#building-the-bundle" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Building the bundle 🚀 Building the bundle
</span> </span>
</a> </a>
@@ -641,7 +641,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#serving-the-bundle" class="md-nav__link"> <a href="#serving-the-bundle" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Serving the bundle 🚀 Serving the bundle
</span> </span>
</a> </a>
@@ -650,7 +650,16 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#bundle-contents" class="md-nav__link"> <a href="#bundle-contents" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Bundle contents 📦 Bundle contents
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#related" class="md-nav__link">
<span class="md-ellipsis">
Related
</span> </span>
</a> </a>
@@ -677,7 +686,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mkdocs Configs MkDocs Configs
</span> </span>
@@ -716,7 +725,8 @@
GSDFC docstrings and serve that bundle over the Model Context Protocol (MCP). GSDFC docstrings and serve that bundle over the Model Context Protocol (MCP).
The bundle is self-contained: readers can derive the full API reference — The bundle is self-contained: readers can derive the full API reference —
signatures, docstrings, and structure — for the documented project.</p> signatures, docstrings, and structure — for the documented project.</p>
<h2 id="building-the-bundle">Building the bundle</h2> <hr />
<h2 id="building-the-bundle">🚀 Building the bundle</h2>
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--mcp<span class="w"> </span>--module<span class="w"> </span>docforge <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--mcp<span class="w"> </span>--module<span class="w"> </span>docforge
</span></code></pre></div></td></tr></table></div> </span></code></pre></div></td></tr></table></div>
<p>This writes structured JSON into <code>docs/mcp/</code>:</p> <p>This writes structured JSON into <code>docs/mcp/</code>:</p>
@@ -725,7 +735,8 @@ signatures, docstrings, and structure — for the documented project.</p>
<li><code>nav.json</code> — module list with <code>docs://modules/{module}</code> resource URIs</li> <li><code>nav.json</code> — module list with <code>docs://modules/{module}</code> resource URIs</li>
<li><code>modules/{dotted.path}.json</code> — per-module serialized documentation</li> <li><code>modules/{dotted.path}.json</code> — per-module serialized documentation</li>
</ul> </ul>
<h2 id="serving-the-bundle">Serving the bundle</h2> <hr />
<h2 id="serving-the-bundle">🚀 Serving the bundle</h2>
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-1-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--mcp<span class="w"> </span>--module<span class="w"> </span>docforge <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-1-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--mcp<span class="w"> </span>--module<span class="w"> </span>docforge
</span></code></pre></div></td></tr></table></div> </span></code></pre></div></td></tr></table></div>
<p>The <code>MCPServer</code> (in <code>docforge/servers/mcp_server.py</code>) exposes:</p> <p>The <code>MCPServer</code> (in <code>docforge/servers/mcp_server.py</code>) exposes:</p>
@@ -755,7 +766,8 @@ signatures, docstrings, and structure — for the documented project.</p>
Missing resources are returned as structured error dictionaries rather than 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 exceptions. The default transport is <code>streamable-http</code>; <code>stdio</code> and <code>sse</code> are
supported via <code>MCPServer.run</code>.</p> supported via <code>MCPServer.run</code>.</p>
<h2 id="bundle-contents">Bundle contents</h2> <hr />
<h2 id="bundle-contents">📦 Bundle contents</h2>
<p>Each module resource contains:</p> <p>Each module resource contains:</p>
<ul> <ul>
<li><code>path</code> — dotted module path</li> <li><code>path</code> — dotted module path</li>
@@ -767,6 +779,11 @@ supported via <code>MCPServer.run</code>.</p>
equals the quality of the project's GSDFC docstrings. For docforge itself, 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 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> <code>docforge/__init__.py</code> package docstring, making the bundle self-documenting.</p>
<hr />
<h2 id="related">Related</h2>
<ul>
<li><a href="../03_gsdfc_guide/">03 – GSDFC Guide</a> · <a href="../05_mkdocs_configs/">05 – MkDocs Configs</a></li>
</ul>

View File

@@ -18,7 +18,7 @@
<title>Mkdocs Configs - doc-forge</title> <title>MkDocs Configs - doc-forge</title>
@@ -104,7 +104,7 @@
<div class="md-header__topic" data-md-component="header-topic"> <div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis"> <span class="md-ellipsis">
Mkdocs Configs MkDocs Configs
</span> </span>
</div> </div>
@@ -222,13 +222,13 @@
<li class="md-tabs__item"> <li class="md-tabs__item">
<a href="../../02_architecture/" class="md-tabs__link"> <a href="../../02_components/" class="md-tabs__link">
Architecture Components
</a> </a>
</li> </li>
@@ -383,12 +383,12 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="../../02_architecture/" class="md-nav__link"> <a href="../../02_components/" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Architecture Components
</span> </span>
@@ -560,7 +560,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Gsdfc Guide GSDFC Guide
</span> </span>
@@ -583,7 +583,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mcp Guide MCP Guide
</span> </span>
@@ -615,7 +615,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mkdocs Configs MkDocs Configs
</span> </span>
@@ -628,7 +628,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mkdocs Configs MkDocs Configs
</span> </span>
@@ -653,7 +653,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#file-wins" class="md-nav__link"> <a href="#file-wins" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
File wins 📄 File wins
</span> </span>
</a> </a>
@@ -662,7 +662,7 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#templates" class="md-nav__link"> <a href="#templates" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Templates 🧩 Templates
</span> </span>
</a> </a>
@@ -671,7 +671,16 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#supported-layouts" class="md-nav__link"> <a href="#supported-layouts" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Supported layouts 🏗️ Supported layouts
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#related" class="md-nav__link">
<span class="md-ellipsis">
Related
</span> </span>
</a> </a>
@@ -714,7 +723,8 @@
repo that documents kind <code>{kind}</code> carries a config at <code>docs/mkdocs.{kind}.yml</code> repo that documents kind <code>{kind}</code> carries a config at <code>docs/mkdocs.{kind}.yml</code>
that sets <code>docs_dir</code> to the kind's source directory and <code>site_dir</code> to that sets <code>docs_dir</code> to the kind's source directory and <code>site_dir</code> to
<code>../site/{kind}</code>.</p> <code>../site/{kind}</code>.</p>
<h2 id="file-wins">File wins</h2> <hr />
<h2 id="file-wins">📄 File wins</h2>
<p><code>docs/mkdocs.{kind}.yml</code> is a repo-owned file, not a build byproduct:</p> <p><code>docs/mkdocs.{kind}.yml</code> is a repo-owned file, not a build byproduct:</p>
<ul> <ul>
<li><strong>Absent</strong> — <code>doc-forge build --{kind}</code> materializes a copy from the <li><strong>Absent</strong> — <code>doc-forge build --{kind}</code> materializes a copy from the
@@ -726,7 +736,8 @@ that sets <code>docs_dir</code> to the kind's source directory and <code>site_di
</ul> </ul>
<p>Because a present file is never rewritten, rerunning a build is a no-op for <p>Because a present file is never rewritten, rerunning a build is a no-op for
versioned configs: the working tree stays clean.</p> versioned configs: the working tree stays clean.</p>
<h2 id="templates">Templates</h2> <hr />
<h2 id="templates">🧩 Templates</h2>
<p>The built-in defaults live in <code>docforge/templates/</code>:</p> <p>The built-in defaults live in <code>docforge/templates/</code>:</p>
<table> <table>
<thead> <thead>
@@ -759,7 +770,8 @@ kind fragment, then filling in generation-time values (<code>site_name</code>,
<code>docs_dir</code>, <code>site_dir</code>, <code>nav</code>, API <code>site_description</code>/<code>site_author</code>, and the <code>docs_dir</code>, <code>site_dir</code>, <code>nav</code>, API <code>site_description</code>/<code>site_author</code>, and the
theme <code>icon</code> from <code>docforge.nav.yml</code>). Pass <code>--template &lt;path&gt;</code> to replace the theme <code>icon</code> from <code>docforge.nav.yml</code>). Pass <code>--template &lt;path&gt;</code> to replace the
built-in templates entirely.</p> built-in templates entirely.</p>
<h2 id="supported-layouts">Supported layouts</h2> <hr />
<h2 id="supported-layouts">🏗️ Supported layouts</h2>
<ul> <ul>
<li><strong>Per-kind config</strong> — the standard layout; each kind builds to <li><strong>Per-kind config</strong> — the standard layout; each kind builds to
<code>site/{kind}</code> and is served under <code>/&lt;repo&gt;/{kind}/</code>.</li> <code>site/{kind}</code> and is served under <code>/&lt;repo&gt;/{kind}/</code>.</li>
@@ -769,6 +781,11 @@ built-in templates entirely.</p>
kind to the root <code>site/</code> dir in this case.</li> kind to the root <code>site/</code> dir in this case.</li>
</ul> </ul>
<p>Commit <code>docs/mkdocs.{kind}.yml</code> so served docs are reproducible from source.</p> <p>Commit <code>docs/mkdocs.{kind}.yml</code> so served docs are reproducible from source.</p>
<hr />
<h2 id="related">Related</h2>
<ul>
<li><a href="../04_mcp_guide/">04 – MCP Guide</a></li>
</ul>

View File

@@ -215,13 +215,13 @@
<li class="md-tabs__item"> <li class="md-tabs__item">
<a href="/02_architecture/" class="md-tabs__link"> <a href="/02_components/" class="md-tabs__link">
Architecture Components
</a> </a>
</li> </li>
@@ -374,12 +374,12 @@
<li class="md-nav__item"> <li class="md-nav__item">
<a href="/02_architecture/" class="md-nav__link"> <a href="/02_components/" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
Architecture Components
</span> </span>
@@ -548,7 +548,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Gsdfc Guide GSDFC Guide
</span> </span>
@@ -571,7 +571,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mcp Guide MCP Guide
</span> </span>
@@ -594,7 +594,7 @@
<span class="md-ellipsis"> <span class="md-ellipsis">
Mkdocs Configs MkDocs Configs
</span> </span>

File diff suppressed because it is too large Load Diff

File diff suppressed because one or more lines are too long