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:
@@ -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>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -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>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -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"> """</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>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -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>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -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 <path></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>/<repo>/{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>
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user