docs(wiki): added more rules and explanation on how to use the prompt in docforge wiki
This commit is contained in:
@@ -466,9 +466,9 @@
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#pyi-stubs" class="md-nav__link">
|
||||
<a href="#pyi-stubs-and-pytyped" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
.pyi stubs
|
||||
.pyi stubs and py.typed
|
||||
</span>
|
||||
</a>
|
||||
|
||||
@@ -743,11 +743,14 @@ package docstring, which is exported verbatim into
|
||||
<li>Use <code>Args:</code>, <code>Returns:</code>, <code>Raises:</code>, <code>Yields:</code>, <code>Notes:</code>, and <code>Example:</code>
|
||||
sections at function and method level.</li>
|
||||
<li>Always update the matching <code>.pyi</code> stub alongside the <code>.py</code> implementation.</li>
|
||||
<li>Every distributable package ships a <code>py.typed</code> marker so type checkers
|
||||
consume the authored signatures instead of <code>Any</code>.</li>
|
||||
</ol>
|
||||
<hr />
|
||||
<h2 id="pyi-stubs"><code>.pyi</code> stubs</h2>
|
||||
<h2 id="pyi-stubs-and-pytyped"><code>.pyi</code> stubs and <code>py.typed</code></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>
|
||||
implementation. When signatures change, update both files. Packages expose a
|
||||
<code>py.typed</code> marker so consumers and type checkers use the authored signatures.</p>
|
||||
<hr />
|
||||
<h2 id="wiki-pages">Wiki pages</h2>
|
||||
<ol>
|
||||
|
||||
@@ -790,7 +790,8 @@ and testing recipes. The authoritative API contracts live in the code
|
||||
<ul>
|
||||
<li><strong>Source Code:</strong> the <code>doc-forge</code> repository</li>
|
||||
<li><strong>MCP Bundle:</strong> generated by <code>doc-forge build --mcp --module docforge</code> into <code>docs/mcp/</code></li>
|
||||
<li><strong>Wiki Kind:</strong> hand-written content lives in <code>docs/wiki/</code> or use the prompt mentioned below
|
||||
<li><strong>Wiki Kind:</strong> hand-written content lives in <code>docs/wiki/</code>; use the prompt in the
|
||||
wiki-related resource below
|
||||
<div class="language-markdown 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>
|
||||
@@ -1051,267 +1052,283 @@ and testing recipes. The authoritative API contracts live in the code
|
||||
<span class="normal"><a href="#__codelineno-1-258">258</a></span>
|
||||
<span class="normal"><a href="#__codelineno-1-259">259</a></span>
|
||||
<span class="normal"><a href="#__codelineno-1-260">260</a></span>
|
||||
<span class="normal"><a href="#__codelineno-1-261">261</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><span class="gh"># AGENTS.md — Wiki Authoring Guide (Aetoskia)</span>
|
||||
<span class="normal"><a href="#__codelineno-1-261">261</a></span>
|
||||
<span class="normal"><a href="#__codelineno-1-262">262</a></span>
|
||||
<span class="normal"><a href="#__codelineno-1-263">263</a></span>
|
||||
<span class="normal"><a href="#__codelineno-1-264">264</a></span>
|
||||
<span class="normal"><a href="#__codelineno-1-265">265</a></span>
|
||||
<span class="normal"><a href="#__codelineno-1-266">266</a></span>
|
||||
<span class="normal"><a href="#__codelineno-1-267">267</a></span>
|
||||
<span class="normal"><a href="#__codelineno-1-268">268</a></span>
|
||||
<span class="normal"><a href="#__codelineno-1-269">269</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><span class="gh"># AGENTS.md — Wiki Authoring Guide (Aetoskia)</span>
|
||||
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2"></a>
|
||||
</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3"></a>This file instructs AI agents how to create, extend, and maintain the wiki
|
||||
</span><span id="__span-1-4"><a id="__codelineno-1-4" name="__codelineno-1-4"></a>(<span class="sb">`docs/wiki/**`</span>) for any Aetoskia repository. The reference implementation is
|
||||
</span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5"></a><span class="sb">`mongo-ops`</span> — its wiki went through several revisions to reach the structure
|
||||
</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6"></a>below and should be treated as the canonical example.
|
||||
</span><span id="__span-1-7"><a id="__codelineno-1-7" name="__codelineno-1-7"></a>
|
||||
</span><span id="__span-1-8"><a id="__codelineno-1-8" name="__codelineno-1-8"></a>---
|
||||
</span><span id="__span-1-9"><a id="__codelineno-1-9" name="__codelineno-1-9"></a>
|
||||
</span><span id="__span-1-10"><a id="__codelineno-1-10" name="__codelineno-1-10"></a><span class="gu">## 1. Doc model — know the two sources of truth</span>
|
||||
</span><span id="__span-1-4"><a id="__codelineno-1-4" name="__codelineno-1-4"></a>(<span class="sb">`docs/wiki/**`</span>) for any Aetoskia repository.
|
||||
</span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5"></a>
|
||||
</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6"></a><span class="k">> </span><span class="ge">**Workflow:** this prompt covers **phase 2 only**. Phase 1 — writing GSDFC docstrings</span>
|
||||
</span><span id="__span-1-7"><a id="__codelineno-1-7" name="__codelineno-1-7"></a><span class="k">> </span><span class="ge">(plus `.pyi` stubs and `py.typed`) — is done by the agent using the doc-forge MCP</span>
|
||||
</span><span id="__span-1-8"><a id="__codelineno-1-8" name="__codelineno-1-8"></a><span class="k">> </span><span class="ge">bundle: `doc://modules/docforge` carries the full GSDFC spec. Write the wiki only</span>
|
||||
</span><span id="__span-1-9"><a id="__codelineno-1-9" name="__codelineno-1-9"></a><span class="k">> </span><span class="ge">after docstrings exist and `doc-forge build --mcp --module <pkg>` produced the</span>
|
||||
</span><span id="__span-1-10"><a id="__codelineno-1-10" name="__codelineno-1-10"></a><span class="k">> </span><span class="ge">repo's own bundle.</span>
|
||||
</span><span id="__span-1-11"><a id="__codelineno-1-11" name="__codelineno-1-11"></a>
|
||||
</span><span id="__span-1-12"><a id="__codelineno-1-12" name="__codelineno-1-12"></a>Every repo keeps two distinct kinds of documentation that must <span class="gs">**not**</span> bleed
|
||||
</span><span id="__span-1-13"><a id="__codelineno-1-13" name="__codelineno-1-13"></a>into each other:
|
||||
</span><span id="__span-1-14"><a id="__codelineno-1-14" name="__codelineno-1-14"></a>
|
||||
</span><span id="__span-1-15"><a id="__codelineno-1-15" name="__codelineno-1-15"></a>| Kind | Source | Where | Audience |
|
||||
</span><span id="__span-1-16"><a id="__codelineno-1-16" name="__codelineno-1-16"></a>|-------------------|-----------------------|------------------------------------------|------------------------------------|
|
||||
</span><span id="__span-1-17"><a id="__codelineno-1-17" name="__codelineno-1-17"></a>| <span class="gs">**Wiki**</span> | Hand-written markdown | <span class="sb">`docs/wiki/**`</span> | Humans (how-to, examples, testing) |
|
||||
</span><span id="__span-1-18"><a id="__codelineno-1-18" name="__codelineno-1-18"></a>| <span class="gs">**API reference**</span> | Docstrings (GSDFC) | Generated → <span class="sb">`docs/lib/**`</span>, <span class="sb">`docs/mcp/**`</span> | Consumers (exact contracts) |
|
||||
</span><span id="__span-1-19"><a id="__codelineno-1-19" name="__codelineno-1-19"></a>
|
||||
</span><span id="__span-1-20"><a id="__codelineno-1-20" name="__codelineno-1-20"></a>Rules:
|
||||
</span><span id="__span-1-21"><a id="__codelineno-1-21" name="__codelineno-1-21"></a>
|
||||
</span><span id="__span-1-22"><a id="__codelineno-1-22" name="__codelineno-1-22"></a><span class="k">-</span><span class="w"> </span>The wiki is written <span class="gs">**for humans**</span> — how-to guides, recipes, and testing
|
||||
</span><span id="__span-1-23"><a id="__codelineno-1-23" name="__codelineno-1-23"></a> patterns. It is never generated.
|
||||
</span><span id="__span-1-24"><a id="__codelineno-1-24" name="__codelineno-1-24"></a><span class="k">-</span><span class="w"> </span>API contracts (signatures, parameter types, exact behavior) live in the
|
||||
</span><span id="__span-1-25"><a id="__codelineno-1-25" name="__codelineno-1-25"></a> docstrings and the machine-readable bundle under <span class="sb">`docs/mcp/`</span>. <span class="gs">**Never**</span>
|
||||
</span><span id="__span-1-26"><a id="__codelineno-1-26" name="__codelineno-1-26"></a> duplicate full API documentation in the wiki — link to the lib site instead.
|
||||
</span><span id="__span-1-27"><a id="__codelineno-1-27" name="__codelineno-1-27"></a><span class="k">-</span><span class="w"> </span>If a page starts to drift into contract territory, cut it down to usage and
|
||||
</span><span id="__span-1-28"><a id="__codelineno-1-28" name="__codelineno-1-28"></a> point at <span class="sb">`docs/lib/`</span>.
|
||||
</span><span id="__span-1-29"><a id="__codelineno-1-29" name="__codelineno-1-29"></a><span class="k">-</span><span class="w"> </span>This doc model is stated on every index page as a blockquote; keep it there:
|
||||
</span><span id="__span-1-30"><a id="__codelineno-1-30" name="__codelineno-1-30"></a><span class="k"> > </span><span class="ge">**Doc model:** this wiki is written for humans — how‑to guides, examples,</span>
|
||||
</span><span id="__span-1-31"><a id="__codelineno-1-31" name="__codelineno-1-31"></a><span class="k"> > </span><span class="ge">and testing recipes. The authoritative API contracts live in the code</span>
|
||||
</span><span id="__span-1-32"><a id="__codelineno-1-32" name="__codelineno-1-32"></a><span class="k"> > </span><span class="ge">(docstrings) and the machine‑readable bundle under `docs/mcp/`.</span>
|
||||
</span><span id="__span-1-33"><a id="__codelineno-1-33" name="__codelineno-1-33"></a>
|
||||
</span><span id="__span-1-34"><a id="__codelineno-1-34" name="__codelineno-1-34"></a>---
|
||||
</span><span id="__span-1-35"><a id="__codelineno-1-35" name="__codelineno-1-35"></a>
|
||||
</span><span id="__span-1-36"><a id="__codelineno-1-36" name="__codelineno-1-36"></a><span class="gu">## 2. Directory layout & file naming</span>
|
||||
</span><span id="__span-1-12"><a id="__codelineno-1-12" name="__codelineno-1-12"></a>---
|
||||
</span><span id="__span-1-13"><a id="__codelineno-1-13" name="__codelineno-1-13"></a>
|
||||
</span><span id="__span-1-14"><a id="__codelineno-1-14" name="__codelineno-1-14"></a><span class="gu">## 1. Doc model — know the two sources of truth</span>
|
||||
</span><span id="__span-1-15"><a id="__codelineno-1-15" name="__codelineno-1-15"></a>
|
||||
</span><span id="__span-1-16"><a id="__codelineno-1-16" name="__codelineno-1-16"></a>Every repo keeps two distinct kinds of documentation that must <span class="gs">**not**</span> bleed
|
||||
</span><span id="__span-1-17"><a id="__codelineno-1-17" name="__codelineno-1-17"></a>into each other:
|
||||
</span><span id="__span-1-18"><a id="__codelineno-1-18" name="__codelineno-1-18"></a>
|
||||
</span><span id="__span-1-19"><a id="__codelineno-1-19" name="__codelineno-1-19"></a>| Kind | Source | Where | Audience |
|
||||
</span><span id="__span-1-20"><a id="__codelineno-1-20" name="__codelineno-1-20"></a>|-------------------|-----------------------|------------------------------------------|------------------------------------|
|
||||
</span><span id="__span-1-21"><a id="__codelineno-1-21" name="__codelineno-1-21"></a>| <span class="gs">**Wiki**</span> | Hand-written markdown | <span class="sb">`docs/wiki/**`</span> | Humans (how-to, examples, testing) |
|
||||
</span><span id="__span-1-22"><a id="__codelineno-1-22" name="__codelineno-1-22"></a>| <span class="gs">**API reference**</span> | Docstrings (GSDFC) | Generated → <span class="sb">`docs/lib/**`</span>, <span class="sb">`docs/mcp/**`</span> | Consumers (exact contracts) |
|
||||
</span><span id="__span-1-23"><a id="__codelineno-1-23" name="__codelineno-1-23"></a>
|
||||
</span><span id="__span-1-24"><a id="__codelineno-1-24" name="__codelineno-1-24"></a>Rules:
|
||||
</span><span id="__span-1-25"><a id="__codelineno-1-25" name="__codelineno-1-25"></a>
|
||||
</span><span id="__span-1-26"><a id="__codelineno-1-26" name="__codelineno-1-26"></a><span class="k">-</span><span class="w"> </span>The wiki is written <span class="gs">**for humans**</span> — how-to guides, recipes, and testing
|
||||
</span><span id="__span-1-27"><a id="__codelineno-1-27" name="__codelineno-1-27"></a> patterns. It is never generated.
|
||||
</span><span id="__span-1-28"><a id="__codelineno-1-28" name="__codelineno-1-28"></a><span class="k">-</span><span class="w"> </span>API contracts (signatures, parameter types, exact behavior) live in the
|
||||
</span><span id="__span-1-29"><a id="__codelineno-1-29" name="__codelineno-1-29"></a> docstrings and the machine-readable bundle under <span class="sb">`docs/mcp/`</span>. <span class="gs">**Never**</span>
|
||||
</span><span id="__span-1-30"><a id="__codelineno-1-30" name="__codelineno-1-30"></a> duplicate full API documentation in the wiki — link to the lib site instead.
|
||||
</span><span id="__span-1-31"><a id="__codelineno-1-31" name="__codelineno-1-31"></a><span class="k">-</span><span class="w"> </span>If a page starts to drift into contract territory, cut it down to usage and
|
||||
</span><span id="__span-1-32"><a id="__codelineno-1-32" name="__codelineno-1-32"></a> point at <span class="sb">`docs/lib/`</span>.
|
||||
</span><span id="__span-1-33"><a id="__codelineno-1-33" name="__codelineno-1-33"></a><span class="k">-</span><span class="w"> </span>This doc model is stated on every index page as a blockquote; keep it there:
|
||||
</span><span id="__span-1-34"><a id="__codelineno-1-34" name="__codelineno-1-34"></a><span class="k"> > </span><span class="ge">**Doc model:** this wiki is written for humans — how‑to guides, examples,</span>
|
||||
</span><span id="__span-1-35"><a id="__codelineno-1-35" name="__codelineno-1-35"></a><span class="k"> > </span><span class="ge">and testing recipes. The authoritative API contracts live in the code</span>
|
||||
</span><span id="__span-1-36"><a id="__codelineno-1-36" name="__codelineno-1-36"></a><span class="k"> > </span><span class="ge">(docstrings) and the machine‑readable bundle under `docs/mcp/`.</span>
|
||||
</span><span id="__span-1-37"><a id="__codelineno-1-37" name="__codelineno-1-37"></a>
|
||||
</span><span id="__span-1-38"><a id="__codelineno-1-38" name="__codelineno-1-38"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-39"><a id="__codelineno-1-39" name="__codelineno-1-39"></a><span class="sb">docs/wiki/</span>
|
||||
</span><span id="__span-1-40"><a id="__codelineno-1-40" name="__codelineno-1-40"></a><span class="sb">├── index.md # site Home</span>
|
||||
</span><span id="__span-1-41"><a id="__codelineno-1-41" name="__codelineno-1-41"></a><span class="sb">├── 01_overview.md</span>
|
||||
</span><span id="__span-1-42"><a id="__codelineno-1-42" name="__codelineno-1-42"></a><span class="sb">├── 02_components.md</span>
|
||||
</span><span id="__span-1-43"><a id="__codelineno-1-43" name="__codelineno-1-43"></a><span class="sb">├── 03_use_cases/ # nested directory → nav group</span>
|
||||
</span><span id="__span-1-44"><a id="__codelineno-1-44" name="__codelineno-1-44"></a><span class="sb">│ ├── 01_basic_crud.md</span>
|
||||
</span><span id="__span-1-45"><a id="__codelineno-1-45" name="__codelineno-1-45"></a><span class="sb">│ ├── 02_custom_repo.md</span>
|
||||
</span><span id="__span-1-46"><a id="__codelineno-1-46" name="__codelineno-1-46"></a><span class="sb">│ └── ...</span>
|
||||
</span><span id="__span-1-47"><a id="__codelineno-1-47" name="__codelineno-1-47"></a><span class="sb">├── 04_best_practices.md</span>
|
||||
</span><span id="__span-1-48"><a id="__codelineno-1-48" name="__codelineno-1-48"></a><span class="sb">├── 06_error_handling.md</span>
|
||||
</span><span id="__span-1-49"><a id="__codelineno-1-49" name="__codelineno-1-49"></a><span class="sb">└── 07_testing_example.md</span>
|
||||
</span><span id="__span-1-50"><a id="__codelineno-1-50" name="__codelineno-1-50"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-51"><a id="__codelineno-1-51" name="__codelineno-1-51"></a>
|
||||
</span><span id="__span-1-52"><a id="__codelineno-1-52" name="__codelineno-1-52"></a><span class="k">-</span><span class="w"> </span>Location: <span class="sb">`docs/wiki/`</span> (hand-written only).
|
||||
</span><span id="__span-1-53"><a id="__codelineno-1-53" name="__codelineno-1-53"></a><span class="k">-</span><span class="w"> </span>File names: <span class="sb">`NN_snake_case_name.md`</span> with a <span class="gs">**zero-padded two-digit**</span> numeric
|
||||
</span><span id="__span-1-54"><a id="__codelineno-1-54" name="__codelineno-1-54"></a> prefix. e.g. <span class="sb">`01_overview.md`</span>, <span class="sb">`03_use_cases/07_caching.md`</span>.
|
||||
</span><span id="__span-1-55"><a id="__codelineno-1-55" name="__codelineno-1-55"></a><span class="k">-</span><span class="w"> </span>Top-level pages use <span class="sb">`NN_name.md`</span> directly. High-volume sections get their own
|
||||
</span><span id="__span-1-56"><a id="__codelineno-1-56" name="__codelineno-1-56"></a> directory, e.g. <span class="sb">`03_use_cases/NN_name.md`</span> (nav group "Use Cases").
|
||||
</span><span id="__span-1-57"><a id="__codelineno-1-57" name="__codelineno-1-57"></a><span class="k">-</span><span class="w"> </span><span class="gs">**No frontmatter.**</span> Every file opens directly with an H1 <span class="sb">`# Title`</span>.
|
||||
</span><span id="__span-1-58"><a id="__codelineno-1-58" name="__codelineno-1-58"></a><span class="k">-</span><span class="w"> </span>Navigation labels are short human titles set explicitly in
|
||||
</span><span id="__span-1-59"><a id="__codelineno-1-59" name="__codelineno-1-59"></a> <span class="sb">`docs/mkdocs.wiki.yml`</span> (title case) — often <span class="gs">**shorter**</span> than the page H1.
|
||||
</span><span id="__span-1-60"><a id="__codelineno-1-60" name="__codelineno-1-60"></a> Example: nav label <span class="sb">`Basic CRUD`</span> vs page H1 <span class="sb">`Use Case 1: Basic FastAPI CRUD API`</span>.
|
||||
</span><span id="__span-1-61"><a id="__codelineno-1-61" name="__codelineno-1-61"></a> Never use the raw filename slug as the label.
|
||||
</span><span id="__span-1-62"><a id="__codelineno-1-62" name="__codelineno-1-62"></a><span class="k">-</span><span class="w"> </span>Renumbering: prefixes order pages. When inserting a page, pick the next
|
||||
</span><span id="__span-1-63"><a id="__codelineno-1-63" name="__codelineno-1-63"></a> number in the relevant group (subgroup numbers stay grouped).
|
||||
</span><span id="__span-1-64"><a id="__codelineno-1-64" name="__codelineno-1-64"></a>
|
||||
</span><span id="__span-1-65"><a id="__codelineno-1-65" name="__codelineno-1-65"></a>---
|
||||
</span><span id="__span-1-66"><a id="__codelineno-1-66" name="__codelineno-1-66"></a>
|
||||
</span><span id="__span-1-67"><a id="__codelineno-1-67" name="__codelineno-1-67"></a><span class="gu">## 3. Navigation — `docs/mkdocs.wiki.yml` is the source of truth</span>
|
||||
</span><span id="__span-1-38"><a id="__codelineno-1-38" name="__codelineno-1-38"></a>---
|
||||
</span><span id="__span-1-39"><a id="__codelineno-1-39" name="__codelineno-1-39"></a>
|
||||
</span><span id="__span-1-40"><a id="__codelineno-1-40" name="__codelineno-1-40"></a><span class="gu">## 2. Directory layout & file naming</span>
|
||||
</span><span id="__span-1-41"><a id="__codelineno-1-41" name="__codelineno-1-41"></a>
|
||||
</span><span id="__span-1-42"><a id="__codelineno-1-42" name="__codelineno-1-42"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-43"><a id="__codelineno-1-43" name="__codelineno-1-43"></a><span class="sb">docs/wiki/</span>
|
||||
</span><span id="__span-1-44"><a id="__codelineno-1-44" name="__codelineno-1-44"></a><span class="sb">├── index.md # site Home</span>
|
||||
</span><span id="__span-1-45"><a id="__codelineno-1-45" name="__codelineno-1-45"></a><span class="sb">├── 01_overview.md</span>
|
||||
</span><span id="__span-1-46"><a id="__codelineno-1-46" name="__codelineno-1-46"></a><span class="sb">├── 02_components.md</span>
|
||||
</span><span id="__span-1-47"><a id="__codelineno-1-47" name="__codelineno-1-47"></a><span class="sb">├── 03_use_cases/ # nested directory → nav group</span>
|
||||
</span><span id="__span-1-48"><a id="__codelineno-1-48" name="__codelineno-1-48"></a><span class="sb">│ ├── 01_basic_crud.md</span>
|
||||
</span><span id="__span-1-49"><a id="__codelineno-1-49" name="__codelineno-1-49"></a><span class="sb">│ ├── 02_custom_repo.md</span>
|
||||
</span><span id="__span-1-50"><a id="__codelineno-1-50" name="__codelineno-1-50"></a><span class="sb">│ └── ...</span>
|
||||
</span><span id="__span-1-51"><a id="__codelineno-1-51" name="__codelineno-1-51"></a><span class="sb">├── 04_best_practices.md</span>
|
||||
</span><span id="__span-1-52"><a id="__codelineno-1-52" name="__codelineno-1-52"></a><span class="sb">├── 06_error_handling.md</span>
|
||||
</span><span id="__span-1-53"><a id="__codelineno-1-53" name="__codelineno-1-53"></a><span class="sb">└── 07_testing_example.md</span>
|
||||
</span><span id="__span-1-54"><a id="__codelineno-1-54" name="__codelineno-1-54"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-55"><a id="__codelineno-1-55" name="__codelineno-1-55"></a>
|
||||
</span><span id="__span-1-56"><a id="__codelineno-1-56" name="__codelineno-1-56"></a><span class="k">-</span><span class="w"> </span>Location: <span class="sb">`docs/wiki/`</span> (hand-written only).
|
||||
</span><span id="__span-1-57"><a id="__codelineno-1-57" name="__codelineno-1-57"></a><span class="k">-</span><span class="w"> </span>File names: <span class="sb">`NN_snake_case_name.md`</span> with a <span class="gs">**zero-padded two-digit**</span> numeric
|
||||
</span><span id="__span-1-58"><a id="__codelineno-1-58" name="__codelineno-1-58"></a> prefix. e.g. <span class="sb">`01_overview.md`</span>, <span class="sb">`03_use_cases/07_caching.md`</span>.
|
||||
</span><span id="__span-1-59"><a id="__codelineno-1-59" name="__codelineno-1-59"></a><span class="k">-</span><span class="w"> </span>Top-level pages use <span class="sb">`NN_name.md`</span> directly. High-volume sections get their own
|
||||
</span><span id="__span-1-60"><a id="__codelineno-1-60" name="__codelineno-1-60"></a> directory, e.g. <span class="sb">`03_use_cases/NN_name.md`</span> (nav group "Use Cases").
|
||||
</span><span id="__span-1-61"><a id="__codelineno-1-61" name="__codelineno-1-61"></a><span class="k">-</span><span class="w"> </span><span class="gs">**No frontmatter.**</span> Every file opens directly with an H1 <span class="sb">`# Title`</span>.
|
||||
</span><span id="__span-1-62"><a id="__codelineno-1-62" name="__codelineno-1-62"></a><span class="k">-</span><span class="w"> </span>Navigation labels are short human titles set explicitly in
|
||||
</span><span id="__span-1-63"><a id="__codelineno-1-63" name="__codelineno-1-63"></a> <span class="sb">`docs/mkdocs.wiki.yml`</span> (title case) — often <span class="gs">**shorter**</span> than the page H1.
|
||||
</span><span id="__span-1-64"><a id="__codelineno-1-64" name="__codelineno-1-64"></a> Example: nav label <span class="sb">`Basic CRUD`</span> vs page H1 <span class="sb">`Use Case 1: Basic FastAPI CRUD API`</span>.
|
||||
</span><span id="__span-1-65"><a id="__codelineno-1-65" name="__codelineno-1-65"></a> Never use the raw filename slug as the label.
|
||||
</span><span id="__span-1-66"><a id="__codelineno-1-66" name="__codelineno-1-66"></a><span class="k">-</span><span class="w"> </span>Renumbering: prefixes order pages. When inserting a page, pick the next
|
||||
</span><span id="__span-1-67"><a id="__codelineno-1-67" name="__codelineno-1-67"></a> number in the relevant group (subgroup numbers stay grouped).
|
||||
</span><span id="__span-1-68"><a id="__codelineno-1-68" name="__codelineno-1-68"></a>
|
||||
</span><span id="__span-1-69"><a id="__codelineno-1-69" name="__codelineno-1-69"></a>Every wiki page <span class="gs">**must**</span> be wired into the nav defined in
|
||||
</span><span id="__span-1-70"><a id="__codelineno-1-70" name="__codelineno-1-70"></a><span class="sb">`docs/mkdocs.wiki.yml`</span>. If a page is not in the nav, it is orphaned.
|
||||
</span><span id="__span-1-71"><a id="__codelineno-1-71" name="__codelineno-1-71"></a>
|
||||
</span><span id="__span-1-72"><a id="__codelineno-1-72" name="__codelineno-1-72"></a><span class="k">-</span><span class="w"> </span>The <span class="sb">`nav:`</span> block mirrors the directory tree; directories become nested
|
||||
</span><span id="__span-1-73"><a id="__codelineno-1-73" name="__codelineno-1-73"></a> groups.
|
||||
</span><span id="__span-1-74"><a id="__codelineno-1-74" name="__codelineno-1-74"></a><span class="k">-</span><span class="w"> </span>When a section has many pages, group them <span class="gs">**by theme**</span> into nested
|
||||
</span><span id="__span-1-75"><a id="__codelineno-1-75" name="__codelineno-1-75"></a> subgroups. mongo-ops groups its use cases into:
|
||||
</span><span id="__span-1-76"><a id="__codelineno-1-76" name="__codelineno-1-76"></a> <span class="sb">`Getting Started`</span>, <span class="sb">`Data & Queries`</span>, <span class="sb">`Caching`</span>, <span class="sb">`Population`</span>,
|
||||
</span><span id="__span-1-77"><a id="__codelineno-1-77" name="__codelineno-1-77"></a> <span class="sb">`Advanced Usage`</span>.
|
||||
</span><span id="__span-1-78"><a id="__codelineno-1-78" name="__codelineno-1-78"></a><span class="k">-</span><span class="w"> </span>Keep <span class="sb">`index.md`</span>'s <span class="gs">**Documentation Structure**</span> table in sync with the nav —
|
||||
</span><span id="__span-1-79"><a id="__codelineno-1-79" name="__codelineno-1-79"></a> it is the human-facing version of the same TOC. Every nav entry needs a row
|
||||
</span><span id="__span-1-80"><a id="__codelineno-1-80" name="__codelineno-1-80"></a> (or nested bullet group) there.
|
||||
</span><span id="__span-1-81"><a id="__codelineno-1-81" name="__codelineno-1-81"></a><span class="k">-</span><span class="w"> </span>Nav label = human title (title case), not the filename slug.
|
||||
</span><span id="__span-1-82"><a id="__codelineno-1-82" name="__codelineno-1-82"></a>
|
||||
</span><span id="__span-1-83"><a id="__codelineno-1-83" name="__codelineno-1-83"></a>---
|
||||
</span><span id="__span-1-84"><a id="__codelineno-1-84" name="__codelineno-1-84"></a>
|
||||
</span><span id="__span-1-85"><a id="__codelineno-1-85" name="__codelineno-1-85"></a><span class="gu">## 4. Page anatomy</span>
|
||||
</span><span id="__span-1-69"><a id="__codelineno-1-69" name="__codelineno-1-69"></a>---
|
||||
</span><span id="__span-1-70"><a id="__codelineno-1-70" name="__codelineno-1-70"></a>
|
||||
</span><span id="__span-1-71"><a id="__codelineno-1-71" name="__codelineno-1-71"></a><span class="gu">## 3. Navigation — `docs/mkdocs.wiki.yml` is the source of truth</span>
|
||||
</span><span id="__span-1-72"><a id="__codelineno-1-72" name="__codelineno-1-72"></a>
|
||||
</span><span id="__span-1-73"><a id="__codelineno-1-73" name="__codelineno-1-73"></a>Every wiki page <span class="gs">**must**</span> be wired into the nav defined in
|
||||
</span><span id="__span-1-74"><a id="__codelineno-1-74" name="__codelineno-1-74"></a><span class="sb">`docs/mkdocs.wiki.yml`</span>. If a page is not in the nav, it is orphaned.
|
||||
</span><span id="__span-1-75"><a id="__codelineno-1-75" name="__codelineno-1-75"></a>
|
||||
</span><span id="__span-1-76"><a id="__codelineno-1-76" name="__codelineno-1-76"></a><span class="k">-</span><span class="w"> </span>The <span class="sb">`nav:`</span> block mirrors the directory tree; directories become nested
|
||||
</span><span id="__span-1-77"><a id="__codelineno-1-77" name="__codelineno-1-77"></a> groups.
|
||||
</span><span id="__span-1-78"><a id="__codelineno-1-78" name="__codelineno-1-78"></a><span class="k">-</span><span class="w"> </span>When a section has many pages, group them <span class="gs">**by theme**</span> into nested
|
||||
</span><span id="__span-1-79"><a id="__codelineno-1-79" name="__codelineno-1-79"></a> subgroups. mongo-ops groups its use cases into:
|
||||
</span><span id="__span-1-80"><a id="__codelineno-1-80" name="__codelineno-1-80"></a> <span class="sb">`Getting Started`</span>, <span class="sb">`Data & Queries`</span>, <span class="sb">`Caching`</span>, <span class="sb">`Population`</span>,
|
||||
</span><span id="__span-1-81"><a id="__codelineno-1-81" name="__codelineno-1-81"></a> <span class="sb">`Advanced Usage`</span>.
|
||||
</span><span id="__span-1-82"><a id="__codelineno-1-82" name="__codelineno-1-82"></a><span class="k">-</span><span class="w"> </span>Keep <span class="sb">`index.md`</span>'s <span class="gs">**Documentation Structure**</span> table in sync with the nav —
|
||||
</span><span id="__span-1-83"><a id="__codelineno-1-83" name="__codelineno-1-83"></a> it is the human-facing version of the same TOC. Every nav entry needs a row
|
||||
</span><span id="__span-1-84"><a id="__codelineno-1-84" name="__codelineno-1-84"></a> (or nested bullet group) there.
|
||||
</span><span id="__span-1-85"><a id="__codelineno-1-85" name="__codelineno-1-85"></a><span class="k">-</span><span class="w"> </span>Nav label = human title (title case), not the filename slug.
|
||||
</span><span id="__span-1-86"><a id="__codelineno-1-86" name="__codelineno-1-86"></a>
|
||||
</span><span id="__span-1-87"><a id="__codelineno-1-87" name="__codelineno-1-87"></a><span class="gu">### 4.1 `index.md` (Home)</span>
|
||||
</span><span id="__span-1-87"><a id="__codelineno-1-87" name="__codelineno-1-87"></a>---
|
||||
</span><span id="__span-1-88"><a id="__codelineno-1-88" name="__codelineno-1-88"></a>
|
||||
</span><span id="__span-1-89"><a id="__codelineno-1-89" name="__codelineno-1-89"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-90"><a id="__codelineno-1-90" name="__codelineno-1-90"></a><span class="sb"># 🧩 <package> — <slogan></span>
|
||||
</span><span id="__span-1-91"><a id="__codelineno-1-91" name="__codelineno-1-91"></a><span class="sb"><one-paragraph pitch></span>
|
||||
</span><span id="__span-1-89"><a id="__codelineno-1-89" name="__codelineno-1-89"></a><span class="gu">## 4. Page anatomy</span>
|
||||
</span><span id="__span-1-90"><a id="__codelineno-1-90" name="__codelineno-1-90"></a>
|
||||
</span><span id="__span-1-91"><a id="__codelineno-1-91" name="__codelineno-1-91"></a><span class="gu">### 4.1 `index.md` (Home)</span>
|
||||
</span><span id="__span-1-92"><a id="__codelineno-1-92" name="__codelineno-1-92"></a>
|
||||
</span><span id="__span-1-93"><a id="__codelineno-1-93" name="__codelineno-1-93"></a><span class="sb">> **Doc model:** … (see §1)</span>
|
||||
</span><span id="__span-1-94"><a id="__codelineno-1-94" name="__codelineno-1-94"></a>
|
||||
</span><span id="__span-1-95"><a id="__codelineno-1-95" name="__codelineno-1-95"></a><span class="sb">---</span>
|
||||
</span><span id="__span-1-93"><a id="__codelineno-1-93" name="__codelineno-1-93"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-94"><a id="__codelineno-1-94" name="__codelineno-1-94"></a><span class="sb"># 🧩 <package> — <slogan></span>
|
||||
</span><span id="__span-1-95"><a id="__codelineno-1-95" name="__codelineno-1-95"></a><span class="sb"><one-paragraph pitch></span>
|
||||
</span><span id="__span-1-96"><a id="__codelineno-1-96" name="__codelineno-1-96"></a>
|
||||
</span><span id="__span-1-97"><a id="__codelineno-1-97" name="__codelineno-1-97"></a><span class="sb">## 🚀 Key Features (bullet list, emoji per feature)</span>
|
||||
</span><span id="__span-1-98"><a id="__codelineno-1-98" name="__codelineno-1-98"></a><span class="sb">## 📦 Installation (code blocks: internal PyPI, extras, local source)</span>
|
||||
</span><span id="__span-1-99"><a id="__codelineno-1-99" name="__codelineno-1-99"></a><span class="sb">## 📁 Documentation Structure (table = TOC, mirrors nav exactly)</span>
|
||||
</span><span id="__span-1-100"><a id="__codelineno-1-100" name="__codelineno-1-100"></a><span class="sb">## 🔗 Related Resources (bullets: source repo, internal PyPI, CI)</span>
|
||||
</span><span id="__span-1-101"><a id="__codelineno-1-101" name="__codelineno-1-101"></a><span class="sb">---</span>
|
||||
</span><span id="__span-1-102"><a id="__codelineno-1-102" name="__codelineno-1-102"></a><span class="sb">© Aetoskia Internal — `<package>` <version></span>
|
||||
</span><span id="__span-1-103"><a id="__codelineno-1-103" name="__codelineno-1-103"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-104"><a id="__codelineno-1-104" name="__codelineno-1-104"></a>
|
||||
</span><span id="__span-1-105"><a id="__codelineno-1-105" name="__codelineno-1-105"></a><span class="gu">### 4.2 Overview page (`01_*`)</span>
|
||||
</span><span id="__span-1-106"><a id="__codelineno-1-106" name="__codelineno-1-106"></a>
|
||||
</span><span id="__span-1-107"><a id="__codelineno-1-107" name="__codelineno-1-107"></a><span class="k">-</span><span class="w"> </span>Opens with <span class="sb">`# Library Overview`</span>, one sentence about what the library does,
|
||||
</span><span id="__span-1-108"><a id="__codelineno-1-108" name="__codelineno-1-108"></a> then a line stating the page builds the mental model.
|
||||
</span><span id="__span-1-109"><a id="__codelineno-1-109" name="__codelineno-1-109"></a><span class="k">-</span><span class="w"> </span>Sections: <span class="sb">`## 🏗️ Architecture`</span> (ASCII diagram + numbered layer list),
|
||||
</span><span id="__span-1-110"><a id="__codelineno-1-110" name="__codelineno-1-110"></a> <span class="sb">`## 🔄 Lifecycle Rules`</span> (table: step / call / why),
|
||||
</span><span id="__span-1-111"><a id="__codelineno-1-111" name="__codelineno-1-111"></a> <span class="sb">`## 🧭 Which … Should You Use?`</span> (decision table).
|
||||
</span><span id="__span-1-112"><a id="__codelineno-1-112" name="__codelineno-1-112"></a><span class="k">-</span><span class="w"> </span>Ends with <span class="sb">`## ➡️ Read Next`</span> (cross-links to the next pages to read).
|
||||
</span><span id="__span-1-113"><a id="__codelineno-1-113" name="__codelineno-1-113"></a>
|
||||
</span><span id="__span-1-114"><a id="__codelineno-1-114" name="__codelineno-1-114"></a><span class="gu">### 4.3 Components page (`02_*`)</span>
|
||||
</span><span id="__span-1-115"><a id="__codelineno-1-115" name="__codelineno-1-115"></a>
|
||||
</span><span id="__span-1-116"><a id="__codelineno-1-116" name="__codelineno-1-116"></a><span class="k">-</span><span class="w"> </span>Validated reference for the public API surface — describes what each
|
||||
</span><span id="__span-1-117"><a id="__codelineno-1-117" name="__codelineno-1-117"></a> component is for and how the pieces wire together. Keep it usage-level;
|
||||
</span><span id="__span-1-118"><a id="__codelineno-1-118" name="__codelineno-1-118"></a> exact signatures belong in <span class="sb">`docs/lib/`</span>.
|
||||
</span><span id="__span-1-119"><a id="__codelineno-1-119" name="__codelineno-1-119"></a><span class="k">-</span><span class="w"> </span>Anatomy: numbered sections, one per component (<span class="sb">`## 1. MongoConnectionManager`</span>,
|
||||
</span><span id="__span-1-120"><a id="__codelineno-1-120" name="__codelineno-1-120"></a> <span class="sb">`## 2. BaseDocument`</span>, …), with <span class="sb">`### 8.1`</span>-style sub-numbering for related
|
||||
</span><span id="__span-1-121"><a id="__codelineno-1-121" name="__codelineno-1-121"></a> types under a component (e.g. the cache layer's backend / stats / config /
|
||||
</span><span id="__span-1-122"><a id="__codelineno-1-122" name="__codelineno-1-122"></a> in-memory / redis implementations). Ends with <span class="sb">`## Related`</span>.
|
||||
</span><span id="__span-1-123"><a id="__codelineno-1-123" name="__codelineno-1-123"></a>
|
||||
</span><span id="__span-1-124"><a id="__codelineno-1-124" name="__codelineno-1-124"></a><span class="gu">### 4.4 Use-case page (the most common)</span>
|
||||
</span><span id="__span-1-125"><a id="__codelineno-1-125" name="__codelineno-1-125"></a>
|
||||
</span><span id="__span-1-126"><a id="__codelineno-1-126" name="__codelineno-1-126"></a>Standard anatomy, in this order:
|
||||
</span><span id="__span-1-97"><a id="__codelineno-1-97" name="__codelineno-1-97"></a><span class="sb">> **Doc model:** … (see §1)</span>
|
||||
</span><span id="__span-1-98"><a id="__codelineno-1-98" name="__codelineno-1-98"></a>
|
||||
</span><span id="__span-1-99"><a id="__codelineno-1-99" name="__codelineno-1-99"></a><span class="sb">---</span>
|
||||
</span><span id="__span-1-100"><a id="__codelineno-1-100" name="__codelineno-1-100"></a>
|
||||
</span><span id="__span-1-101"><a id="__codelineno-1-101" name="__codelineno-1-101"></a><span class="sb">## 🚀 Key Features (bullet list, emoji per feature)</span>
|
||||
</span><span id="__span-1-102"><a id="__codelineno-1-102" name="__codelineno-1-102"></a><span class="sb">## 📦 Installation (code blocks: internal PyPI, extras, local source)</span>
|
||||
</span><span id="__span-1-103"><a id="__codelineno-1-103" name="__codelineno-1-103"></a><span class="sb">## 📁 Documentation Structure (table = TOC, mirrors nav exactly)</span>
|
||||
</span><span id="__span-1-104"><a id="__codelineno-1-104" name="__codelineno-1-104"></a><span class="sb">## 🔗 Related Resources (bullets: source repo, internal PyPI, CI)</span>
|
||||
</span><span id="__span-1-105"><a id="__codelineno-1-105" name="__codelineno-1-105"></a><span class="sb">---</span>
|
||||
</span><span id="__span-1-106"><a id="__codelineno-1-106" name="__codelineno-1-106"></a><span class="sb">© Aetoskia Internal — `<package>` <version></span>
|
||||
</span><span id="__span-1-107"><a id="__codelineno-1-107" name="__codelineno-1-107"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-108"><a id="__codelineno-1-108" name="__codelineno-1-108"></a>
|
||||
</span><span id="__span-1-109"><a id="__codelineno-1-109" name="__codelineno-1-109"></a><span class="gu">### 4.2 Overview page (`01_*`)</span>
|
||||
</span><span id="__span-1-110"><a id="__codelineno-1-110" name="__codelineno-1-110"></a>
|
||||
</span><span id="__span-1-111"><a id="__codelineno-1-111" name="__codelineno-1-111"></a><span class="k">-</span><span class="w"> </span>Opens with <span class="sb">`# Library Overview`</span>, one sentence about what the library does,
|
||||
</span><span id="__span-1-112"><a id="__codelineno-1-112" name="__codelineno-1-112"></a> then a line stating the page builds the mental model.
|
||||
</span><span id="__span-1-113"><a id="__codelineno-1-113" name="__codelineno-1-113"></a><span class="k">-</span><span class="w"> </span>Sections: <span class="sb">`## 🏗️ Architecture`</span> (ASCII diagram + numbered layer list),
|
||||
</span><span id="__span-1-114"><a id="__codelineno-1-114" name="__codelineno-1-114"></a> <span class="sb">`## 🔄 Lifecycle Rules`</span> (table: step / call / why),
|
||||
</span><span id="__span-1-115"><a id="__codelineno-1-115" name="__codelineno-1-115"></a> <span class="sb">`## 🧭 Which … Should You Use?`</span> (decision table).
|
||||
</span><span id="__span-1-116"><a id="__codelineno-1-116" name="__codelineno-1-116"></a><span class="k">-</span><span class="w"> </span>Ends with <span class="sb">`## ➡️ Read Next`</span> (cross-links to the next pages to read).
|
||||
</span><span id="__span-1-117"><a id="__codelineno-1-117" name="__codelineno-1-117"></a>
|
||||
</span><span id="__span-1-118"><a id="__codelineno-1-118" name="__codelineno-1-118"></a><span class="gu">### 4.3 Components page (`02_*`)</span>
|
||||
</span><span id="__span-1-119"><a id="__codelineno-1-119" name="__codelineno-1-119"></a>
|
||||
</span><span id="__span-1-120"><a id="__codelineno-1-120" name="__codelineno-1-120"></a><span class="k">-</span><span class="w"> </span>Validated reference for the public API surface — describes what each
|
||||
</span><span id="__span-1-121"><a id="__codelineno-1-121" name="__codelineno-1-121"></a> component is for and how the pieces wire together. Keep it usage-level;
|
||||
</span><span id="__span-1-122"><a id="__codelineno-1-122" name="__codelineno-1-122"></a> exact signatures belong in <span class="sb">`docs/lib/`</span>.
|
||||
</span><span id="__span-1-123"><a id="__codelineno-1-123" name="__codelineno-1-123"></a><span class="k">-</span><span class="w"> </span>Anatomy: numbered sections, one per component (<span class="sb">`## 1. MongoConnectionManager`</span>,
|
||||
</span><span id="__span-1-124"><a id="__codelineno-1-124" name="__codelineno-1-124"></a> <span class="sb">`## 2. BaseDocument`</span>, …), with <span class="sb">`### 8.1`</span>-style sub-numbering for related
|
||||
</span><span id="__span-1-125"><a id="__codelineno-1-125" name="__codelineno-1-125"></a> types under a component (e.g. the cache layer's backend / stats / config /
|
||||
</span><span id="__span-1-126"><a id="__codelineno-1-126" name="__codelineno-1-126"></a> in-memory / redis implementations). Ends with <span class="sb">`## Related`</span>.
|
||||
</span><span id="__span-1-127"><a id="__codelineno-1-127" name="__codelineno-1-127"></a>
|
||||
</span><span id="__span-1-128"><a id="__codelineno-1-128" name="__codelineno-1-128"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-129"><a id="__codelineno-1-129" name="__codelineno-1-129"></a><span class="sb"># Use Case N: <Human Title></span>
|
||||
</span><span id="__span-1-130"><a id="__codelineno-1-130" name="__codelineno-1-130"></a>
|
||||
</span><span id="__span-1-131"><a id="__codelineno-1-131" name="__codelineno-1-131"></a><span class="sb">**Scenario:** <one sentence: the problem this recipe solves></span>
|
||||
</span><span id="__span-1-132"><a id="__codelineno-1-132" name="__codelineno-1-132"></a>
|
||||
</span><span id="__span-1-133"><a id="__codelineno-1-133" name="__codelineno-1-133"></a><span class="sb">---</span>
|
||||
</span><span id="__span-1-128"><a id="__codelineno-1-128" name="__codelineno-1-128"></a><span class="gu">### 4.4 Use-case page (the most common)</span>
|
||||
</span><span id="__span-1-129"><a id="__codelineno-1-129" name="__codelineno-1-129"></a>
|
||||
</span><span id="__span-1-130"><a id="__codelineno-1-130" name="__codelineno-1-130"></a>Standard anatomy, in this order:
|
||||
</span><span id="__span-1-131"><a id="__codelineno-1-131" name="__codelineno-1-131"></a>
|
||||
</span><span id="__span-1-132"><a id="__codelineno-1-132" name="__codelineno-1-132"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-133"><a id="__codelineno-1-133" name="__codelineno-1-133"></a><span class="sb"># Use Case N: <Human Title></span>
|
||||
</span><span id="__span-1-134"><a id="__codelineno-1-134" name="__codelineno-1-134"></a>
|
||||
</span><span id="__span-1-135"><a id="__codelineno-1-135" name="__codelineno-1-135"></a><span class="sb">## 📦 What's New? (table: Component | Description — new API used here)</span>
|
||||
</span><span id="__span-1-136"><a id="__codelineno-1-136" name="__codelineno-1-136"></a><span class="sb">## 🚀 Example (languaged code block, complete runnable-looking snippet)</span>
|
||||
</span><span id="__span-1-137"><a id="__codelineno-1-137" name="__codelineno-1-137"></a><span class="sb">## 💡 Tips (bullets: gotchas, ordering, common mistakes)</span>
|
||||
</span><span id="__span-1-138"><a id="__codelineno-1-138" name="__codelineno-1-138"></a><span class="sb">## Related (§5)</span>
|
||||
</span><span id="__span-1-139"><a id="__codelineno-1-139" name="__codelineno-1-139"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-140"><a id="__codelineno-1-140" name="__codelineno-1-140"></a>
|
||||
</span><span id="__span-1-141"><a id="__codelineno-1-141" name="__codelineno-1-141"></a><span class="gu">### 4.5 Deep-dive / worked-example page</span>
|
||||
</span><span id="__span-1-142"><a id="__codelineno-1-142" name="__codelineno-1-142"></a>
|
||||
</span><span id="__span-1-143"><a id="__codelineno-1-143" name="__codelineno-1-143"></a>For intricate flows (population shapes, cache round-trips), use numbered
|
||||
</span><span id="__span-1-144"><a id="__codelineno-1-144" name="__codelineno-1-144"></a>depth-first sections and comparison tables:
|
||||
</span><span id="__span-1-145"><a id="__codelineno-1-145" name="__codelineno-1-145"></a>
|
||||
</span><span id="__span-1-146"><a id="__codelineno-1-146" name="__codelineno-1-146"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-147"><a id="__codelineno-1-147" name="__codelineno-1-147"></a><span class="sb">## 1. <Write path> (### 1a., ### 1b., … per sub-case)</span>
|
||||
</span><span id="__span-1-148"><a id="__codelineno-1-148" name="__codelineno-1-148"></a><span class="sb">## 2. <Read path></span>
|
||||
</span><span id="__span-1-149"><a id="__codelineno-1-149" name="__codelineno-1-149"></a><span class="sb">## 3. <Round trip / tricky bit></span>
|
||||
</span><span id="__span-1-150"><a id="__codelineno-1-150" name="__codelineno-1-150"></a><span class="sb">## 4. When to use which (comparison table)</span>
|
||||
</span><span id="__span-1-151"><a id="__codelineno-1-151" name="__codelineno-1-151"></a><span class="sb">## Related</span>
|
||||
</span><span id="__span-1-152"><a id="__codelineno-1-152" name="__codelineno-1-152"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-153"><a id="__codelineno-1-153" name="__codelineno-1-153"></a>
|
||||
</span><span id="__span-1-154"><a id="__codelineno-1-154" name="__codelineno-1-154"></a><span class="gu">### 4.6 Best Practices page (`04_*`)</span>
|
||||
</span><span id="__span-1-155"><a id="__codelineno-1-155" name="__codelineno-1-155"></a>
|
||||
</span><span id="__span-1-156"><a id="__codelineno-1-156" name="__codelineno-1-156"></a><span class="k">-</span><span class="w"> </span>Flat themed <span class="sb">`##`</span> sections (e.g. Layering, Lifecycle, Data & Performance,
|
||||
</span><span id="__span-1-157"><a id="__codelineno-1-157" name="__codelineno-1-157"></a> Transactions & Errors, Testing), each a short list of numbered conventions.
|
||||
</span><span id="__span-1-158"><a id="__codelineno-1-158" name="__codelineno-1-158"></a><span class="k">-</span><span class="w"> </span>Pure prose — no large code blocks.
|
||||
</span><span id="__span-1-135"><a id="__codelineno-1-135" name="__codelineno-1-135"></a><span class="sb">**Scenario:** <one sentence: the problem this recipe solves></span>
|
||||
</span><span id="__span-1-136"><a id="__codelineno-1-136" name="__codelineno-1-136"></a>
|
||||
</span><span id="__span-1-137"><a id="__codelineno-1-137" name="__codelineno-1-137"></a><span class="sb">---</span>
|
||||
</span><span id="__span-1-138"><a id="__codelineno-1-138" name="__codelineno-1-138"></a>
|
||||
</span><span id="__span-1-139"><a id="__codelineno-1-139" name="__codelineno-1-139"></a><span class="sb">## 📦 What's New? (table: Component | Description — new API used here)</span>
|
||||
</span><span id="__span-1-140"><a id="__codelineno-1-140" name="__codelineno-1-140"></a><span class="sb">## 🚀 Example (languaged code block, complete runnable-looking snippet)</span>
|
||||
</span><span id="__span-1-141"><a id="__codelineno-1-141" name="__codelineno-1-141"></a><span class="sb">## 💡 Tips (bullets: gotchas, ordering, common mistakes)</span>
|
||||
</span><span id="__span-1-142"><a id="__codelineno-1-142" name="__codelineno-1-142"></a><span class="sb">## Related (§5)</span>
|
||||
</span><span id="__span-1-143"><a id="__codelineno-1-143" name="__codelineno-1-143"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-144"><a id="__codelineno-1-144" name="__codelineno-1-144"></a>
|
||||
</span><span id="__span-1-145"><a id="__codelineno-1-145" name="__codelineno-1-145"></a><span class="gu">### 4.5 Deep-dive / worked-example page</span>
|
||||
</span><span id="__span-1-146"><a id="__codelineno-1-146" name="__codelineno-1-146"></a>
|
||||
</span><span id="__span-1-147"><a id="__codelineno-1-147" name="__codelineno-1-147"></a>For intricate flows (population shapes, cache round-trips), use numbered
|
||||
</span><span id="__span-1-148"><a id="__codelineno-1-148" name="__codelineno-1-148"></a>depth-first sections and comparison tables:
|
||||
</span><span id="__span-1-149"><a id="__codelineno-1-149" name="__codelineno-1-149"></a>
|
||||
</span><span id="__span-1-150"><a id="__codelineno-1-150" name="__codelineno-1-150"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-151"><a id="__codelineno-1-151" name="__codelineno-1-151"></a><span class="sb">## 1. <Write path> (### 1a., ### 1b., … per sub-case)</span>
|
||||
</span><span id="__span-1-152"><a id="__codelineno-1-152" name="__codelineno-1-152"></a><span class="sb">## 2. <Read path></span>
|
||||
</span><span id="__span-1-153"><a id="__codelineno-1-153" name="__codelineno-1-153"></a><span class="sb">## 3. <Round trip / tricky bit></span>
|
||||
</span><span id="__span-1-154"><a id="__codelineno-1-154" name="__codelineno-1-154"></a><span class="sb">## 4. When to use which (comparison table)</span>
|
||||
</span><span id="__span-1-155"><a id="__codelineno-1-155" name="__codelineno-1-155"></a><span class="sb">## Related</span>
|
||||
</span><span id="__span-1-156"><a id="__codelineno-1-156" name="__codelineno-1-156"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-157"><a id="__codelineno-1-157" name="__codelineno-1-157"></a>
|
||||
</span><span id="__span-1-158"><a id="__codelineno-1-158" name="__codelineno-1-158"></a><span class="gu">### 4.6 Best Practices page (`04_*`)</span>
|
||||
</span><span id="__span-1-159"><a id="__codelineno-1-159" name="__codelineno-1-159"></a>
|
||||
</span><span id="__span-1-160"><a id="__codelineno-1-160" name="__codelineno-1-160"></a><span class="gu">### 4.7 Error Handling (`06_*`) / Testing pages</span>
|
||||
</span><span id="__span-1-161"><a id="__codelineno-1-161" name="__codelineno-1-161"></a>
|
||||
</span><span id="__span-1-162"><a id="__codelineno-1-162" name="__codelineno-1-162"></a><span class="k">-</span><span class="w"> </span><span class="gs">**Error Handling:**</span> an exceptions table (<span class="sb">`Exception | Source | Meaning / fix`</span>),
|
||||
</span><span id="__span-1-163"><a id="__codelineno-1-163" name="__codelineno-1-163"></a> a <span class="sb">`> `</span> note on which failures are by design, a <span class="sb">`## 🚀 FastAPI Mapping Example`</span>
|
||||
</span><span id="__span-1-164"><a id="__codelineno-1-164" name="__codelineno-1-164"></a> code block, then <span class="sb">`## 💡 Tips`</span> bullets, then <span class="sb">`## Related`</span>.
|
||||
</span><span id="__span-1-165"><a id="__codelineno-1-165" name="__codelineno-1-165"></a><span class="k">-</span><span class="w"> </span>**Testing example (<span class="sb">`07_*`</span>):** <span class="sb">`## 🚀 Mock-Based Quickstart`</span> (focused code
|
||||
</span><span id="__span-1-166"><a id="__codelineno-1-166" name="__codelineno-1-166"></a> block), <span class="sb">`## 💡 Notes`</span> tip list, <span class="sb">`## Related`</span>.
|
||||
</span><span id="__span-1-167"><a id="__codelineno-1-167" name="__codelineno-1-167"></a>
|
||||
</span><span id="__span-1-168"><a id="__codelineno-1-168" name="__codelineno-1-168"></a>Common to all pages: no frontmatter, <span class="sb">`---`</span> between every major section, and a
|
||||
</span><span id="__span-1-169"><a id="__codelineno-1-169" name="__codelineno-1-169"></a><span class="sb">`## Related`</span> (or variant) footer as the <span class="gs">**last**</span> section.
|
||||
</span><span id="__span-1-170"><a id="__codelineno-1-170" name="__codelineno-1-170"></a>
|
||||
</span><span id="__span-1-171"><a id="__codelineno-1-171" name="__codelineno-1-171"></a>---
|
||||
</span><span id="__span-1-172"><a id="__codelineno-1-172" name="__codelineno-1-172"></a>
|
||||
</span><span id="__span-1-173"><a id="__codelineno-1-173" name="__codelineno-1-173"></a><span class="gu">## 5. The `## Related` footer</span>
|
||||
</span><span id="__span-1-160"><a id="__codelineno-1-160" name="__codelineno-1-160"></a><span class="k">-</span><span class="w"> </span>Flat themed <span class="sb">`##`</span> sections (e.g. Layering, Lifecycle, Data & Performance,
|
||||
</span><span id="__span-1-161"><a id="__codelineno-1-161" name="__codelineno-1-161"></a> Transactions & Errors, Testing), each a short list of numbered conventions.
|
||||
</span><span id="__span-1-162"><a id="__codelineno-1-162" name="__codelineno-1-162"></a><span class="k">-</span><span class="w"> </span>Pure prose — no large code blocks.
|
||||
</span><span id="__span-1-163"><a id="__codelineno-1-163" name="__codelineno-1-163"></a>
|
||||
</span><span id="__span-1-164"><a id="__codelineno-1-164" name="__codelineno-1-164"></a><span class="gu">### 4.7 Error Handling (`06_*`) / Testing pages</span>
|
||||
</span><span id="__span-1-165"><a id="__codelineno-1-165" name="__codelineno-1-165"></a>
|
||||
</span><span id="__span-1-166"><a id="__codelineno-1-166" name="__codelineno-1-166"></a><span class="k">-</span><span class="w"> </span><span class="gs">**Error Handling:**</span> an exceptions table (<span class="sb">`Exception | Source | Meaning / fix`</span>),
|
||||
</span><span id="__span-1-167"><a id="__codelineno-1-167" name="__codelineno-1-167"></a> a <span class="sb">`> `</span> note on which failures are by design, a <span class="sb">`## 🚀 FastAPI Mapping Example`</span>
|
||||
</span><span id="__span-1-168"><a id="__codelineno-1-168" name="__codelineno-1-168"></a> code block, then <span class="sb">`## 💡 Tips`</span> bullets, then <span class="sb">`## Related`</span>.
|
||||
</span><span id="__span-1-169"><a id="__codelineno-1-169" name="__codelineno-1-169"></a><span class="k">-</span><span class="w"> </span>**Testing example (<span class="sb">`07_*`</span>):** <span class="sb">`## 🚀 Mock-Based Quickstart`</span> (focused code
|
||||
</span><span id="__span-1-170"><a id="__codelineno-1-170" name="__codelineno-1-170"></a> block), <span class="sb">`## 💡 Notes`</span> tip list, <span class="sb">`## Related`</span>.
|
||||
</span><span id="__span-1-171"><a id="__codelineno-1-171" name="__codelineno-1-171"></a>
|
||||
</span><span id="__span-1-172"><a id="__codelineno-1-172" name="__codelineno-1-172"></a>Common to all pages: no frontmatter, <span class="sb">`---`</span> between every major section, and a
|
||||
</span><span id="__span-1-173"><a id="__codelineno-1-173" name="__codelineno-1-173"></a><span class="sb">`## Related`</span> (or variant) footer as the <span class="gs">**last**</span> section.
|
||||
</span><span id="__span-1-174"><a id="__codelineno-1-174" name="__codelineno-1-174"></a>
|
||||
</span><span id="__span-1-175"><a id="__codelineno-1-175" name="__codelineno-1-175"></a>Every page ends with a cross-link footer. Rules:
|
||||
</span><span id="__span-1-175"><a id="__codelineno-1-175" name="__codelineno-1-175"></a>---
|
||||
</span><span id="__span-1-176"><a id="__codelineno-1-176" name="__codelineno-1-176"></a>
|
||||
</span><span id="__span-1-177"><a id="__codelineno-1-177" name="__codelineno-1-177"></a><span class="k">-</span><span class="w"> </span>Always the <span class="gs">**last**</span> section, always preceded by a <span class="sb">`---`</span>.
|
||||
</span><span id="__span-1-178"><a id="__codelineno-1-178" name="__codelineno-1-178"></a><span class="k">-</span><span class="w"> </span>Standard heading: <span class="sb">`## Related`</span> (no emoji).
|
||||
</span><span id="__span-1-179"><a id="__codelineno-1-179" name="__codelineno-1-179"></a><span class="k">-</span><span class="w"> </span>One bullet line; links separated by <span class="sb">` · `</span> (middle dot plus spaces).
|
||||
</span><span id="__span-1-180"><a id="__codelineno-1-180" name="__codelineno-1-180"></a><span class="k">-</span><span class="w"> </span>Link label format: <span class="sb">`[NN – Title](relative_path)`</span> — en-dash, page number, title.
|
||||
</span><span id="__span-1-181"><a id="__codelineno-1-181" name="__codelineno-1-181"></a><span class="k">-</span><span class="w"> </span>Paths are <span class="gs">**relative**</span>: same directory → <span class="sb">`02_custom_repo.md`</span>; parent →
|
||||
</span><span id="__span-1-182"><a id="__codelineno-1-182" name="__codelineno-1-182"></a> <span class="sb">`../01_overview.md`</span>; child → <span class="sb">`03_use_cases/01_basic_crud.md`</span>.
|
||||
</span><span id="__span-1-183"><a id="__codelineno-1-183" name="__codelineno-1-183"></a><span class="k">-</span><span class="w"> </span>Link order follows nav order (each <span class="sb">`Related`</span> points to related next/sibling
|
||||
</span><span id="__span-1-184"><a id="__codelineno-1-184" name="__codelineno-1-184"></a> pages, plus the overview/components anchor).
|
||||
</span><span id="__span-1-185"><a id="__codelineno-1-185" name="__codelineno-1-185"></a>
|
||||
</span><span id="__span-1-186"><a id="__codelineno-1-186" name="__codelineno-1-186"></a>Examples (from mongo-ops):
|
||||
</span><span id="__span-1-187"><a id="__codelineno-1-187" name="__codelineno-1-187"></a>
|
||||
</span><span id="__span-1-188"><a id="__codelineno-1-188" name="__codelineno-1-188"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-189"><a id="__codelineno-1-189" name="__codelineno-1-189"></a><span class="sb">## Related</span>
|
||||
</span><span id="__span-1-190"><a id="__codelineno-1-190" name="__codelineno-1-190"></a><span class="sb">- [02 – Custom repository](02_custom_repo.md) · [04 – Pagination](04_pagination.md) · [Overview](../01_overview.md)</span>
|
||||
</span><span id="__span-1-191"><a id="__codelineno-1-191" name="__codelineno-1-191"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-192"><a id="__codelineno-1-192" name="__codelineno-1-192"></a>
|
||||
</span><span id="__span-1-193"><a id="__codelineno-1-193" name="__codelineno-1-193"></a>Variants:
|
||||
</span><span id="__span-1-194"><a id="__codelineno-1-194" name="__codelineno-1-194"></a>
|
||||
</span><span id="__span-1-195"><a id="__codelineno-1-195" name="__codelineno-1-195"></a><span class="k">-</span><span class="w"> </span><span class="sb">`## ➡️ Read Next`</span> — used on the overview page (linear reading order).
|
||||
</span><span id="__span-1-196"><a id="__codelineno-1-196" name="__codelineno-1-196"></a><span class="k">-</span><span class="w"> </span><span class="sb">`## 🔗 Related Resources`</span> — only on <span class="sb">`index.md`</span>, one bullet per external resource.
|
||||
</span><span id="__span-1-197"><a id="__codelineno-1-197" name="__codelineno-1-197"></a>
|
||||
</span><span id="__span-1-198"><a id="__codelineno-1-198" name="__codelineno-1-198"></a>---
|
||||
</span><span id="__span-1-199"><a id="__codelineno-1-199" name="__codelineno-1-199"></a>
|
||||
</span><span id="__span-1-200"><a id="__codelineno-1-200" name="__codelineno-1-200"></a><span class="gu">## 6. Tone & formatting rules</span>
|
||||
</span><span id="__span-1-177"><a id="__codelineno-1-177" name="__codelineno-1-177"></a><span class="gu">## 5. The `## Related` footer</span>
|
||||
</span><span id="__span-1-178"><a id="__codelineno-1-178" name="__codelineno-1-178"></a>
|
||||
</span><span id="__span-1-179"><a id="__codelineno-1-179" name="__codelineno-1-179"></a>Every page ends with a cross-link footer. Rules:
|
||||
</span><span id="__span-1-180"><a id="__codelineno-1-180" name="__codelineno-1-180"></a>
|
||||
</span><span id="__span-1-181"><a id="__codelineno-1-181" name="__codelineno-1-181"></a><span class="k">-</span><span class="w"> </span>Always the <span class="gs">**last**</span> section, always preceded by a <span class="sb">`---`</span>.
|
||||
</span><span id="__span-1-182"><a id="__codelineno-1-182" name="__codelineno-1-182"></a><span class="k">-</span><span class="w"> </span>Standard heading: <span class="sb">`## Related`</span> (no emoji).
|
||||
</span><span id="__span-1-183"><a id="__codelineno-1-183" name="__codelineno-1-183"></a><span class="k">-</span><span class="w"> </span>One bullet line; links separated by <span class="sb">` · `</span> (middle dot plus spaces).
|
||||
</span><span id="__span-1-184"><a id="__codelineno-1-184" name="__codelineno-1-184"></a><span class="k">-</span><span class="w"> </span>Link label format: <span class="sb">`[NN – Title](relative_path)`</span> — en-dash, page number, title.
|
||||
</span><span id="__span-1-185"><a id="__codelineno-1-185" name="__codelineno-1-185"></a><span class="k">-</span><span class="w"> </span>Paths are <span class="gs">**relative**</span>: same directory → <span class="sb">`02_custom_repo.md`</span>; parent →
|
||||
</span><span id="__span-1-186"><a id="__codelineno-1-186" name="__codelineno-1-186"></a> <span class="sb">`../01_overview.md`</span>; child → <span class="sb">`03_use_cases/01_basic_crud.md`</span>.
|
||||
</span><span id="__span-1-187"><a id="__codelineno-1-187" name="__codelineno-1-187"></a><span class="k">-</span><span class="w"> </span>Link order follows nav order (each <span class="sb">`Related`</span> points to related next/sibling
|
||||
</span><span id="__span-1-188"><a id="__codelineno-1-188" name="__codelineno-1-188"></a> pages, plus the overview/components anchor).
|
||||
</span><span id="__span-1-189"><a id="__codelineno-1-189" name="__codelineno-1-189"></a>
|
||||
</span><span id="__span-1-190"><a id="__codelineno-1-190" name="__codelineno-1-190"></a>Examples (from mongo-ops):
|
||||
</span><span id="__span-1-191"><a id="__codelineno-1-191" name="__codelineno-1-191"></a>
|
||||
</span><span id="__span-1-192"><a id="__codelineno-1-192" name="__codelineno-1-192"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-193"><a id="__codelineno-1-193" name="__codelineno-1-193"></a><span class="sb">## Related</span>
|
||||
</span><span id="__span-1-194"><a id="__codelineno-1-194" name="__codelineno-1-194"></a><span class="sb">- [02 – Custom repository](02_custom_repo.md) · [04 – Pagination](04_pagination.md) · [Overview](../01_overview.md)</span>
|
||||
</span><span id="__span-1-195"><a id="__codelineno-1-195" name="__codelineno-1-195"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-196"><a id="__codelineno-1-196" name="__codelineno-1-196"></a>
|
||||
</span><span id="__span-1-197"><a id="__codelineno-1-197" name="__codelineno-1-197"></a>Variants:
|
||||
</span><span id="__span-1-198"><a id="__codelineno-1-198" name="__codelineno-1-198"></a>
|
||||
</span><span id="__span-1-199"><a id="__codelineno-1-199" name="__codelineno-1-199"></a><span class="k">-</span><span class="w"> </span><span class="sb">`## ➡️ Read Next`</span> — used on the overview page (linear reading order).
|
||||
</span><span id="__span-1-200"><a id="__codelineno-1-200" name="__codelineno-1-200"></a><span class="k">-</span><span class="w"> </span><span class="sb">`## 🔗 Related Resources`</span> — only on <span class="sb">`index.md`</span>, one bullet per external resource.
|
||||
</span><span id="__span-1-201"><a id="__codelineno-1-201" name="__codelineno-1-201"></a>
|
||||
</span><span id="__span-1-202"><a id="__codelineno-1-202" name="__codelineno-1-202"></a><span class="k">-</span><span class="w"> </span><span class="gs">**Written for humans**</span>: short sentences, concrete examples, plain words.
|
||||
</span><span id="__span-1-203"><a id="__codelineno-1-203" name="__codelineno-1-203"></a><span class="k">-</span><span class="w"> </span>Emoji-prefixed H2 headings for recognizable section types
|
||||
</span><span id="__span-1-204"><a id="__codelineno-1-204" name="__codelineno-1-204"></a> (<span class="sb">`📦 What's New?`</span>, <span class="sb">`🚀 Example`</span>, <span class="sb">`💡 Tips`</span>, <span class="sb">`🚀 Key Features`</span>).
|
||||
</span><span id="__span-1-205"><a id="__codelineno-1-205" name="__codelineno-1-205"></a><span class="k">-</span><span class="w"> </span><span class="sb">`---`</span> horizontal rule between every major section.
|
||||
</span><span id="__span-1-206"><a id="__codelineno-1-206" name="__codelineno-1-206"></a><span class="k">-</span><span class="w"> </span>Code blocks always declare a language (```python, ```bash, etc.).
|
||||
</span><span id="__span-1-207"><a id="__codelineno-1-207" name="__codelineno-1-207"></a><span class="k">-</span><span class="w"> </span>Use tables for comparisons and structured decisions; bullets for lists;
|
||||
</span><span id="__span-1-208"><a id="__codelineno-1-208" name="__codelineno-1-208"></a> ASCII diagrams for architecture.
|
||||
</span><span id="__span-1-209"><a id="__codelineno-1-209" name="__codelineno-1-209"></a><span class="k">-</span><span class="w"> </span>Bold key terms inline. Use <span class="sb">`inline code`</span> for symbols/APIs.
|
||||
</span><span id="__span-1-210"><a id="__codelineno-1-210" name="__codelineno-1-210"></a><span class="k">-</span><span class="w"> </span>Keep pages focused: one recipe/purpose per page. If a page balloons past
|
||||
</span><span id="__span-1-211"><a id="__codelineno-1-211" name="__codelineno-1-211"></a> ~10 KB, split it (add a numbered deep-dive page instead).
|
||||
</span><span id="__span-1-212"><a id="__codelineno-1-212" name="__codelineno-1-212"></a><span class="k">-</span><span class="w"> </span>Match tone of existing pages in the repo before writing new ones.
|
||||
</span><span id="__span-1-213"><a id="__codelineno-1-213" name="__codelineno-1-213"></a>
|
||||
</span><span id="__span-1-214"><a id="__codelineno-1-214" name="__codelineno-1-214"></a>---
|
||||
</span><span id="__span-1-215"><a id="__codelineno-1-215" name="__codelineno-1-215"></a>
|
||||
</span><span id="__span-1-216"><a id="__codelineno-1-216" name="__codelineno-1-216"></a><span class="gu">## 7. Build & verify workflow</span>
|
||||
</span><span id="__span-1-217"><a id="__codelineno-1-217" name="__codelineno-1-217"></a>
|
||||
</span><span id="__span-1-218"><a id="__codelineno-1-218" name="__codelineno-1-218"></a>After creating or editing wiki pages:
|
||||
</span><span id="__span-1-219"><a id="__codelineno-1-219" name="__codelineno-1-219"></a>
|
||||
</span><span id="__span-1-220"><a id="__codelineno-1-220" name="__codelineno-1-220"></a><span class="sb">```bash</span>
|
||||
</span><span id="__span-1-221"><a id="__codelineno-1-221" name="__codelineno-1-221"></a><span class="c1"># 1. Build the wiki (from the repo root)</span>
|
||||
</span><span id="__span-1-222"><a id="__codelineno-1-222" name="__codelineno-1-222"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--wiki<span class="w"> </span><span class="c1"># wiki only</span>
|
||||
</span><span id="__span-1-223"><a id="__codelineno-1-223" name="__codelineno-1-223"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--wiki<span class="w"> </span>--mkdocs<span class="w"> </span>--module<span class="w"> </span><pkg><span class="w"> </span><span class="c1"># wiki + lib together</span>
|
||||
</span><span id="__span-1-224"><a id="__codelineno-1-224" name="__codelineno-1-224"></a>
|
||||
</span><span id="__span-1-225"><a id="__codelineno-1-225" name="__codelineno-1-225"></a><span class="c1"># 2. Preview locally</span>
|
||||
</span><span id="__span-1-226"><a id="__codelineno-1-226" name="__codelineno-1-226"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--wiki
|
||||
</span><span id="__span-1-202"><a id="__codelineno-1-202" name="__codelineno-1-202"></a>---
|
||||
</span><span id="__span-1-203"><a id="__codelineno-1-203" name="__codelineno-1-203"></a>
|
||||
</span><span id="__span-1-204"><a id="__codelineno-1-204" name="__codelineno-1-204"></a><span class="gu">## 6. Tone & formatting rules</span>
|
||||
</span><span id="__span-1-205"><a id="__codelineno-1-205" name="__codelineno-1-205"></a>
|
||||
</span><span id="__span-1-206"><a id="__codelineno-1-206" name="__codelineno-1-206"></a><span class="k">-</span><span class="w"> </span><span class="gs">**Written for humans**</span>: short sentences, concrete examples, plain words.
|
||||
</span><span id="__span-1-207"><a id="__codelineno-1-207" name="__codelineno-1-207"></a><span class="k">-</span><span class="w"> </span>Emoji-prefixed H2 headings for recognizable section types
|
||||
</span><span id="__span-1-208"><a id="__codelineno-1-208" name="__codelineno-1-208"></a> (<span class="sb">`📦 What's New?`</span>, <span class="sb">`🚀 Example`</span>, <span class="sb">`💡 Tips`</span>, <span class="sb">`🚀 Key Features`</span>).
|
||||
</span><span id="__span-1-209"><a id="__codelineno-1-209" name="__codelineno-1-209"></a><span class="k">-</span><span class="w"> </span><span class="sb">`---`</span> horizontal rule between every major section.
|
||||
</span><span id="__span-1-210"><a id="__codelineno-1-210" name="__codelineno-1-210"></a><span class="k">-</span><span class="w"> </span>Code blocks always declare a language (```python, ```bash, etc.).
|
||||
</span><span id="__span-1-211"><a id="__codelineno-1-211" name="__codelineno-1-211"></a><span class="k">-</span><span class="w"> </span>Use tables for comparisons and structured decisions; bullets for lists;
|
||||
</span><span id="__span-1-212"><a id="__codelineno-1-212" name="__codelineno-1-212"></a> ASCII diagrams for architecture.
|
||||
</span><span id="__span-1-213"><a id="__codelineno-1-213" name="__codelineno-1-213"></a><span class="k">-</span><span class="w"> </span>Bold key terms inline. Use <span class="sb">`inline code`</span> for symbols/APIs.
|
||||
</span><span id="__span-1-214"><a id="__codelineno-1-214" name="__codelineno-1-214"></a><span class="k">-</span><span class="w"> </span>Keep pages focused: one recipe/purpose per page. If a page balloons past
|
||||
</span><span id="__span-1-215"><a id="__codelineno-1-215" name="__codelineno-1-215"></a> ~10 KB, split it (add a numbered deep-dive page instead).
|
||||
</span><span id="__span-1-216"><a id="__codelineno-1-216" name="__codelineno-1-216"></a><span class="k">-</span><span class="w"> </span>Match tone of existing pages in the repo before writing new ones.
|
||||
</span><span id="__span-1-217"><a id="__codelineno-1-217" name="__codelineno-1-217"></a><span class="k">-</span><span class="w"> </span>Ground every <span class="sb">`## 🚀 Example`</span>, <span class="sb">`💡 Tips`</span>, and <span class="sb">`📦 What's New?`</span> row in the
|
||||
</span><span id="__span-1-218"><a id="__codelineno-1-218" name="__codelineno-1-218"></a> library's actual source, tests, and its <span class="sb">`docs/mcp`</span> bundle — never invent
|
||||
</span><span id="__span-1-219"><a id="__codelineno-1-219" name="__codelineno-1-219"></a> APIs or behavior. Signatures and exceptions come from the code; gotchas
|
||||
</span><span id="__span-1-220"><a id="__codelineno-1-220" name="__codelineno-1-220"></a> come from the tests.
|
||||
</span><span id="__span-1-221"><a id="__codelineno-1-221" name="__codelineno-1-221"></a>
|
||||
</span><span id="__span-1-222"><a id="__codelineno-1-222" name="__codelineno-1-222"></a>---
|
||||
</span><span id="__span-1-223"><a id="__codelineno-1-223" name="__codelineno-1-223"></a>
|
||||
</span><span id="__span-1-224"><a id="__codelineno-1-224" name="__codelineno-1-224"></a><span class="gu">## 7. Build & verify workflow</span>
|
||||
</span><span id="__span-1-225"><a id="__codelineno-1-225" name="__codelineno-1-225"></a>
|
||||
</span><span id="__span-1-226"><a id="__codelineno-1-226" name="__codelineno-1-226"></a>After creating or editing wiki pages:
|
||||
</span><span id="__span-1-227"><a id="__codelineno-1-227" name="__codelineno-1-227"></a>
|
||||
</span><span id="__span-1-228"><a id="__codelineno-1-228" name="__codelineno-1-228"></a><span class="c1"># 3. Collect into the hub (run from the docs/ service repo)</span>
|
||||
</span><span id="__span-1-229"><a id="__codelineno-1-229" name="__codelineno-1-229"></a>python<span class="w"> </span>collect.py<span class="w"> </span><span class="c1"># copies site, regenerates index + nginx.conf</span>
|
||||
</span><span id="__span-1-230"><a id="__codelineno-1-230" name="__codelineno-1-230"></a>python<span class="w"> </span>collect.py<span class="w"> </span>--dry-run<span class="w"> </span><span class="c1"># preview without writing</span>
|
||||
</span><span id="__span-1-231"><a id="__codelineno-1-231" name="__codelineno-1-231"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-228"><a id="__codelineno-1-228" name="__codelineno-1-228"></a><span class="sb">```bash</span>
|
||||
</span><span id="__span-1-229"><a id="__codelineno-1-229" name="__codelineno-1-229"></a><span class="c1"># 1. Build the wiki (from the repo root)</span>
|
||||
</span><span id="__span-1-230"><a id="__codelineno-1-230" name="__codelineno-1-230"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--wiki<span class="w"> </span><span class="c1"># wiki only</span>
|
||||
</span><span id="__span-1-231"><a id="__codelineno-1-231" name="__codelineno-1-231"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--wiki<span class="w"> </span>--mkdocs<span class="w"> </span>--module<span class="w"> </span><pkg><span class="w"> </span><span class="c1"># wiki + lib together</span>
|
||||
</span><span id="__span-1-232"><a id="__codelineno-1-232" name="__codelineno-1-232"></a>
|
||||
</span><span id="__span-1-233"><a id="__codelineno-1-233" name="__codelineno-1-233"></a>Verification checklist:
|
||||
</span><span id="__span-1-234"><a id="__codelineno-1-234" name="__codelineno-1-234"></a>
|
||||
</span><span id="__span-1-235"><a id="__codelineno-1-235" name="__codelineno-1-235"></a><span class="k">-</span><span class="w"> </span><span class="sb">`doc-forge build --wiki`</span> completes with no warnings about missing files.
|
||||
</span><span id="__span-1-236"><a id="__codelineno-1-236" name="__codelineno-1-236"></a><span class="k">-</span><span class="w"> </span>Every new page is present in <span class="sb">`docs/mkdocs.wiki.yml`</span> <span class="gs">**and**</span> in the index
|
||||
</span><span id="__span-1-237"><a id="__codelineno-1-237" name="__codelineno-1-237"></a> Documentation Structure table.
|
||||
</span><span id="__span-1-238"><a id="__codelineno-1-238" name="__codelineno-1-238"></a><span class="k">-</span><span class="w"> </span>Every page ends with a <span class="sb">`## Related`</span> block and no dead links (paths resolve).
|
||||
</span><span id="__span-1-239"><a id="__codelineno-1-239" name="__codelineno-1-239"></a><span class="k">-</span><span class="w"> </span>After <span class="sb">`collect.py`</span>: the hub card links to both <span class="sb">`/wiki/`</span> and <span class="sb">`/lib/`</span> and the
|
||||
</span><span id="__span-1-240"><a id="__codelineno-1-240" name="__codelineno-1-240"></a> pages render (spot-check with the served site).
|
||||
</span><span id="__span-1-241"><a id="__codelineno-1-241" name="__codelineno-1-241"></a><span class="k">-</span><span class="w"> </span>If code/docstrings changed (no change when wiki-only), run the repo gates:
|
||||
</span><span id="__span-1-242"><a id="__codelineno-1-242" name="__codelineno-1-242"></a> <span class="sb">`black`</span>, <span class="sb">`ruff`</span>, <span class="sb">`mypy`</span>, <span class="sb">`pytest`</span>.
|
||||
</span><span id="__span-1-243"><a id="__codelineno-1-243" name="__codelineno-1-243"></a>
|
||||
</span><span id="__span-1-244"><a id="__codelineno-1-244" name="__codelineno-1-244"></a>---
|
||||
</span><span id="__span-1-245"><a id="__codelineno-1-245" name="__codelineno-1-245"></a>
|
||||
</span><span id="__span-1-246"><a id="__codelineno-1-246" name="__codelineno-1-246"></a><span class="gu">## 8. Before/after checklist</span>
|
||||
</span><span id="__span-1-247"><a id="__codelineno-1-247" name="__codelineno-1-247"></a>
|
||||
</span><span id="__span-1-248"><a id="__codelineno-1-248" name="__codelineno-1-248"></a><span class="gs">**Before creating a page:**</span>
|
||||
</span><span id="__span-1-249"><a id="__codelineno-1-249" name="__codelineno-1-249"></a>
|
||||
</span><span id="__span-1-250"><a id="__codelineno-1-250" name="__codelineno-1-250"></a><span class="k">- [ ]</span> Confirm it is genuinely wiki material (how-to) and not API contract.
|
||||
</span><span id="__span-1-251"><a id="__codelineno-1-251" name="__codelineno-1-251"></a><span class="k">- [ ]</span> Find the right filename (<span class="sb">`NN_snake_case.md`</span>) and directory for its theme.
|
||||
</span><span id="__span-1-252"><a id="__codelineno-1-252" name="__codelineno-1-252"></a><span class="k">- [ ]</span> Outline the sections per §4 anatomy that fits the content.
|
||||
</span><span id="__span-1-233"><a id="__codelineno-1-233" name="__codelineno-1-233"></a><span class="c1"># 2. Preview locally</span>
|
||||
</span><span id="__span-1-234"><a id="__codelineno-1-234" name="__codelineno-1-234"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--wiki
|
||||
</span><span id="__span-1-235"><a id="__codelineno-1-235" name="__codelineno-1-235"></a>
|
||||
</span><span id="__span-1-236"><a id="__codelineno-1-236" name="__codelineno-1-236"></a><span class="c1"># 3. Collect into the hub (run from the docs/ service repo)</span>
|
||||
</span><span id="__span-1-237"><a id="__codelineno-1-237" name="__codelineno-1-237"></a>python<span class="w"> </span>collect.py<span class="w"> </span><span class="c1"># copies site, regenerates index + nginx.conf</span>
|
||||
</span><span id="__span-1-238"><a id="__codelineno-1-238" name="__codelineno-1-238"></a>python<span class="w"> </span>collect.py<span class="w"> </span>--dry-run<span class="w"> </span><span class="c1"># preview without writing</span>
|
||||
</span><span id="__span-1-239"><a id="__codelineno-1-239" name="__codelineno-1-239"></a><span class="sb">```</span>
|
||||
</span><span id="__span-1-240"><a id="__codelineno-1-240" name="__codelineno-1-240"></a>
|
||||
</span><span id="__span-1-241"><a id="__codelineno-1-241" name="__codelineno-1-241"></a>Verification checklist:
|
||||
</span><span id="__span-1-242"><a id="__codelineno-1-242" name="__codelineno-1-242"></a>
|
||||
</span><span id="__span-1-243"><a id="__codelineno-1-243" name="__codelineno-1-243"></a><span class="k">-</span><span class="w"> </span><span class="sb">`doc-forge build --wiki`</span> completes with no warnings about missing files.
|
||||
</span><span id="__span-1-244"><a id="__codelineno-1-244" name="__codelineno-1-244"></a><span class="k">-</span><span class="w"> </span>Every new page is present in <span class="sb">`docs/mkdocs.wiki.yml`</span> <span class="gs">**and**</span> in the index
|
||||
</span><span id="__span-1-245"><a id="__codelineno-1-245" name="__codelineno-1-245"></a> Documentation Structure table.
|
||||
</span><span id="__span-1-246"><a id="__codelineno-1-246" name="__codelineno-1-246"></a><span class="k">-</span><span class="w"> </span>Every page ends with a <span class="sb">`## Related`</span> block and no dead links (paths resolve).
|
||||
</span><span id="__span-1-247"><a id="__codelineno-1-247" name="__codelineno-1-247"></a><span class="k">-</span><span class="w"> </span>After <span class="sb">`collect.py`</span>: the hub card links to both <span class="sb">`/wiki/`</span> and <span class="sb">`/lib/`</span> and the
|
||||
</span><span id="__span-1-248"><a id="__codelineno-1-248" name="__codelineno-1-248"></a> pages render (spot-check with the served site).
|
||||
</span><span id="__span-1-249"><a id="__codelineno-1-249" name="__codelineno-1-249"></a><span class="k">-</span><span class="w"> </span>If code/docstrings changed (no change when wiki-only), run the repo gates:
|
||||
</span><span id="__span-1-250"><a id="__codelineno-1-250" name="__codelineno-1-250"></a> <span class="sb">`black`</span>, <span class="sb">`ruff`</span>, <span class="sb">`mypy`</span>, <span class="sb">`pytest`</span>.
|
||||
</span><span id="__span-1-251"><a id="__codelineno-1-251" name="__codelineno-1-251"></a>
|
||||
</span><span id="__span-1-252"><a id="__codelineno-1-252" name="__codelineno-1-252"></a>---
|
||||
</span><span id="__span-1-253"><a id="__codelineno-1-253" name="__codelineno-1-253"></a>
|
||||
</span><span id="__span-1-254"><a id="__codelineno-1-254" name="__codelineno-1-254"></a><span class="gs">**After creating/editing a page:**</span>
|
||||
</span><span id="__span-1-254"><a id="__codelineno-1-254" name="__codelineno-1-254"></a><span class="gu">## 8. Before/after checklist</span>
|
||||
</span><span id="__span-1-255"><a id="__codelineno-1-255" name="__codelineno-1-255"></a>
|
||||
</span><span id="__span-1-256"><a id="__codelineno-1-256" name="__codelineno-1-256"></a><span class="k">- [ ]</span> Page wired into <span class="sb">`docs/mkdocs.wiki.yml`</span> nav (themed subgroup if needed).
|
||||
</span><span id="__span-1-257"><a id="__codelineno-1-257" name="__codelineno-1-257"></a><span class="k">- [ ]</span> <span class="sb">`index.md`</span> Documentation Structure table updated.
|
||||
</span><span id="__span-1-258"><a id="__codelineno-1-258" name="__codelineno-1-258"></a><span class="k">- [ ]</span> <span class="sb">`## Related`</span> footer present, relative links, nav order.
|
||||
</span><span id="__span-1-259"><a id="__codelineno-1-259" name="__codelineno-1-259"></a><span class="k">- [ ]</span> <span class="sb">`---`</span> separators consistent; no frontmatter; emoji headings where apt.
|
||||
</span><span id="__span-1-260"><a id="__codelineno-1-260" name="__codelineno-1-260"></a><span class="k">- [ ]</span> Build passes; collect run; hub shows <span class="sb">`/wiki/`</span> + <span class="sb">`/lib/`</span> links.
|
||||
</span><span id="__span-1-261"><a id="__codelineno-1-261" name="__codelineno-1-261"></a><span class="k">- [ ]</span> No orphaned files, no dead links.
|
||||
</span><span id="__span-1-256"><a id="__codelineno-1-256" name="__codelineno-1-256"></a><span class="gs">**Before creating a page:**</span>
|
||||
</span><span id="__span-1-257"><a id="__codelineno-1-257" name="__codelineno-1-257"></a>
|
||||
</span><span id="__span-1-258"><a id="__codelineno-1-258" name="__codelineno-1-258"></a><span class="k">- [ ]</span> Confirm it is genuinely wiki material (how-to) and not API contract.
|
||||
</span><span id="__span-1-259"><a id="__codelineno-1-259" name="__codelineno-1-259"></a><span class="k">- [ ]</span> Find the right filename (<span class="sb">`NN_snake_case.md`</span>) and directory for its theme.
|
||||
</span><span id="__span-1-260"><a id="__codelineno-1-260" name="__codelineno-1-260"></a><span class="k">- [ ]</span> Outline the sections per §4 anatomy that fits the content.
|
||||
</span><span id="__span-1-261"><a id="__codelineno-1-261" name="__codelineno-1-261"></a>
|
||||
</span><span id="__span-1-262"><a id="__codelineno-1-262" name="__codelineno-1-262"></a><span class="gs">**After creating/editing a page:**</span>
|
||||
</span><span id="__span-1-263"><a id="__codelineno-1-263" name="__codelineno-1-263"></a>
|
||||
</span><span id="__span-1-264"><a id="__codelineno-1-264" name="__codelineno-1-264"></a><span class="k">- [ ]</span> Page wired into <span class="sb">`docs/mkdocs.wiki.yml`</span> nav (themed subgroup if needed).
|
||||
</span><span id="__span-1-265"><a id="__codelineno-1-265" name="__codelineno-1-265"></a><span class="k">- [ ]</span> <span class="sb">`index.md`</span> Documentation Structure table updated.
|
||||
</span><span id="__span-1-266"><a id="__codelineno-1-266" name="__codelineno-1-266"></a><span class="k">- [ ]</span> <span class="sb">`## Related`</span> footer present, relative links, nav order.
|
||||
</span><span id="__span-1-267"><a id="__codelineno-1-267" name="__codelineno-1-267"></a><span class="k">- [ ]</span> <span class="sb">`---`</span> separators consistent; no frontmatter; emoji headings where apt.
|
||||
</span><span id="__span-1-268"><a id="__codelineno-1-268" name="__codelineno-1-268"></a><span class="k">- [ ]</span> Build passes; collect run; hub shows <span class="sb">`/wiki/`</span> + <span class="sb">`/lib/`</span> links.
|
||||
</span><span id="__span-1-269"><a id="__codelineno-1-269" name="__codelineno-1-269"></a><span class="k">- [ ]</span> No orphaned files, no dead links.
|
||||
</span></code></pre></div></td></tr></table></div></li>
|
||||
</ul>
|
||||
<hr />
|
||||
|
||||
File diff suppressed because one or more lines are too long
Binary file not shown.
Reference in New Issue
Block a user