aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
68c51d722e67f6725ca3e0677599349d1ea07923
doc-forge/WIKI.md

10 KiB
Raw Blame History

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:

# 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.