aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

(refactor): moved WIKI.md to wiki for doc-forge

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-09-14 22:57:52 +05:30
parent 68c51d722e
commit 358510ebf0
2 changed files with 264 additions and 262 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
docs/wiki/index.md
View File

@@ -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)
```
# 🧩 <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