261 lines
10 KiB
Markdown
261 lines
10 KiB
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)
|
||
|
||
```
|
||
# 🧩 <package> — <slogan>
|
||
<one-paragraph pitch>
|
||
|
||
> **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 — `<package>` <version>
|
||
```
|
||
|
||
### 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: <Human Title>
|
||
|
||
**Scenario:** <one sentence: the problem this recipe solves>
|
||
|
||
---
|
||
|
||
## 📦 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. <Write path> (### 1a., ### 1b., … per sub-case)
|
||
## 2. <Read path>
|
||
## 3. <Round trip / tricky bit>
|
||
## 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 <pkg> # 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. |