diff --git a/WIKI.md b/WIKI.md deleted file mode 100644 index 563a730..0000000 --- a/WIKI.md +++ /dev/null @@ -1,261 +0,0 @@ -# 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 short human titles set explicitly in - `docs/mkdocs.wiki.yml` (title case) — often **shorter** than the page H1. - Example: nav label `Basic CRUD` vs page H1 `Use Case 1: Basic FastAPI CRUD API`. - Never use the raw filename slug as the label. -- 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/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/`. -- Anatomy: numbered sections, one per component (`## 1. MongoConnectionManager`, - `## 2. BaseDocument`, …), with `### 8.1`-style sub-numbering for related - types under a component (e.g. the cache layer's backend / stats / config / - in-memory / redis implementations). Ends with `## Related`. - -### 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 - -- **Error Handling:** an exceptions table (`Exception | Source | Meaning / fix`), - a `> ` note on which failures are by design, a `## 🚀 FastAPI Mapping Example` - code block, then `## 💡 Tips` bullets, then `## Related`. -- **Testing example (`07_*`):** `## 🚀 Mock-Based Quickstart` (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 diff --git a/docs/wiki/index.md b/docs/wiki/index.md index d66e3eb..7d1c00a 100644 --- a/docs/wiki/index.md +++ b/docs/wiki/index.md @@ -34,9 +34,272 @@ OpenAPI-based API docs. ## 🔗 Related Resources - **Source Code:** the `doc-forge` repository -- **Wiki Kind:** hand-written content lives in `docs/wiki/` - **MCP Bundle:** generated by `doc-forge build --mcp --module docforge` into `docs/mcp/` +- **Wiki Kind:** hand-written content lives in `docs/wiki/` or use the prompt mentioned below + +````markdown +# 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 short human titles set explicitly in + `docs/mkdocs.wiki.yml` (title case) — often **shorter** than the page H1. + Example: nav label `Basic CRUD` vs page H1 `Use Case 1: Basic FastAPI CRUD API`. + Never use the raw filename slug as the label. +- 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/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/`. +- Anatomy: numbered sections, one per component (`## 1. MongoConnectionManager`, + `## 2. BaseDocument`, …), with `### 8.1`-style sub-numbering for related + types under a component (e.g. the cache layer's backend / stats / config / + in-memory / redis implementations). Ends with `## Related`. + +### 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 + +- **Error Handling:** an exceptions table (`Exception | Source | Meaning / fix`), + a `> ` note on which failures are by design, a `## 🚀 FastAPI Mapping Example` + code block, then `## 💡 Tips` bullets, then `## Related`. +- **Testing example (`07_*`):** `## 🚀 Mock-Based Quickstart` (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. +```` +--- + © Aetoskia Internal \ No newline at end of file