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="next" href="../02_architecture/">
<link rel="next" href="../02_components/">
<link rel="icon" href="../assets/images/favicon.png">
@@ -72,7 +72,7 @@
<div data-md-component="skip">
<a href="#overview" class="md-skip">
<a href="#library-overview" class="md-skip">
Skip to content
</a>
@@ -226,13 +226,13 @@
<li class="md-tabs__item">
<a href="../02_architecture/" class="md-tabs__link">
<a href="../02_components/" class="md-tabs__link">
Architecture
Components
</a>
</li>
@@ -413,27 +413,36 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<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">
What it generates
🧭 Which Build Should You Use?
</span>
</a>
</li>
<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">
Per-kind MkDocs builds
🏗️ Architecture
</span>
</a>
</li>
<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">
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>
</a>
@@ -454,12 +463,12 @@
<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">
Architecture
Components
</span>
@@ -628,7 +637,7 @@
<span class="md-ellipsis">
Gsdfc Guide
GSDFC Guide
</span>
@@ -651,7 +660,7 @@
<span class="md-ellipsis">
Mcp Guide
MCP Guide
</span>
@@ -674,7 +683,7 @@
<span class="md-ellipsis">
Mkdocs Configs
MkDocs Configs
</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
documentation. It never edits source docstrings; it reads them, renders them,
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>
<thead>
<tr>
@@ -744,7 +754,8 @@ and assembles documentation sites from all available material.</p>
</tr>
</tbody>
</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>
<ol>
<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
navigation derived or scoped to that kind. Hand-written wiki content is never
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
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>
<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">
<a href="#architecture" class="md-skip">
<a href="#components" class="md-skip">
Skip to content
</a>
@@ -106,7 +106,7 @@
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Architecture
Components
</span>
</div>
@@ -232,7 +232,7 @@
Architecture
Components
</a>
</li>
@@ -399,7 +399,7 @@
<span class="md-ellipsis">
Architecture
Components
</span>
@@ -412,7 +412,7 @@
<span class="md-ellipsis">
Architecture
Components
</span>
@@ -435,45 +435,54 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<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">
Loaders → Models
1. Loaders &amp; Models
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#navigation" class="md-nav__link">
<a href="#2-navigation" class="md-nav__link">
<span class="md-ellipsis">
Navigation
2. Navigation
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#renderers" class="md-nav__link">
<a href="#3-renderers" class="md-nav__link">
<span class="md-ellipsis">
Renderers
3. Renderers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#servers" class="md-nav__link">
<a href="#4-servers" class="md-nav__link">
<span class="md-ellipsis">
Servers
4. Servers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#cli" class="md-nav__link">
<a href="#5-cli" class="md-nav__link">
<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>
</a>
@@ -646,7 +655,7 @@
<span class="md-ellipsis">
Gsdfc Guide
GSDFC Guide
</span>
@@ -669,7 +678,7 @@
<span class="md-ellipsis">
Mcp Guide
MCP Guide
</span>
@@ -692,7 +701,7 @@
<span class="md-ellipsis">
Mkdocs Configs
MkDocs Configs
</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
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,
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>
<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
MkDocs nav emitter) and, since the wiki kind, derives wiki navigation from the
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>
<ul>
<li><code>MkDocsRenderer</code> → <code>docs/lib/**</code> reference markdown</li>
<li><code>MCPRenderer</code> → <code>docs/mcp/**</code> structured documentation</li>
</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>
<ul>
<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>
</ul>
<h2 id="cli">CLI</h2>
<hr />
<h2 id="5-cli">5. CLI</h2>
<p><code>docforge/cli</code> wires it all together:</p>
<ul>
<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>
<li><code>api_utils.py</code> — OpenAPI loading and API docs generation</li>
</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/">
@@ -224,13 +224,13 @@
<li class="md-tabs__item">
<a href="../02_architecture/" class="md-tabs__link">
<a href="../02_components/" class="md-tabs__link">
Architecture
Components
</a>
</li>
@@ -385,12 +385,12 @@
<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">
Architecture
Components
</span>
@@ -490,6 +490,15 @@
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#related" class="md-nav__link">
<span class="md-ellipsis">
Related
</span>
</a>
</li>
</ul>
@@ -637,7 +646,7 @@
<span class="md-ellipsis">
Gsdfc Guide
GSDFC Guide
</span>
@@ -660,7 +669,7 @@
<span class="md-ellipsis">
Mcp Guide
MCP Guide
</span>
@@ -683,7 +692,7 @@
<span class="md-ellipsis">
Mkdocs Configs
MkDocs Configs
</span>
@@ -718,6 +727,7 @@
<h1 id="conventions">Conventions</h1>
<hr />
<h2 id="gsdfc-docstrings">GSDFC docstrings</h2>
<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
@@ -726,32 +736,40 @@ signatures.</p>
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>
<ol>
<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>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>
</ul>
</ol>
<hr />
<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>
implementation. When signatures change, update both files.</p>
<hr />
<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>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:
<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
directory.</li>
directory.</li>
<li>Navigation labels are derived by stripping the numeric prefix and applying
title case on the remaining words.</li>
</ul>
title case on the remaining words.</li>
</ol>
<hr />
<h2 id="templates">Templates</h2>
<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>
<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">
<a href="../02_architecture/" class="md-tabs__link">
<a href="../02_components/" class="md-tabs__link">
Architecture
Components
</a>
</li>
@@ -385,12 +385,12 @@
<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">
Architecture
Components
</span>
@@ -481,7 +481,7 @@
<li class="md-nav__item">
<a href="#build-commands" class="md-nav__link">
<span class="md-ellipsis">
Build commands
🚀 Build commands
</span>
</a>
@@ -490,7 +490,7 @@
<li class="md-nav__item">
<a href="#what-a-build-does" class="md-nav__link">
<span class="md-ellipsis">
What a build does
🔄 What a build does
</span>
</a>
@@ -499,7 +499,7 @@
<li class="md-nav__item">
<a href="#explore-the-sites" class="md-nav__link">
<span class="md-ellipsis">
Explore the sites
🧭 Explore the sites
</span>
</a>
@@ -508,7 +508,16 @@
<li class="md-nav__item">
<a href="#serve-the-mcp-bundle" class="md-nav__link">
<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>
</a>
@@ -637,7 +646,7 @@
<span class="md-ellipsis">
Gsdfc Guide
GSDFC Guide
</span>
@@ -660,7 +669,7 @@
<span class="md-ellipsis">
Mcp Guide
MCP Guide
</span>
@@ -683,7 +692,7 @@
<span class="md-ellipsis">
Mkdocs Configs
MkDocs Configs
</span>
@@ -719,7 +728,8 @@
<h1 id="iterative-workflow">Iterative Workflow</h1>
<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>
<span class="normal"><a href="#__codelineno-0-2"> 2</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-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>
<h2 id="what-a-build-does">What a build does</h2>
<hr />
<h2 id="what-a-build-does">🔄 What a build does</h2>
<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>
@@ -753,7 +764,8 @@
<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>
<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>
<span class="normal"><a href="#__codelineno-1-2">2</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-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>
<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>
<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></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">
<a href="../../02_architecture/" class="md-tabs__link">
<a href="../../02_components/" class="md-tabs__link">
Architecture
Components
</a>
</li>
@@ -385,12 +385,12 @@
<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">
Architecture
Components
</span>
@@ -563,7 +563,7 @@
<li class="md-nav__item">
<a href="#create-the-environment" class="md-nav__link">
<span class="md-ellipsis">
Create the environment
🚀 Create the environment
</span>
</a>
@@ -572,7 +572,16 @@
<li class="md-nav__item">
<a href="#dependencies" class="md-nav__link">
<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>
</a>
@@ -622,7 +631,7 @@
<span class="md-ellipsis">
Gsdfc Guide
GSDFC Guide
</span>
@@ -645,7 +654,7 @@
<span class="md-ellipsis">
Mcp Guide
MCP Guide
</span>
@@ -668,7 +677,7 @@
<span class="md-ellipsis">
Mkdocs Configs
MkDocs Configs
</span>
@@ -703,7 +712,8 @@
<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>
<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
@@ -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></code></pre></div></td></tr></table></div>
<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>
<ul>
<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>pydoclint</code> — docstring ↔ signature consistency checks</li>
</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">
<a href="../../02_architecture/" class="md-tabs__link">
<a href="../../02_components/" class="md-tabs__link">
Architecture
Components
</a>
</li>
@@ -385,12 +385,12 @@
<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">
Architecture
Components
</span>
@@ -583,10 +583,28 @@
</label>
<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">
<a href="#test-layout" class="md-nav__link">
<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>
</a>
@@ -613,7 +631,7 @@
<span class="md-ellipsis">
Gsdfc Guide
GSDFC Guide
</span>
@@ -636,7 +654,7 @@
<span class="md-ellipsis">
Mcp Guide
MCP Guide
</span>
@@ -659,7 +677,7 @@
<span class="md-ellipsis">
Mkdocs Configs
MkDocs Configs
</span>
@@ -695,6 +713,8 @@
<h1 id="quality-gates">Quality Gates</h1>
<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>
<span class="normal"><a href="#__codelineno-0-2">2</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-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>
<h2 id="test-layout">Test layout</h2>
<hr />
<h2 id="test-layout">📁 Test layout</h2>
<table>
<thead>
<tr>
@@ -731,6 +752,11 @@
<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>
<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">
<span class="md-ellipsis">
Gsdfc Guide
GSDFC Guide
</span>
</div>
@@ -224,13 +224,13 @@
<li class="md-tabs__item">
<a href="../../02_architecture/" class="md-tabs__link">
<a href="../../02_components/" class="md-tabs__link">
Architecture
Components
</a>
</li>
@@ -385,12 +385,12 @@
<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">
Architecture
Components
</span>
@@ -571,7 +571,7 @@
<span class="md-ellipsis">
Gsdfc Guide
GSDFC Guide
</span>
@@ -584,7 +584,7 @@
<span class="md-ellipsis">
Gsdfc Guide
GSDFC Guide
</span>
@@ -609,7 +609,7 @@
<li class="md-nav__item">
<a href="#overview" class="md-nav__link">
<span class="md-ellipsis">
Overview
🧭 Overview
</span>
</a>
@@ -618,7 +618,7 @@
<li class="md-nav__item">
<a href="#module-docstrings" class="md-nav__link">
<span class="md-ellipsis">
Module docstrings
📦 Module docstrings
</span>
</a>
@@ -627,7 +627,7 @@
<li class="md-nav__item">
<a href="#class-docstrings" class="md-nav__link">
<span class="md-ellipsis">
Class docstrings
📦 Class docstrings
</span>
</a>
@@ -636,7 +636,7 @@
<li class="md-nav__item">
<a href="#function-and-method-docstrings" class="md-nav__link">
<span class="md-ellipsis">
Function and method docstrings
📦 Function and method docstrings
</span>
</a>
@@ -645,7 +645,7 @@
<li class="md-nav__item">
<a href="#property-docstrings" class="md-nav__link">
<span class="md-ellipsis">
Property docstrings
📦 Property docstrings
</span>
</a>
@@ -654,7 +654,7 @@
<li class="md-nav__item">
<a href="#example" class="md-nav__link">
<span class="md-ellipsis">
Example
🚀 Example
</span>
</a>
@@ -663,7 +663,7 @@
<li class="md-nav__item">
<a href="#keeping-stubs-in-sync" class="md-nav__link">
<span class="md-ellipsis">
Keeping stubs in sync
🔄 Keeping stubs in sync
</span>
</a>
@@ -672,7 +672,16 @@
<li class="md-nav__item">
<a href="#enforcement" class="md-nav__link">
<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>
</a>
@@ -699,7 +708,7 @@
<span class="md-ellipsis">
Mcp Guide
MCP Guide
</span>
@@ -722,7 +731,7 @@
<span class="md-ellipsis">
Mkdocs Configs
MkDocs Configs
</span>
@@ -761,7 +770,8 @@
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>
<h2 id="overview">Overview</h2>
<hr />
<h2 id="overview">🧭 Overview</h2>
<ul>
<li>Docstrings are the single source of truth.</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
parentheses and must match the signature.</li>
</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>Recommended sections:</p>
<ul>
@@ -777,7 +788,8 @@ doc-forge, MkDocs, and MCP clients.</p>
<li><code># Examples</code> — a representative usage snippet</li>
<li><code># Notes</code> — guarantees, lifecycle, and thread-safety notes</li>
</ul>
<h2 id="class-docstrings">Class docstrings</h2>
<hr />
<h2 id="class-docstrings">📦 Class docstrings</h2>
<p>Recommended sections, in order:</p>
<ul>
<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>Example:</code> — indented <code>python</code> code block</li>
</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>
<ol>
<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
four spaces.</li>
</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
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>
<span class="normal"><a href="#__codelineno-0-2"> 2</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-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>
<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
symbol changes, update both files. Signature annotations in the stub must
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>
sections match function signatures, including types.</p>
<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
attributes without class-level annotations.</li>
</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">
<span class="md-ellipsis">
Mcp Guide
MCP Guide
</span>
</div>
@@ -224,13 +224,13 @@
<li class="md-tabs__item">
<a href="../../02_architecture/" class="md-tabs__link">
<a href="../../02_components/" class="md-tabs__link">
Architecture
Components
</a>
</li>
@@ -385,12 +385,12 @@
<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">
Architecture
Components
</span>
@@ -562,7 +562,7 @@
<span class="md-ellipsis">
Gsdfc Guide
GSDFC Guide
</span>
@@ -594,7 +594,7 @@
<span class="md-ellipsis">
Mcp Guide
MCP Guide
</span>
@@ -607,7 +607,7 @@
<span class="md-ellipsis">
Mcp Guide
MCP Guide
</span>
@@ -632,7 +632,7 @@
<li class="md-nav__item">
<a href="#building-the-bundle" class="md-nav__link">
<span class="md-ellipsis">
Building the bundle
🚀 Building the bundle
</span>
</a>
@@ -641,7 +641,7 @@
<li class="md-nav__item">
<a href="#serving-the-bundle" class="md-nav__link">
<span class="md-ellipsis">
Serving the bundle
🚀 Serving the bundle
</span>
</a>
@@ -650,7 +650,16 @@
<li class="md-nav__item">
<a href="#bundle-contents" class="md-nav__link">
<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>
</a>
@@ -677,7 +686,7 @@
<span class="md-ellipsis">
Mkdocs Configs
MkDocs Configs
</span>
@@ -716,7 +725,8 @@
GSDFC docstrings and serve that bundle over the Model Context Protocol (MCP).
The bundle is self-contained: readers can derive the full API reference —
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
</span></code></pre></div></td></tr></table></div>
<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>modules/{dotted.path}.json</code> — per-module serialized documentation</li>
</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
</span></code></pre></div></td></tr></table></div>
<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
exceptions. The default transport is <code>streamable-http</code>; <code>stdio</code> and <code>sse</code> are
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>
<ul>
<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,
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>
<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">
<span class="md-ellipsis">
Mkdocs Configs
MkDocs Configs
</span>
</div>
@@ -222,13 +222,13 @@
<li class="md-tabs__item">
<a href="../../02_architecture/" class="md-tabs__link">
<a href="../../02_components/" class="md-tabs__link">
Architecture
Components
</a>
</li>
@@ -383,12 +383,12 @@
<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">
Architecture
Components
</span>
@@ -560,7 +560,7 @@
<span class="md-ellipsis">
Gsdfc Guide
GSDFC Guide
</span>
@@ -583,7 +583,7 @@
<span class="md-ellipsis">
Mcp Guide
MCP Guide
</span>
@@ -615,7 +615,7 @@
<span class="md-ellipsis">
Mkdocs Configs
MkDocs Configs
</span>
@@ -628,7 +628,7 @@
<span class="md-ellipsis">
Mkdocs Configs
MkDocs Configs
</span>
@@ -653,7 +653,7 @@
<li class="md-nav__item">
<a href="#file-wins" class="md-nav__link">
<span class="md-ellipsis">
File wins
📄 File wins
</span>
</a>
@@ -662,7 +662,7 @@
<li class="md-nav__item">
<a href="#templates" class="md-nav__link">
<span class="md-ellipsis">
Templates
🧩 Templates
</span>
</a>
@@ -671,7 +671,16 @@
<li class="md-nav__item">
<a href="#supported-layouts" class="md-nav__link">
<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>
</a>
@@ -714,7 +723,8 @@
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
<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>
<ul>
<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>
<p>Because a present file is never rewritten, rerunning a build is a no-op for
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>
<table>
<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
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>
<h2 id="supported-layouts">Supported layouts</h2>
<hr />
<h2 id="supported-layouts">🏗️ Supported layouts</h2>
<ul>
<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>
@@ -769,6 +781,11 @@ built-in templates entirely.</p>
kind to the root <code>site/</code> dir in this case.</li>
</ul>
<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">
<a href="/02_architecture/" class="md-tabs__link">
<a href="/02_components/" class="md-tabs__link">
Architecture
Components
</a>
</li>
@@ -374,12 +374,12 @@
<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">
Architecture
Components
</span>
@@ -548,7 +548,7 @@
<span class="md-ellipsis">
Gsdfc Guide
GSDFC Guide
</span>
@@ -571,7 +571,7 @@
<span class="md-ellipsis">
Mcp Guide
MCP Guide
</span>
@@ -594,7 +594,7 @@
<span class="md-ellipsis">
Mkdocs Configs
MkDocs Configs
</span>

File diff suppressed because it is too large Load Diff

File diff suppressed because one or more lines are too long