1399 lines
78 KiB
HTML
1399 lines
78 KiB
HTML
|
||
<!doctype html>
|
||
<html lang="en" class="no-js">
|
||
<head>
|
||
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
|
||
|
||
|
||
|
||
|
||
<link rel="next" href="01_overview/">
|
||
|
||
|
||
<link rel="icon" href="assets/images/favicon.png">
|
||
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.6.23">
|
||
|
||
|
||
|
||
<title>doc-forge</title>
|
||
|
||
|
||
|
||
<link rel="stylesheet" href="assets/stylesheets/main.84d31ad4.min.css">
|
||
|
||
|
||
<link rel="stylesheet" href="assets/stylesheets/palette.06af60db.min.css">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CJetBrains+Mono:400,400i,700,700i&display=fallback">
|
||
<style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style>
|
||
|
||
|
||
|
||
<link rel="stylesheet" href="https://unpkg.com/dracula-prism/dist/css/dracula-prism.css">
|
||
|
||
<script>__md_scope=new URL(".",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</head>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<body dir="ltr" data-md-color-scheme="slate" data-md-color-primary="blue-grey" data-md-color-accent="teal">
|
||
|
||
|
||
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
|
||
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
|
||
<label class="md-overlay" for="__drawer"></label>
|
||
<div data-md-component="skip">
|
||
|
||
|
||
<a href="#docforge-docstring-driven-documentation-forge" class="md-skip">
|
||
Skip to content
|
||
</a>
|
||
|
||
</div>
|
||
<div data-md-component="announce">
|
||
|
||
</div>
|
||
|
||
|
||
|
||
|
||
<header class="md-header" data-md-component="header">
|
||
<nav class="md-header__inner md-grid" aria-label="Header">
|
||
<a href="." title="doc-forge" class="md-header__button md-logo" aria-label="doc-forge" data-md-component="logo">
|
||
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 4v18h16v2H4c-1.1 0-2-.9-2-2V4zm11 3h5.5L15 1.5zM8 0h8l6 6v12c0 1.11-.89 2-2 2H8a2 2 0 0 1-2-2V2c0-1.11.89-2 2-2m9 16v-2H8v2zm3-4v-2H8v2z"/></svg>
|
||
|
||
</a>
|
||
<label class="md-header__button md-icon" for="__drawer">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
|
||
</label>
|
||
<div class="md-header__title" data-md-component="header-title">
|
||
<div class="md-header__ellipsis">
|
||
<div class="md-header__topic">
|
||
<span class="md-ellipsis">
|
||
doc-forge
|
||
</span>
|
||
</div>
|
||
<div class="md-header__topic" data-md-component="header-topic">
|
||
<span class="md-ellipsis">
|
||
|
||
Home
|
||
|
||
</span>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<label class="md-header__button md-icon" for="__search">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
|
||
</label>
|
||
<div class="md-search" data-md-component="search" role="dialog">
|
||
<label class="md-search__overlay" for="__search"></label>
|
||
<div class="md-search__inner" role="search">
|
||
<form class="md-search__form" name="search">
|
||
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
|
||
<label class="md-search__icon md-icon" for="__search">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
|
||
</label>
|
||
<nav class="md-search__options" aria-label="Search">
|
||
|
||
<a href="javascript:void(0)" class="md-search__icon md-icon" title="Share" aria-label="Share" data-clipboard data-clipboard-text="" data-md-component="search-share" tabindex="-1">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11c.54.5 1.25.81 2.04.81a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3c0 .24.04.47.09.7L8.04 9.81C7.5 9.31 6.79 9 6 9a3 3 0 0 0-3 3 3 3 0 0 0 3 3c.79 0 1.5-.31 2.04-.81l7.12 4.15c-.05.21-.08.43-.08.66 0 1.61 1.31 2.91 2.92 2.91s2.92-1.3 2.92-2.91A2.92 2.92 0 0 0 18 16.08"/></svg>
|
||
</a>
|
||
|
||
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
|
||
</button>
|
||
</nav>
|
||
|
||
<div class="md-search__suggest" data-md-component="search-suggest"></div>
|
||
|
||
</form>
|
||
<div class="md-search__output">
|
||
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
|
||
<div class="md-search-result" data-md-component="search-result">
|
||
<div class="md-search-result__meta">
|
||
Initializing search
|
||
</div>
|
||
<ol class="md-search-result__list" role="presentation"></ol>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
</nav>
|
||
|
||
</header>
|
||
|
||
<div class="md-container" data-md-component="container">
|
||
|
||
|
||
|
||
|
||
|
||
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
|
||
<div class="md-grid">
|
||
<ul class="md-tabs__list">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item md-tabs__item--active">
|
||
<a href="." class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
|
||
Home
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="01_overview/" class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
|
||
Overview
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="02_components/" class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
|
||
Components
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="03_conventions/" class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
|
||
Conventions
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="04_iterative_workflow/" class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
|
||
Iterative Workflow
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="05_development/01_environment/" class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
|
||
Development
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
|
||
|
||
|
||
<main class="md-main" data-md-component="main">
|
||
<div class="md-main__inner md-grid">
|
||
|
||
|
||
|
||
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
|
||
<div class="md-sidebar__scrollwrap">
|
||
<div class="md-sidebar__inner">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<nav class="md-nav md-nav--primary md-nav--lifted md-nav--integrated" aria-label="Navigation" data-md-level="0">
|
||
<label class="md-nav__title" for="__drawer">
|
||
<a href="." title="doc-forge" class="md-nav__button md-logo" aria-label="doc-forge" data-md-component="logo">
|
||
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 4v18h16v2H4c-1.1 0-2-.9-2-2V4zm11 3h5.5L15 1.5zM8 0h8l6 6v12c0 1.11-.89 2-2 2H8a2 2 0 0 1-2-2V2c0-1.11.89-2 2-2m9 16v-2H8v2zm3-4v-2H8v2z"/></svg>
|
||
|
||
</a>
|
||
doc-forge
|
||
</label>
|
||
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--active">
|
||
|
||
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
|
||
|
||
|
||
|
||
|
||
|
||
<label class="md-nav__link md-nav__link--active" for="__toc">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Home
|
||
|
||
</span>
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
<a href="." class="md-nav__link md-nav__link--active">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Home
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
|
||
|
||
|
||
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<label class="md-nav__title" for="__toc">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Table of contents
|
||
</label>
|
||
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#key-features" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
🚀 Key Features
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#installation" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
📦 Installation
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#documentation-structure" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
📁 Documentation Structure
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#related-resources" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
🔗 Related Resources
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="01_overview/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Overview
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="02_components/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Components
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="03_conventions/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Conventions
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="04_iterative_workflow/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Iterative Workflow
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_6" >
|
||
|
||
|
||
<label class="md-nav__link" for="__nav_6" id="__nav_6_label" tabindex="0">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Development
|
||
|
||
</span>
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false">
|
||
<label class="md-nav__title" for="__nav_6">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Development
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="05_development/01_environment/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Environment
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="05_development/02_quality_gates/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Quality Gates
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="05_development/03_gsdfc_guide/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
GSDFC Guide
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="05_development/04_mcp_guide/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
MCP Guide
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="05_development/05_mkdocs_configs/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
MkDocs Configs
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
|
||
<div class="md-content" data-md-component="content">
|
||
<article class="md-content__inner md-typeset">
|
||
|
||
|
||
|
||
|
||
|
||
<h1 id="docforge-docstring-driven-documentation-forge">🧩 docforge — Docstring-Driven Documentation Forge</h1>
|
||
<p><code>docforge</code> is an internal documentation tool that generates reference documentation from Google-Styled Doc-Forge Convention (GSDFC) docstrings and assembles it into per-kind MkDocs sites, alongside hand-written wiki pages and OpenAPI-based API docs.</p>
|
||
<blockquote>
|
||
<p><strong>Doc model:</strong> this wiki is written for humans — how‑to guides, examples,
|
||
and testing recipes. The authoritative API contracts live in the code
|
||
(docstrings) and the machine‑readable bundle under <code>docs/mcp/</code>.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<h2 id="key-features">🚀 Key Features</h2>
|
||
<ul>
|
||
<li>🧪 GSDFC docstring extraction via Griffe</li>
|
||
<li>🧭 Auto-derived navigation for hand-written wiki pages</li>
|
||
<li>🗂 Independent MkDocs builds per kind (lib, api, wiki) into <code>site/{kind}</code></li>
|
||
<li>🔌 Material MkDocs theming out of the box</li>
|
||
<li>📦 MCP structured documentation resources</li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="installation">📦 Installation</h2>
|
||
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-2">2</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="c1"># Internal PyPI (TBD)</span>
|
||
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2"></a>pip<span class="w"> </span>install<span class="w"> </span>docforge
|
||
</span></code></pre></div></td></tr></table></div>
|
||
<hr />
|
||
<h2 id="documentation-structure">📁 Documentation Structure</h2>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Section</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><a href="01_overview/">Overview</a></td>
|
||
<td>What docforge is and how it fits the pipeline</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="02_components/">Components</a></td>
|
||
<td>Loaders, models, nav, renderers, CLI, servers</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="03_conventions/">Conventions</a></td>
|
||
<td>GSDFC, <code>.pyi</code> stubs, and template conventions</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="04_iterative_workflow/">Iterative Workflow</a></td>
|
||
<td>How a docs build runs end to end</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="05_development/01_environment/">Environment</a></td>
|
||
<td>Environment setup</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="05_development/02_quality_gates/">Quality Gates</a></td>
|
||
<td>Test layout and quality checks</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="05_development/03_gsdfc_guide/">GSDFC Guide</a></td>
|
||
<td>How to write GSDFC-conformant docstrings</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="05_development/04_mcp_guide/">MCP Guide</a></td>
|
||
<td>Building, serving, and consuming the MCP bundle</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="05_development/05_mkdocs_configs/">MkDocs Configs</a></td>
|
||
<td>MkDocs config generation and templates</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<hr />
|
||
<h2 id="related-resources">🔗 Related Resources</h2>
|
||
<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>; 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>
|
||
<span class="normal"><a href="#__codelineno-1-4"> 4</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-5"> 5</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-6"> 6</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-7"> 7</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-8"> 8</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-9"> 9</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-10"> 10</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-11"> 11</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-12"> 12</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-13"> 13</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-14"> 14</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-15"> 15</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-16"> 16</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-17"> 17</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-18"> 18</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-19"> 19</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-20"> 20</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-21"> 21</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-22"> 22</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-23"> 23</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-24"> 24</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-25"> 25</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-26"> 26</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-27"> 27</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-28"> 28</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-29"> 29</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-30"> 30</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-31"> 31</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-32"> 32</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-33"> 33</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-34"> 34</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-35"> 35</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-36"> 36</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-37"> 37</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-38"> 38</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-39"> 39</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-40"> 40</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-41"> 41</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-42"> 42</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-43"> 43</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-44"> 44</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-45"> 45</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-46"> 46</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-47"> 47</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-48"> 48</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-49"> 49</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-50"> 50</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-51"> 51</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-52"> 52</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-53"> 53</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-54"> 54</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-55"> 55</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-56"> 56</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-57"> 57</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-58"> 58</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-59"> 59</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-60"> 60</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-61"> 61</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-62"> 62</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-63"> 63</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-64"> 64</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-65"> 65</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-66"> 66</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-67"> 67</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-68"> 68</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-69"> 69</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-70"> 70</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-71"> 71</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-72"> 72</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-73"> 73</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-74"> 74</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-75"> 75</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-76"> 76</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-77"> 77</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-78"> 78</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-79"> 79</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-80"> 80</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-81"> 81</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-82"> 82</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-83"> 83</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-84"> 84</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-85"> 85</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-86"> 86</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-87"> 87</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-88"> 88</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-89"> 89</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-90"> 90</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-91"> 91</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-92"> 92</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-93"> 93</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-94"> 94</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-95"> 95</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-96"> 96</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-97"> 97</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-98"> 98</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-99"> 99</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-100">100</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-101">101</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-102">102</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-103">103</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-104">104</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-105">105</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-106">106</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-107">107</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-108">108</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-109">109</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-110">110</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-111">111</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-112">112</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-113">113</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-114">114</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-115">115</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-116">116</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-117">117</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-118">118</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-119">119</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-120">120</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-121">121</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-122">122</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-123">123</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-124">124</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-125">125</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-126">126</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-127">127</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-128">128</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-129">129</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-130">130</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-131">131</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-132">132</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-133">133</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-134">134</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-135">135</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-136">136</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-137">137</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-138">138</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-139">139</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-140">140</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-141">141</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-142">142</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-143">143</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-144">144</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-145">145</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-146">146</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-147">147</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-148">148</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-149">149</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-150">150</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-151">151</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-152">152</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-153">153</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-154">154</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-155">155</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-156">156</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-157">157</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-158">158</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-159">159</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-160">160</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-161">161</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-162">162</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-163">163</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-164">164</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-165">165</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-166">166</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-167">167</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-168">168</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-169">169</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-170">170</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-171">171</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-172">172</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-173">173</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-174">174</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-175">175</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-176">176</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-177">177</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-178">178</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-179">179</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-180">180</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-181">181</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-182">182</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-183">183</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-184">184</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-185">185</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-186">186</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-187">187</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-188">188</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-189">189</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-190">190</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-191">191</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-192">192</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-193">193</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-194">194</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-195">195</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-196">196</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-197">197</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-198">198</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-199">199</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-200">200</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-201">201</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-202">202</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-203">203</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-204">204</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-205">205</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-206">206</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-207">207</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-208">208</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-209">209</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-210">210</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-211">211</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-212">212</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-213">213</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-214">214</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-215">215</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-216">216</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-217">217</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-218">218</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-219">219</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-220">220</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-221">221</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-222">222</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-223">223</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-224">224</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-225">225</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-226">226</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-227">227</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-228">228</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-229">229</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-230">230</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-231">231</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-232">232</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-233">233</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-234">234</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-235">235</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-236">236</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-237">237</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-238">238</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-239">239</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-240">240</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-241">241</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-242">242</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-243">243</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-244">244</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-245">245</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-246">246</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-247">247</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-248">248</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-249">249</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-250">250</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-251">251</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-252">252</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-253">253</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-254">254</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-255">255</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-256">256</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-257">257</a></span>
|
||
<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>
|
||
<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.
|
||
</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>---
|
||
</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><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>---
|
||
</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><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="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">```</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">> **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="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">**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="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>---
|
||
</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="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><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="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><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="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="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 />
|
||
<p>© Aetoskia Internal — <code>docforge</code> 1.0</p>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</article>
|
||
</div>
|
||
|
||
|
||
<script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script>
|
||
|
||
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
|
||
</div>
|
||
|
||
<button type="button" class="md-top md-icon" data-md-component="top" hidden>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
|
||
Back to top
|
||
</button>
|
||
|
||
</main>
|
||
|
||
<footer class="md-footer">
|
||
|
||
<div class="md-footer-meta md-typeset">
|
||
<div class="md-footer-meta__inner md-grid">
|
||
<div class="md-copyright">
|
||
|
||
|
||
Made with
|
||
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
|
||
Material for MkDocs
|
||
</a>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
</footer>
|
||
|
||
</div>
|
||
<div class="md-dialog" data-md-component="dialog">
|
||
<div class="md-dialog__inner md-typeset"></div>
|
||
</div>
|
||
|
||
|
||
|
||
|
||
<script id="__config" type="application/json">{"base": ".", "features": ["navigation.sections", "navigation.expand", "navigation.top", "navigation.instant", "navigation.tracking", "navigation.indexes", "content.code.copy", "content.code.annotate", "content.tabs.link", "content.action.edit", "search.highlight", "search.share", "search.suggest", "navigation.tabs", "toc.integrate", "header.autohide", "announce.dismiss", "footer.social", "content.code.select", "content.code.line_numbers", "content.tooltips"], "search": "assets/javascripts/workers/search.973d3a69.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
|
||
|
||
|
||
<script src="assets/javascripts/bundle.f55a23d4.min.js"></script>
|
||
|
||
|
||
</body>
|
||
</html> |