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

fixes for compliance with existing poster wiki at mongo-ops

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-09-14 22:49:10 +05:30
parent 3448f55e18
commit 68c51d722e
1 changed files with 20 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
WIKI.md
View File

@@ -55,7 +55,10 @@ docs/wiki/
- Top-level pages use `NN_name.md` directly. High-volume sections get their own - 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"). directory, e.g. `03_use_cases/NN_name.md` (nav group "Use Cases").
- **No frontmatter.** Every file opens directly with an H1 `# Title`. - **No frontmatter.** Every file opens directly with an H1 `# Title`.
- Navigation labels are derived from the page title, not the filename. - 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 - Renumbering: prefixes order pages. When inserting a page, pick the next
number in the relevant group (subgroup numbers stay grouped). number in the relevant group (subgroup numbers stay grouped).
@@ -64,7 +67,7 @@ docs/wiki/
## 3. Navigation — `docs/mkdocs.wiki.yml` is the source of truth ## 3. Navigation — `docs/mkdocs.wiki.yml` is the source of truth
Every wiki page **must** be wired into the nav defined in Every wiki page **must** be wired into the nav defined in
`docs/wiki/../mkdocs.wiki.yml`. If a page is not in the nav, it is orphaned. `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 - The `nav:` block mirrors the directory tree; directories become nested
groups. groups.
@@ -103,16 +106,20 @@ Every wiki page **must** be wired into the nav defined in
- Opens with `# Library Overview`, one sentence about what the library does, - Opens with `# Library Overview`, one sentence about what the library does,
then a line stating the page builds the mental model. then a line stating the page builds the mental model.
- Sections: `## Architecture` (ASCII diagram + numbered layer list), - Sections: `## 🏗️ Architecture` (ASCII diagram + numbered layer list),
`## Lifecycle Rules` (table: step / call / why), `## 🔄 Lifecycle Rules` (table: step / call / why),
`## Which … Should You Use?` (decision table). `## 🧭 Which … Should You Use?` (decision table).
- Ends with `## Read Next` (cross-links to the next pages to read). - Ends with `## ➡️ Read Next` (cross-links to the next pages to read).
### 4.3 Components page (`02_*`) ### 4.3 Components page (`02_*`)
- Validated reference for the public API surface — describes what each - Validated reference for the public API surface — describes what each
component is for and how the pieces wire together. Keep it usage-level; component is for and how the pieces wire together. Keep it usage-level;
exact signatures belong in `docs/lib/`. 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) ### 4.4 Use-case page (the most common)
@@ -152,8 +159,11 @@ depth-first sections and comparison tables:
### 4.7 Error Handling (`06_*`) / Testing pages ### 4.7 Error Handling (`06_*`) / Testing pages
- Scenario-style: explain the failure modes / test approaches, a focused code - **Error Handling:** an exceptions table (`Exception | Source | Meaning / fix`),
block, `## Notes` tip list, `## Related`. 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 Common to all pages: no frontmatter, `---` between every major section, and a
`## Related` (or variant) footer as the **last** section. `## Related` (or variant) footer as the **last** section.
@@ -182,8 +192,8 @@ Examples (from mongo-ops):
Variants: Variants:
- `## Read Next` — used on the overview page (linear reading order). - `## ➡️ Read Next` — used on the overview page (linear reading order).
- `## Related Resources` — only on `index.md`, one bullet per external resource. - `## 🔗 Related Resources` — only on `index.md`, one bullet per external resource.
--- ---