aetos/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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:
Vishesh 'ironeagle' Bangotra
2026-09-14 23:30:51 +05:30
parent 37f2fbf4b9
commit 48631b57c5
12 changed files with 896 additions and 701 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
doc-forge/wiki/05_development/03_gsdfc_guide/index.html
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>