(refactor): moved WIKI.md to wiki for doc-forge
This commit is contained in:
261
WIKI.md
261
WIKI.md
@@ -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)
|
|
||||||
|
|
||||||
```
|
|
||||||
# 🧩 <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.
|
|
||||||
@@ -34,9 +34,272 @@ OpenAPI-based API docs.
|
|||||||
## 🔗 Related Resources
|
## 🔗 Related Resources
|
||||||
|
|
||||||
- **Source Code:** the `doc-forge` repository
|
- **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/`
|
- **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)
|
||||||
|
|
||||||
|
```
|
||||||
|
# 🧩 <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.
|
||||||
|
````
|
||||||
|
---
|
||||||
|
|
||||||
© Aetoskia Internal
|
© Aetoskia Internal
|
||||||
Reference in New Issue
Block a user