diff --git a/WIKI.md b/WIKI.md new file mode 100644 index 0000000..5e2a106 --- /dev/null +++ b/WIKI.md @@ -0,0 +1,251 @@ +# AGENTS.md — Wiki Authoring Guide (Aetoskia) + +This file instructs AI agents how to create, extend, and maintain the wiki +(`docs/wiki/**`) for any Aetoskia repository. The reference implementation is +`mongo-ops` — its wiki went through several revisions to reach the structure +below and should be treated as the canonical example. + +--- + +## 1. Doc model — know the two sources of truth + +Every repo keeps two distinct kinds of documentation that must **not** bleed +into each other: + +| Kind | Source | Where | Audience | +|-------------------|-----------------------|------------------------------------------|------------------------------------| +| **Wiki** | Hand-written markdown | `docs/wiki/**` | Humans (how-to, examples, testing) | +| **API reference** | Docstrings (GSDFC) | Generated → `docs/lib/**`, `docs/mcp/**` | Consumers (exact contracts) | + +Rules: + +- The wiki is written **for humans** — how-to guides, recipes, and testing + patterns. It is never generated. +- API contracts (signatures, parameter types, exact behavior) live in the + docstrings and the machine-readable bundle under `docs/mcp/`. **Never** + duplicate full API documentation in the wiki — link to the lib site instead. +- If a page starts to drift into contract territory, cut it down to usage and + point at `docs/lib/`. +- This doc model is stated on every index page as a blockquote; keep it there: + > **Doc model:** 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 `docs/mcp/`. + +--- + +## 2. Directory layout & file naming + +``` +docs/wiki/ +├── index.md # site Home +├── 01_overview.md +├── 02_components.md +├── 03_use_cases/ # nested directory → nav group +│ ├── 01_basic_crud.md +│ ├── 02_custom_repo.md +│ └── ... +├── 04_best_practices.md +├── 06_error_handling.md +└── 07_testing_example.md +``` + +- Location: `docs/wiki/` (hand-written only). +- File names: `NN_snake_case_name.md` with a **zero-padded two-digit** numeric + prefix. e.g. `01_overview.md`, `03_use_cases/07_caching.md`. +- Top-level pages use `NN_name.md` directly. High-volume sections get their own + directory, e.g. `03_use_cases/NN_name.md` (nav group "Use Cases"). +- **No frontmatter.** Every file opens directly with an H1 `# Title`. +- Navigation labels are derived from the page title, not the filename. +- Renumbering: prefixes order pages. When inserting a page, pick the next + number in the relevant group (subgroup numbers stay grouped). + +--- + +## 3. Navigation — `docs/mkdocs.wiki.yml` is the source of truth + +Every wiki page **must** be wired into the nav defined in +`docs/wiki/../mkdocs.wiki.yml`. If a page is not in the nav, it is orphaned. + +- The `nav:` block mirrors the directory tree; directories become nested + groups. +- When a section has many pages, group them **by theme** into nested + subgroups. mongo-ops groups its use cases into: + `Getting Started`, `Data & Queries`, `Caching`, `Population`, + `Advanced Usage`. +- Keep `index.md`'s **Documentation Structure** table in sync with the nav — + it is the human-facing version of the same TOC. Every nav entry needs a row + (or nested bullet group) there. +- Nav label = human title (title case), not the filename slug. + +--- + +## 4. Page anatomy + +### 4.1 `index.md` (Home) + +``` +# 🧩 — + + +> **Doc model:** … (see §1) + +--- + +## 🚀 Key Features (bullet list, emoji per feature) +## 📦 Installation (code blocks: internal PyPI, extras, local source) +## 📁 Documentation Structure (table = TOC, mirrors nav exactly) +## 🔗 Related Resources (bullets: source repo, internal PyPI, CI) +--- +© Aetoskia Internal — `` +``` + +### 4.2 Overview page (`01_*`) + +- Opens with `# Library Overview`, one sentence about what the library does, + then a line stating the page builds the mental model. +- Sections: `## Architecture` (ASCII diagram + numbered layer list), + `## Lifecycle Rules` (table: step / call / why), + `## Which … Should You Use?` (decision table). +- Ends with `## Read Next` (cross-links to the next pages to read). + +### 4.3 Components page (`02_*`) + +- Validated reference for the public API surface — describes what each + component is for and how the pieces wire together. Keep it usage-level; + exact signatures belong in `docs/lib/`. + +### 4.4 Use-case page (the most common) + +Standard anatomy, in this order: + +``` +# Use Case N: + +**Scenario:** + +--- + +## 📦 What's New? (table: Component | Description — new API used here) +## 🚀 Example (languaged code block, complete runnable-looking snippet) +## 💡 Tips (bullets: gotchas, ordering, common mistakes) +## Related (§5) +``` + +### 4.5 Deep-dive / worked-example page + +For intricate flows (population shapes, cache round-trips), use numbered +depth-first sections and comparison tables: + +``` +## 1. (### 1a., ### 1b., … per sub-case) +## 2. +## 3. +## 4. When to use which (comparison table) +## Related +``` + +### 4.6 Best Practices page (`04_*`) + +- Flat themed `##` sections (e.g. Layering, Lifecycle, Data & Performance, + Transactions & Errors, Testing), each a short list of numbered conventions. +- Pure prose — no large code blocks. + +### 4.7 Error Handling (`06_*`) / Testing pages + +- Scenario-style: explain the failure modes / test approaches, a focused code + block, `## Notes` tip list, `## Related`. + +Common to all pages: no frontmatter, `---` between every major section, and a +`## Related` (or variant) footer as the **last** section. + +--- + +## 5. The `## Related` footer + +Every page ends with a cross-link footer. Rules: + +- Always the **last** section, always preceded by a `---`. +- Standard heading: `## Related` (no emoji). +- One bullet line; links separated by ` · ` (middle dot plus spaces). +- Link label format: `[NN – Title](relative_path)` — en-dash, page number, title. +- Paths are **relative**: same directory → `02_custom_repo.md`; parent → + `../01_overview.md`; child → `03_use_cases/01_basic_crud.md`. +- Link order follows nav order (each `Related` points to related next/sibling + pages, plus the overview/components anchor). + +Examples (from mongo-ops): + +``` +## Related +- [02 – Custom repository](02_custom_repo.md) · [04 – Pagination](04_pagination.md) · [Overview](../01_overview.md) +``` + +Variants: + +- `## Read Next` — used on the overview page (linear reading order). +- `## Related Resources` — only on `index.md`, one bullet per external resource. + +--- + +## 6. Tone & formatting rules + +- **Written for humans**: short sentences, concrete examples, plain words. +- Emoji-prefixed H2 headings for recognizable section types + (`📦 What's New?`, `🚀 Example`, `💡 Tips`, `🚀 Key Features`). +- `---` horizontal rule between every major section. +- Code blocks always declare a language (```python, ```bash, etc.). +- Use tables for comparisons and structured decisions; bullets for lists; + ASCII diagrams for architecture. +- Bold key terms inline. Use `inline code` for symbols/APIs. +- Keep pages focused: one recipe/purpose per page. If a page balloons past + ~10 KB, split it (add a numbered deep-dive page instead). +- Match tone of existing pages in the repo before writing new ones. + +--- + +## 7. Build & verify workflow + +After creating or editing wiki pages: + +```bash +# 1. Build the wiki (from the repo root) +doc-forge build --wiki # wiki only +doc-forge build --wiki --mkdocs --module # wiki + lib together + +# 2. Preview locally +doc-forge serve --wiki + +# 3. Collect into the hub (run from the docs/ service repo) +python collect.py # copies site, regenerates index + nginx.conf +python collect.py --dry-run # preview without writing +``` + +Verification checklist: + +- `doc-forge build --wiki` completes with no warnings about missing files. +- Every new page is present in `docs/mkdocs.wiki.yml` **and** in the index + Documentation Structure table. +- Every page ends with a `## Related` block and no dead links (paths resolve). +- After `collect.py`: the hub card links to both `/wiki/` and `/lib/` and the + pages render (spot-check with the served site). +- If code/docstrings changed (no change when wiki-only), run the repo gates: + `black`, `ruff`, `mypy`, `pytest`. + +--- + +## 8. Before/after checklist + +**Before creating a page:** + +- [ ] Confirm it is genuinely wiki material (how-to) and not API contract. +- [ ] Find the right filename (`NN_snake_case.md`) and directory for its theme. +- [ ] Outline the sections per §4 anatomy that fits the content. + +**After creating/editing a page:** + +- [ ] Page wired into `docs/mkdocs.wiki.yml` nav (themed subgroup if needed). +- [ ] `index.md` Documentation Structure table updated. +- [ ] `## Related` footer present, relative links, nav order. +- [ ] `---` separators consistent; no frontmatter; emoji headings where apt. +- [ ] Build passes; collect run; hub shows `/wiki/` + `/lib/` links. +- [ ] No orphaned files, no dead links. \ No newline at end of file