# 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.
+ | # 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 β docforge 1.0
diff --git a/doc-forge/wiki/search/search_index.json b/doc-forge/wiki/search/search_index.json
index eb45cf6..88b0ca9 100644
--- a/doc-forge/wiki/search/search_index.json
+++ b/doc-forge/wiki/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83d\udd28 docforge \u2014 Docstring-Driven Documentation Forge","text":"docforge is an internal documentation tool that generates reference documentation from Google-Styled Doc-Forge Convention (GSDFC) docstrings and assembles it into per-kind MkDocs sites, alongside hand-written wiki pages and OpenAPI-based API docs.
"},{"location":"#key-features","title":"\ud83d\ude80 Key Features","text":" - \ud83e\uddea GSDFC docstring extraction via Griffe
- \ud83e\udded Auto-derived navigation for hand-written wiki pages
- \ud83d\uddc2 Independent MkDocs builds per kind (lib, api, wiki) into
site/{kind} - \ud83d\udd0c Material MkDocs theming out of the box
- \ud83d\udce6 MCP structured documentation resources
"},{"location":"#documentation-structure","title":"\ud83d\udcc1 Documentation Structure","text":"Section Description Overview What docforge is and how it fits the pipeline Architecture Loaders, models, nav, renderers, CLI, servers Conventions GSDFC, .pyi stubs, and template conventions Iterative Workflow How a docs build runs end to end Development Environment setup and quality gates Docstring Guide How to write GSDFC-conformant docstrings MCP Guide Building, serving, and consuming the MCP bundle"},{"location":"#related-resources","title":"\ud83d\udd17 Related Resources","text":" - Source Code: the
doc-forge repository - 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 # AGENTS.md \u2014 Wiki Authoring Guide (Aetoskia)\n\nThis file instructs AI agents how to create, extend, and maintain the wiki\n(`docs/wiki/**`) for any Aetoskia repository. The reference implementation is\n`mongo-ops` \u2014 its wiki went through several revisions to reach the structure\nbelow and should be treated as the canonical example.\n\n---\n\n## 1. Doc model \u2014 know the two sources of truth\n\nEvery repo keeps two distinct kinds of documentation that must **not** bleed\ninto each other:\n\n| Kind | Source | Where | Audience |\n|-------------------|-----------------------|------------------------------------------|------------------------------------|\n| **Wiki** | Hand-written markdown | `docs/wiki/**` | Humans (how-to, examples, testing) |\n| **API reference** | Docstrings (GSDFC) | Generated \u2192 `docs/lib/**`, `docs/mcp/**` | Consumers (exact contracts) |\n\nRules:\n\n- The wiki is written **for humans** \u2014 how-to guides, recipes, and testing\n patterns. It is never generated.\n- API contracts (signatures, parameter types, exact behavior) live in the\n docstrings and the machine-readable bundle under `docs/mcp/`. **Never**\n duplicate full API documentation in the wiki \u2014 link to the lib site instead.\n- If a page starts to drift into contract territory, cut it down to usage and\n point at `docs/lib/`.\n- This doc model is stated on every index page as a blockquote; keep it there:\n > **Doc model:** this wiki is written for humans \u2014 how\u2011to guides, examples,\n > and testing recipes. The authoritative API contracts live in the code\n > (docstrings) and the machine\u2011readable bundle under `docs/mcp/`.\n\n---\n\n## 2. Directory layout & file naming\n\n```\ndocs/wiki/\n\u251c\u2500\u2500 index.md # site Home\n\u251c\u2500\u2500 01_overview.md\n\u251c\u2500\u2500 02_components.md\n\u251c\u2500\u2500 03_use_cases/ # nested directory \u2192 nav group\n\u2502 \u251c\u2500\u2500 01_basic_crud.md\n\u2502 \u251c\u2500\u2500 02_custom_repo.md\n\u2502 \u2514\u2500\u2500 ...\n\u251c\u2500\u2500 04_best_practices.md\n\u251c\u2500\u2500 06_error_handling.md\n\u2514\u2500\u2500 07_testing_example.md\n```\n\n- Location: `docs/wiki/` (hand-written only).\n- File names: `NN_snake_case_name.md` with a **zero-padded two-digit** numeric\n prefix. e.g. `01_overview.md`, `03_use_cases/07_caching.md`.\n- Top-level pages use `NN_name.md` directly. High-volume sections get their own\n directory, e.g. `03_use_cases/NN_name.md` (nav group \"Use Cases\").\n- **No frontmatter.** Every file opens directly with an H1 `# Title`.\n- Navigation labels are short human titles set explicitly in\n `docs/mkdocs.wiki.yml` (title case) \u2014 often **shorter** than the page H1.\n Example: nav label `Basic CRUD` vs page H1 `Use Case 1: Basic FastAPI CRUD API`.\n Never use the raw filename slug as the label.\n- Renumbering: prefixes order pages. When inserting a page, pick the next\n number in the relevant group (subgroup numbers stay grouped).\n\n---\n\n## 3. Navigation \u2014 `docs/mkdocs.wiki.yml` is the source of truth\n\nEvery wiki page **must** be wired into the nav defined in\n`docs/mkdocs.wiki.yml`. If a page is not in the nav, it is orphaned.\n\n- The `nav:` block mirrors the directory tree; directories become nested\n groups.\n- When a section has many pages, group them **by theme** into nested\n subgroups. mongo-ops groups its use cases into:\n `Getting Started`, `Data & Queries`, `Caching`, `Population`,\n `Advanced Usage`.\n- Keep `index.md`'s **Documentation Structure** table in sync with the nav \u2014\n it is the human-facing version of the same TOC. Every nav entry needs a row\n (or nested bullet group) there.\n- Nav label = human title (title case), not the filename slug.\n\n---\n\n## 4. Page anatomy\n\n### 4.1 `index.md` (Home)\n\n```\n# \ud83e\udde9 <package> \u2014 <slogan>\n<one-paragraph pitch>\n\n> **Doc model:** \u2026 (see \u00a71)\n\n---\n\n## \ud83d\ude80 Key Features (bullet list, emoji per feature)\n## \ud83d\udce6 Installation (code blocks: internal PyPI, extras, local source)\n## \ud83d\udcc1 Documentation Structure (table = TOC, mirrors nav exactly)\n## \ud83d\udd17 Related Resources (bullets: source repo, internal PyPI, CI)\n---\n\u00a9 Aetoskia Internal \u2014 `<package>` <version>\n```\n\n### 4.2 Overview page (`01_*`)\n\n- Opens with `# Library Overview`, one sentence about what the library does,\n then a line stating the page builds the mental model.\n- Sections: `## \ud83c\udfd7\ufe0f Architecture` (ASCII diagram + numbered layer list),\n `## \ud83d\udd04 Lifecycle Rules` (table: step / call / why),\n `## \ud83e\udded Which \u2026 Should You Use?` (decision table).\n- Ends with `## \u27a1\ufe0f Read Next` (cross-links to the next pages to read).\n\n### 4.3 Components page (`02_*`)\n\n- Validated reference for the public API surface \u2014 describes what each\n component is for and how the pieces wire together. Keep it usage-level;\n exact signatures belong in `docs/lib/`.\n- Anatomy: numbered sections, one per component (`## 1. MongoConnectionManager`,\n `## 2. BaseDocument`, \u2026), with `### 8.1`-style sub-numbering for related\n types under a component (e.g. the cache layer's backend / stats / config /\n in-memory / redis implementations). Ends with `## Related`.\n\n### 4.4 Use-case page (the most common)\n\nStandard anatomy, in this order:\n\n```\n# Use Case N: <Human Title>\n\n**Scenario:** <one sentence: the problem this recipe solves>\n\n---\n\n## \ud83d\udce6 What's New? (table: Component | Description \u2014 new API used here)\n## \ud83d\ude80 Example (languaged code block, complete runnable-looking snippet)\n## \ud83d\udca1 Tips (bullets: gotchas, ordering, common mistakes)\n## Related (\u00a75)\n```\n\n### 4.5 Deep-dive / worked-example page\n\nFor intricate flows (population shapes, cache round-trips), use numbered\ndepth-first sections and comparison tables:\n\n```\n## 1. <Write path> (### 1a., ### 1b., \u2026 per sub-case)\n## 2. <Read path>\n## 3. <Round trip / tricky bit>\n## 4. When to use which (comparison table)\n## Related\n```\n\n### 4.6 Best Practices page (`04_*`)\n\n- Flat themed `##` sections (e.g. Layering, Lifecycle, Data & Performance,\n Transactions & Errors, Testing), each a short list of numbered conventions.\n- Pure prose \u2014 no large code blocks.\n\n### 4.7 Error Handling (`06_*`) / Testing pages\n\n- **Error Handling:** an exceptions table (`Exception | Source | Meaning / fix`),\n a `> ` note on which failures are by design, a `## \ud83d\ude80 FastAPI Mapping Example`\n code block, then `## \ud83d\udca1 Tips` bullets, then `## Related`.\n- **Testing example (`07_*`):** `## \ud83d\ude80 Mock-Based Quickstart` (focused code\n block), `## \ud83d\udca1 Notes` tip list, `## Related`.\n\nCommon to all pages: no frontmatter, `---` between every major section, and a\n`## Related` (or variant) footer as the **last** section.\n\n---\n\n## 5. The `## Related` footer\n\nEvery page ends with a cross-link footer. Rules:\n\n- Always the **last** section, always preceded by a `---`.\n- Standard heading: `## Related` (no emoji).\n- One bullet line; links separated by ` \u00b7 ` (middle dot plus spaces).\n- Link label format: `[NN \u2013 Title](relative_path)` \u2014 en-dash, page number, title.\n- Paths are **relative**: same directory \u2192 `02_custom_repo.md`; parent \u2192\n `../01_overview.md`; child \u2192 `03_use_cases/01_basic_crud.md`.\n- Link order follows nav order (each `Related` points to related next/sibling\n pages, plus the overview/components anchor).\n\nExamples (from mongo-ops):\n\n```\n## Related\n- [02 \u2013 Custom repository](02_custom_repo.md) \u00b7 [04 \u2013 Pagination](04_pagination.md) \u00b7 [Overview](../01_overview.md)\n```\n\nVariants:\n\n- `## \u27a1\ufe0f Read Next` \u2014 used on the overview page (linear reading order).\n- `## \ud83d\udd17 Related Resources` \u2014 only on `index.md`, one bullet per external resource.\n\n---\n\n## 6. Tone & formatting rules\n\n- **Written for humans**: short sentences, concrete examples, plain words.\n- Emoji-prefixed H2 headings for recognizable section types\n (`\ud83d\udce6 What's New?`, `\ud83d\ude80 Example`, `\ud83d\udca1 Tips`, `\ud83d\ude80 Key Features`).\n- `---` horizontal rule between every major section.\n- Code blocks always declare a language (```python, ```bash, etc.).\n- Use tables for comparisons and structured decisions; bullets for lists;\n ASCII diagrams for architecture.\n- Bold key terms inline. Use `inline code` for symbols/APIs.\n- Keep pages focused: one recipe/purpose per page. If a page balloons past\n ~10 KB, split it (add a numbered deep-dive page instead).\n- Match tone of existing pages in the repo before writing new ones.\n\n---\n\n## 7. Build & verify workflow\n\nAfter creating or editing wiki pages:\n\n```bash\n# 1. Build the wiki (from the repo root)\ndoc-forge build --wiki # wiki only\ndoc-forge build --wiki --mkdocs --module <pkg> # wiki + lib together\n\n# 2. Preview locally\ndoc-forge serve --wiki\n\n# 3. Collect into the hub (run from the docs/ service repo)\npython collect.py # copies site, regenerates index + nginx.conf\npython collect.py --dry-run # preview without writing\n```\n\nVerification checklist:\n\n- `doc-forge build --wiki` completes with no warnings about missing files.\n- Every new page is present in `docs/mkdocs.wiki.yml` **and** in the index\n Documentation Structure table.\n- Every page ends with a `## Related` block and no dead links (paths resolve).\n- After `collect.py`: the hub card links to both `/wiki/` and `/lib/` and the\n pages render (spot-check with the served site).\n- If code/docstrings changed (no change when wiki-only), run the repo gates:\n `black`, `ruff`, `mypy`, `pytest`.\n\n---\n\n## 8. Before/after checklist\n\n**Before creating a page:**\n\n- [ ] Confirm it is genuinely wiki material (how-to) and not API contract.\n- [ ] Find the right filename (`NN_snake_case.md`) and directory for its theme.\n- [ ] Outline the sections per \u00a74 anatomy that fits the content.\n\n**After creating/editing a page:**\n\n- [ ] Page wired into `docs/mkdocs.wiki.yml` nav (themed subgroup if needed).\n- [ ] `index.md` Documentation Structure table updated.\n- [ ] `## Related` footer present, relative links, nav order.\n- [ ] `---` separators consistent; no frontmatter; emoji headings where apt.\n- [ ] Build passes; collect run; hub shows `/wiki/` + `/lib/` links.\n- [ ] No orphaned files, no dead links.\n
\u00a9 Aetoskia Internal
"},{"location":"01_overview/","title":"Overview","text":"docforge turns GSDFC-compliant Python docstrings into maintainable reference documentation. It never edits source docstrings; it reads them, renders them, and assembles documentation sites from all available material.
"},{"location":"01_overview/#what-it-generates","title":"What it generates","text":"Kind Source Output lib GSDFC docstrings docs/lib/** rendered markdown api OpenAPI JSON spec docs/api/** rendered markdown wiki Hand-written markdown docs/wiki/** (unchanged) mcp GSDFC docstrings + renderers docs/mcp/** structured JSON"},{"location":"01_overview/#per-kind-mkdocs-builds","title":"Per-kind MkDocs builds","text":"Each enabled site kind produces its own MkDocs configuration and build:
--mkdocs (lib) writes docs/mkdocs.lib.yml and builds site/lib/.--api writes docs/mkdocs.api.yml and builds site/api/.--wiki writes docs/mkdocs.wiki.yml and builds site/wiki/.
Every site is self-contained (own theme assets and search index) with navigation derived or scoped to that kind. Hand-written wiki content is never overwritten or regenerated \u2014 only its navigation is derived automatically.
"},{"location":"01_overview/#mcp-bundle","title":"MCP bundle","text":"docs/mcp/** is a self-contained, machine-readable reference generated from docforge's own GSDFC docstrings. doc-forge serve --mcp --module docforge serves it over MCP. See the MCP Guide.
"},{"location":"02_architecture/","title":"Architecture","text":"docforge is split into four horizontal layers. Everything flows top to bottom through the CLI.
"},{"location":"02_architecture/#loaders-models","title":"Loaders \u2192 Models","text":"The docforge/loaders package wraps griffe to extract modules, functions, classes, and Google-style docstring sections. Loaded data is normalized into the object model under docforge/models (Project, Module, DocObject).
"},{"location":"02_architecture/#navigation","title":"Navigation","text":"docforge/nav parses docforge.nav.yml specs (NavSpec, Resolver, and the MkDocs nav emitter) and, since the wiki kind, derives wiki navigation from the file structure via build_wiki_nav.
"},{"location":"02_architecture/#renderers","title":"Renderers","text":"docforge/renderers turn model data into artifacts:
MkDocsRenderer \u2192 docs/lib/** reference markdownMCPRenderer \u2192 docs/mcp/** structured documentation
"},{"location":"02_architecture/#servers","title":"Servers","text":"docforge/servers serves generated artifacts over live protocols:
MCPServer \u2192 serves a pre-generated docs/mcp/** bundle through MCP resources (docs://index, docs://nav, docs://modules/{module})
"},{"location":"02_architecture/#cli","title":"CLI","text":"docforge/cli wires it all together:
commands.py \u2014 the build command and its --mkdocs / --api / --wiki / --mcp modesmkdocs_utils.py \u2014 per-kind config generation (docs/mkdocs.{lib,api,wiki}.yml) with navigation re-rooted to each kind's docs_dirapi_utils.py \u2014 OpenAPI loading and API docs generation
"},{"location":"03_conventions/","title":"Conventions","text":""},{"location":"03_conventions/#gsdfc-docstrings","title":"GSDFC docstrings","text":"All documented source uses the Google-Styled Doc-Forge Convention (GSDFC): Args:, Returns:, Raises:, and Attributes: sections with properly typed signatures.
The authoritative GSDFC specification lives in the docforge/__init__.py package docstring, which is exported verbatim into docs/mcp/modules/docforge.json, so the MCP bundle is self-documenting.
Key rules:
- Use parenthesized types in prose entries (
name (Type):) that match the signature types. - Use
# Summary, # Examples, and # Notes sections at module level. - Use
Args:, Returns:, Raises:, Yields:, Notes:, and Example: sections at function and method level. - Always update the matching
.pyi stub alongside the .py implementation.
"},{"location":"03_conventions/#pyi-stubs","title":".pyi stubs","text":"Every module ships a matching .pyi stub kept in sync with the .py implementation. When signatures change, update both files.
"},{"location":"03_conventions/#wiki-pages","title":"Wiki pages","text":" - Hand-written markdown lives in
docs/wiki/** and is never generated. - File names use a numeric prefix:
01_overview.md, 02_architecture.md. - Nested directories become nested navigation groups:
05_development/01_environment.md \u2192 group Development. index.md is the site Home at the root, and a section root inside a directory.- Navigation labels are derived by stripping the numeric prefix and applying title case on the remaining words.
"},{"location":"03_conventions/#templates","title":"Templates","text":"MkDocs config fragments live in docforge/templates. The mkdocs.wiki.yml fragment carries only the search plugin, since wiki pages contain no mkdocstrings directives.
"},{"location":"04_iterative_workflow/","title":"Iterative Workflow","text":"A docs build runs through the CLI in a single pass.
"},{"location":"04_iterative_workflow/#build-commands","title":"Build commands","text":"# Library reference only\ndoc-forge build --mkdocs --module docforge\n\n# Wiki + library (each an independent MkDocs build)\ndoc-forge build --wiki --mkdocs --module docforge\n\n# Wiki only \u2014 no module required\ndoc-forge build --wiki --site-name docforge\n\n# MCP structured bundle\ndoc-forge build --mcp --module docforge\n
"},{"location":"04_iterative_workflow/#what-a-build-does","title":"What a build does","text":" - Validates the requested modes (
--mkdocs, --api, --wiki, --mcp). - Generates library sources under
docs/lib/** with MkDocsRenderer. - Generates API sources under
docs/api/** when --api is given. - Derives the wiki navigation from
docs/wiki/**. - Writes one MkDocs config per site kind (
docs/mkdocs.{lib,api,wiki}.yml), re-rooting navigation paths to each kind's docs_dir. - Runs
mkdocs build once per config, emitting self-contained sites site/lib/, site/api/, and site/wiki/.
"},{"location":"04_iterative_workflow/#explore-the-sites","title":"Explore the sites","text":"doc-forge build --wiki --mkdocs --module docforge\ndoc-forge serve --wiki # serves site preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or target any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n
"},{"location":"04_iterative_workflow/#serve-the-mcp-bundle","title":"Serve the MCP bundle","text":"doc-forge build --mcp --module docforge\ndoc-forge serve --mcp --module docforge\n
"},{"location":"05_development/01_environment/","title":"Environment Setup","text":""},{"location":"05_development/01_environment/#create-the-environment","title":"Create the environment","text":"python -m venv .venv\n.venv\\Scripts\\activate\npip install -e .\n
Requires Python 3.10+ (per pyproject.toml).
"},{"location":"05_development/01_environment/#dependencies","title":"Dependencies","text":"Development extras include:
pytest, pytest-cov \u2014 test suite and coverageruff \u2014 lint and format checkingblack \u2014 auto-formattingmypy \u2014 strict typing checkspydoclint \u2014 docstring \u2194 signature consistency checks
"},{"location":"05_development/02_quality_gates/","title":"Quality Gates","text":"Run all checks before pushing:
.venv\\Scripts\\python.exe -m pytest\n.venv\\Scripts\\python.exe -m ruff check docforge tests\n.venv\\Scripts\\python.exe -m black --check docforge tests\n.venv\\Scripts\\python.exe -m mypy docforge\n.venv\\Scripts\\pydoclint.exe docforge\n
"},{"location":"05_development/02_quality_gates/#test-layout","title":"Test layout","text":"Path Covers tests/nav/ Nav spec, resolver, wiki nav tests/cli/ Build command flows and modes tests/renderers/ MkDocs / MCP rendering CLI tests use the cli_runner fixture with mock_mkdocs_build and mock_mkdocs_load_config so they exercise the full flow without invoking a real MkDocs build.
"},{"location":"05_development/03_gsdfc_guide/","title":"GSDFC Docstring Guide","text":"This page is the practical companion to the authoritative GSDFC specification in the docforge/__init__.py package docstring. It describes how to write docstrings that render correctly in MkDocs and stay machine-parseable by doc-forge, MkDocs, and MCP clients.
"},{"location":"05_development/03_gsdfc_guide/#overview","title":"Overview","text":" - Docstrings are the single source of truth.
doc-forge compiles docstrings but never rewrites them.- Every public symbol should have a complete, accurate docstring.
- Type hints live in signatures; prose entries repeat the type in parentheses and must match the signature.
"},{"location":"05_development/03_gsdfc_guide/#module-docstrings","title":"Module docstrings","text":"Modules use Markdown headings and --- separators.
Recommended sections:
# Summary \u2014 what the subsystem does# Examples \u2014 a representative usage snippet# Notes \u2014 guarantees, lifecycle, and thread-safety notes
"},{"location":"05_development/03_gsdfc_guide/#class-docstrings","title":"Class docstrings","text":"Recommended sections, in order:
- summary line describing responsibility
Attributes: \u2014 instance attributes with name (Type): entriesNotes: \u2014 grouped subsections such as Guarantees, LifecycleExample: \u2014 indented python code block
"},{"location":"05_development/03_gsdfc_guide/#function-and-method-docstrings","title":"Function and method docstrings","text":"Recommended section order:
Args:Returns:Raises:Yields:Notes:Example:
Formatting rules:
Args: entries are name (Type): followed by an indented description.Returns: entries are Type: followed by an indented description.Raises: entries are ExceptionType: followed by an indented condition.Yields: replaces Returns: for generators.- Summaries are written in the imperative mood.
- Fenced
python blocks are allowed inside Example: sections, indented four spaces.
"},{"location":"05_development/03_gsdfc_guide/#property-docstrings","title":"Property docstrings","text":"Properties document their return values with a Returns: section and, when meaningful, an Example:.
"},{"location":"05_development/03_gsdfc_guide/#example","title":"Example","text":"def process(foo: Foo, multiplier: int) -> int:\n \"\"\"Process a Foo instance.\n\n Args:\n foo (Foo):\n Foo instance to process.\n\n multiplier (int):\n Value used to scale foo.\n\n Returns:\n int:\n Processed result.\n\n Raises:\n ValueError:\n If multiplier is negative.\n\n Example:\n Process foo:\n\n ```python\n foo = Foo(\"example\", value=10)\n result = process(foo, multiplier=2)\n print(result)\n ```\n \"\"\"\n
"},{"location":"05_development/03_gsdfc_guide/#keeping-stubs-in-sync","title":"Keeping stubs in sync","text":"Every .py module ships a matching .pyi stub. When a signature or a public symbol changes, update both files. Signature annotations in the stub must match the implementation.
"},{"location":"05_development/03_gsdfc_guide/#enforcement","title":"Enforcement","text":"pydoclint (Google style) runs in CI and verifies that Args:/Returns: sections match function signatures, including types.
allow-init-docstring = true \u2014 __init__ docstrings are allowed.skip-checking-raises = true \u2014 Raises: sections are descriptive and are not required to map to literal raise statements.check-class-attributes = false \u2014 Attributes: sections document instance attributes without class-level annotations.
"},{"location":"05_development/04_mcp_guide/","title":"MCP Guide","text":"Doc-forge can export a machine-readable MCP bundle from a project's GSDFC docstrings and serve that bundle over the Model Context Protocol (MCP). The bundle is self-contained: readers can derive the full API reference \u2014 signatures, docstrings, and structure \u2014 for the documented project.
"},{"location":"05_development/04_mcp_guide/#building-the-bundle","title":"Building the bundle","text":"doc-forge build --mcp --module docforge\n
This writes structured JSON into docs/mcp/:
index.json \u2014 project metadata and module countnav.json \u2014 module list with docs://modules/{module} resource URIsmodules/{dotted.path}.json \u2014 per-module serialized documentation
"},{"location":"05_development/04_mcp_guide/#serving-the-bundle","title":"Serving the bundle","text":"doc-forge serve --mcp --module docforge\n
The MCPServer (in docforge/servers/mcp_server.py) exposes:
Resource Description docs://index Project metadata docs://nav Navigation structure docs://modules/{module} Individual module documentation The server also registers a single diagnostic tool, ping, and is read-only. Missing resources are returned as structured error dictionaries rather than exceptions. The default transport is streamable-http; stdio and sse are supported via MCPServer.run.
"},{"location":"05_development/04_mcp_guide/#bundle-contents","title":"Bundle contents","text":"Each module resource contains:
path \u2014 dotted module pathdocstring \u2014 the raw GSDFC module docstringobjects \u2014 a recursive mapping of public symbols with name, kind, path, signature, and docstring, plus nested members
Because the bundle is generated from docstrings, the quality of the bundle equals the quality of the project's GSDFC docstrings. For docforge itself, the GSDFC specification is carried in modules/docforge.json via the docforge/__init__.py package docstring, making the bundle self-documenting.
"},{"location":"05_development/05_mkdocs_configs/","title":"MkDocs Configuration Model","text":"Each documentation kind (lib, api, wiki) is built by its own MkDocs site. A repo that documents kind {kind} carries a config at docs/mkdocs.{kind}.yml that sets docs_dir to the kind's source directory and site_dir to ../site/{kind}.
"},{"location":"05_development/05_mkdocs_configs/#file-wins","title":"File wins","text":"docs/mkdocs.{kind}.yml is a repo-owned file, not a build byproduct:
- Absent \u2014
doc-forge build --{kind} materializes a copy from the packaged templates (see below) and then builds site/{kind}. - Present \u2014 the build uses the file verbatim. Edits to the theme, palette, plugins, markdown extensions, nav, or
site_dir are respected as-is. --refresh \u2014 force-regenerates the file from the templates, replacing any local changes.
Because a present file is never rewritten, rerunning a build is a no-op for versioned configs: the working tree stays clean.
"},{"location":"05_development/05_mkdocs_configs/#templates","title":"Templates","text":"The built-in defaults live in docforge/templates/:
File Role mkdocs.common.yml Shared theme + markdown extensions mkdocs.lib.yml mkdocstrings handler for library reference mkdocs.api.yml Swagger/OpenAPI plugins and API-side features mkdocs.wiki.yml Wiki look: horizontal navigation.tabs header, blue grey/teal palette, Roboto A per-kind config is generated by deep-merging the common template with the kind fragment, then filling in generation-time values (site_name, docs_dir, site_dir, nav, API site_description/site_author, and the theme icon from docforge.nav.yml). Pass --template <path> to replace the built-in templates entirely.
"},{"location":"05_development/05_mkdocs_configs/#supported-layouts","title":"Supported layouts","text":" - Per-kind config \u2014 the standard layout; each kind builds to
site/{kind} and is served under /<repo>/{kind}/. - Legacy root config \u2014 a repo with a single kind may instead author root
mkdocs.yml (for example mongo-ops, whose wiki uses docs_dir: docs/wiki). doc-forge never reads or writes root mkdocs.yml; the docs service maps the kind to the root site/ dir in this case.
Commit docs/mkdocs.{kind}.yml so served docs are reproducible from source.
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83e\udde9 docforge \u2014 Docstring-Driven Documentation Forge","text":"docforge is an internal documentation tool that generates reference documentation from Google-Styled Doc-Forge Convention (GSDFC) docstrings and assembles it into per-kind MkDocs sites, alongside hand-written wiki pages and OpenAPI-based API docs.
Doc model: this wiki is written for humans \u2014 how\u2011to guides, examples, and testing recipes. The authoritative API contracts live in the code (docstrings) and the machine\u2011readable bundle under docs/mcp/.
"},{"location":"#key-features","title":"\ud83d\ude80 Key Features","text":" - \ud83e\uddea GSDFC docstring extraction via Griffe
- \ud83e\udded Auto-derived navigation for hand-written wiki pages
- \ud83d\uddc2 Independent MkDocs builds per kind (lib, api, wiki) into
site/{kind} - \ud83d\udd0c Material MkDocs theming out of the box
- \ud83d\udce6 MCP structured documentation resources
"},{"location":"#installation","title":"\ud83d\udce6 Installation","text":"# Internal PyPI (TBD)\npip install docforge\n
"},{"location":"#documentation-structure","title":"\ud83d\udcc1 Documentation Structure","text":"Section Description Overview What docforge is and how it fits the pipeline Components Loaders, models, nav, renderers, CLI, servers Conventions GSDFC, .pyi stubs, and template conventions Iterative Workflow How a docs build runs end to end Environment Environment setup Quality Gates Test layout and quality checks GSDFC Guide How to write GSDFC-conformant docstrings MCP Guide Building, serving, and consuming the MCP bundle MkDocs Configs MkDocs config generation and templates"},{"location":"#related-resources","title":"\ud83d\udd17 Related Resources","text":" - Source Code: the
doc-forge repository - 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 # AGENTS.md \u2014 Wiki Authoring Guide (Aetoskia)\n\nThis file instructs AI agents how to create, extend, and maintain the wiki\n(`docs/wiki/**`) for any Aetoskia repository. The reference implementation is\n`mongo-ops` \u2014 its wiki went through several revisions to reach the structure\nbelow and should be treated as the canonical example.\n\n---\n\n## 1. Doc model \u2014 know the two sources of truth\n\nEvery repo keeps two distinct kinds of documentation that must **not** bleed\ninto each other:\n\n| Kind | Source | Where | Audience |\n|-------------------|-----------------------|------------------------------------------|------------------------------------|\n| **Wiki** | Hand-written markdown | `docs/wiki/**` | Humans (how-to, examples, testing) |\n| **API reference** | Docstrings (GSDFC) | Generated \u2192 `docs/lib/**`, `docs/mcp/**` | Consumers (exact contracts) |\n\nRules:\n\n- The wiki is written **for humans** \u2014 how-to guides, recipes, and testing\n patterns. It is never generated.\n- API contracts (signatures, parameter types, exact behavior) live in the\n docstrings and the machine-readable bundle under `docs/mcp/`. **Never**\n duplicate full API documentation in the wiki \u2014 link to the lib site instead.\n- If a page starts to drift into contract territory, cut it down to usage and\n point at `docs/lib/`.\n- This doc model is stated on every index page as a blockquote; keep it there:\n > **Doc model:** this wiki is written for humans \u2014 how\u2011to guides, examples,\n > and testing recipes. The authoritative API contracts live in the code\n > (docstrings) and the machine\u2011readable bundle under `docs/mcp/`.\n\n---\n\n## 2. Directory layout & file naming\n\n```\ndocs/wiki/\n\u251c\u2500\u2500 index.md # site Home\n\u251c\u2500\u2500 01_overview.md\n\u251c\u2500\u2500 02_components.md\n\u251c\u2500\u2500 03_use_cases/ # nested directory \u2192 nav group\n\u2502 \u251c\u2500\u2500 01_basic_crud.md\n\u2502 \u251c\u2500\u2500 02_custom_repo.md\n\u2502 \u2514\u2500\u2500 ...\n\u251c\u2500\u2500 04_best_practices.md\n\u251c\u2500\u2500 06_error_handling.md\n\u2514\u2500\u2500 07_testing_example.md\n```\n\n- Location: `docs/wiki/` (hand-written only).\n- File names: `NN_snake_case_name.md` with a **zero-padded two-digit** numeric\n prefix. e.g. `01_overview.md`, `03_use_cases/07_caching.md`.\n- Top-level pages use `NN_name.md` directly. High-volume sections get their own\n directory, e.g. `03_use_cases/NN_name.md` (nav group \"Use Cases\").\n- **No frontmatter.** Every file opens directly with an H1 `# Title`.\n- Navigation labels are short human titles set explicitly in\n `docs/mkdocs.wiki.yml` (title case) \u2014 often **shorter** than the page H1.\n Example: nav label `Basic CRUD` vs page H1 `Use Case 1: Basic FastAPI CRUD API`.\n Never use the raw filename slug as the label.\n- Renumbering: prefixes order pages. When inserting a page, pick the next\n number in the relevant group (subgroup numbers stay grouped).\n\n---\n\n## 3. Navigation \u2014 `docs/mkdocs.wiki.yml` is the source of truth\n\nEvery wiki page **must** be wired into the nav defined in\n`docs/mkdocs.wiki.yml`. If a page is not in the nav, it is orphaned.\n\n- The `nav:` block mirrors the directory tree; directories become nested\n groups.\n- When a section has many pages, group them **by theme** into nested\n subgroups. mongo-ops groups its use cases into:\n `Getting Started`, `Data & Queries`, `Caching`, `Population`,\n `Advanced Usage`.\n- Keep `index.md`'s **Documentation Structure** table in sync with the nav \u2014\n it is the human-facing version of the same TOC. Every nav entry needs a row\n (or nested bullet group) there.\n- Nav label = human title (title case), not the filename slug.\n\n---\n\n## 4. Page anatomy\n\n### 4.1 `index.md` (Home)\n\n```\n# \ud83e\udde9 <package> \u2014 <slogan>\n<one-paragraph pitch>\n\n> **Doc model:** \u2026 (see \u00a71)\n\n---\n\n## \ud83d\ude80 Key Features (bullet list, emoji per feature)\n## \ud83d\udce6 Installation (code blocks: internal PyPI, extras, local source)\n## \ud83d\udcc1 Documentation Structure (table = TOC, mirrors nav exactly)\n## \ud83d\udd17 Related Resources (bullets: source repo, internal PyPI, CI)\n---\n\u00a9 Aetoskia Internal \u2014 `<package>` <version>\n```\n\n### 4.2 Overview page (`01_*`)\n\n- Opens with `# Library Overview`, one sentence about what the library does,\n then a line stating the page builds the mental model.\n- Sections: `## \ud83c\udfd7\ufe0f Architecture` (ASCII diagram + numbered layer list),\n `## \ud83d\udd04 Lifecycle Rules` (table: step / call / why),\n `## \ud83e\udded Which \u2026 Should You Use?` (decision table).\n- Ends with `## \u27a1\ufe0f Read Next` (cross-links to the next pages to read).\n\n### 4.3 Components page (`02_*`)\n\n- Validated reference for the public API surface \u2014 describes what each\n component is for and how the pieces wire together. Keep it usage-level;\n exact signatures belong in `docs/lib/`.\n- Anatomy: numbered sections, one per component (`## 1. MongoConnectionManager`,\n `## 2. BaseDocument`, \u2026), with `### 8.1`-style sub-numbering for related\n types under a component (e.g. the cache layer's backend / stats / config /\n in-memory / redis implementations). Ends with `## Related`.\n\n### 4.4 Use-case page (the most common)\n\nStandard anatomy, in this order:\n\n```\n# Use Case N: <Human Title>\n\n**Scenario:** <one sentence: the problem this recipe solves>\n\n---\n\n## \ud83d\udce6 What's New? (table: Component | Description \u2014 new API used here)\n## \ud83d\ude80 Example (languaged code block, complete runnable-looking snippet)\n## \ud83d\udca1 Tips (bullets: gotchas, ordering, common mistakes)\n## Related (\u00a75)\n```\n\n### 4.5 Deep-dive / worked-example page\n\nFor intricate flows (population shapes, cache round-trips), use numbered\ndepth-first sections and comparison tables:\n\n```\n## 1. <Write path> (### 1a., ### 1b., \u2026 per sub-case)\n## 2. <Read path>\n## 3. <Round trip / tricky bit>\n## 4. When to use which (comparison table)\n## Related\n```\n\n### 4.6 Best Practices page (`04_*`)\n\n- Flat themed `##` sections (e.g. Layering, Lifecycle, Data & Performance,\n Transactions & Errors, Testing), each a short list of numbered conventions.\n- Pure prose \u2014 no large code blocks.\n\n### 4.7 Error Handling (`06_*`) / Testing pages\n\n- **Error Handling:** an exceptions table (`Exception | Source | Meaning / fix`),\n a `> ` note on which failures are by design, a `## \ud83d\ude80 FastAPI Mapping Example`\n code block, then `## \ud83d\udca1 Tips` bullets, then `## Related`.\n- **Testing example (`07_*`):** `## \ud83d\ude80 Mock-Based Quickstart` (focused code\n block), `## \ud83d\udca1 Notes` tip list, `## Related`.\n\nCommon to all pages: no frontmatter, `---` between every major section, and a\n`## Related` (or variant) footer as the **last** section.\n\n---\n\n## 5. The `## Related` footer\n\nEvery page ends with a cross-link footer. Rules:\n\n- Always the **last** section, always preceded by a `---`.\n- Standard heading: `## Related` (no emoji).\n- One bullet line; links separated by ` \u00b7 ` (middle dot plus spaces).\n- Link label format: `[NN \u2013 Title](relative_path)` \u2014 en-dash, page number, title.\n- Paths are **relative**: same directory \u2192 `02_custom_repo.md`; parent \u2192\n `../01_overview.md`; child \u2192 `03_use_cases/01_basic_crud.md`.\n- Link order follows nav order (each `Related` points to related next/sibling\n pages, plus the overview/components anchor).\n\nExamples (from mongo-ops):\n\n```\n## Related\n- [02 \u2013 Custom repository](02_custom_repo.md) \u00b7 [04 \u2013 Pagination](04_pagination.md) \u00b7 [Overview](../01_overview.md)\n```\n\nVariants:\n\n- `## \u27a1\ufe0f Read Next` \u2014 used on the overview page (linear reading order).\n- `## \ud83d\udd17 Related Resources` \u2014 only on `index.md`, one bullet per external resource.\n\n---\n\n## 6. Tone & formatting rules\n\n- **Written for humans**: short sentences, concrete examples, plain words.\n- Emoji-prefixed H2 headings for recognizable section types\n (`\ud83d\udce6 What's New?`, `\ud83d\ude80 Example`, `\ud83d\udca1 Tips`, `\ud83d\ude80 Key Features`).\n- `---` horizontal rule between every major section.\n- Code blocks always declare a language (```python, ```bash, etc.).\n- Use tables for comparisons and structured decisions; bullets for lists;\n ASCII diagrams for architecture.\n- Bold key terms inline. Use `inline code` for symbols/APIs.\n- Keep pages focused: one recipe/purpose per page. If a page balloons past\n ~10 KB, split it (add a numbered deep-dive page instead).\n- Match tone of existing pages in the repo before writing new ones.\n\n---\n\n## 7. Build & verify workflow\n\nAfter creating or editing wiki pages:\n\n```bash\n# 1. Build the wiki (from the repo root)\ndoc-forge build --wiki # wiki only\ndoc-forge build --wiki --mkdocs --module <pkg> # wiki + lib together\n\n# 2. Preview locally\ndoc-forge serve --wiki\n\n# 3. Collect into the hub (run from the docs/ service repo)\npython collect.py # copies site, regenerates index + nginx.conf\npython collect.py --dry-run # preview without writing\n```\n\nVerification checklist:\n\n- `doc-forge build --wiki` completes with no warnings about missing files.\n- Every new page is present in `docs/mkdocs.wiki.yml` **and** in the index\n Documentation Structure table.\n- Every page ends with a `## Related` block and no dead links (paths resolve).\n- After `collect.py`: the hub card links to both `/wiki/` and `/lib/` and the\n pages render (spot-check with the served site).\n- If code/docstrings changed (no change when wiki-only), run the repo gates:\n `black`, `ruff`, `mypy`, `pytest`.\n\n---\n\n## 8. Before/after checklist\n\n**Before creating a page:**\n\n- [ ] Confirm it is genuinely wiki material (how-to) and not API contract.\n- [ ] Find the right filename (`NN_snake_case.md`) and directory for its theme.\n- [ ] Outline the sections per \u00a74 anatomy that fits the content.\n\n**After creating/editing a page:**\n\n- [ ] Page wired into `docs/mkdocs.wiki.yml` nav (themed subgroup if needed).\n- [ ] `index.md` Documentation Structure table updated.\n- [ ] `## Related` footer present, relative links, nav order.\n- [ ] `---` separators consistent; no frontmatter; emoji headings where apt.\n- [ ] Build passes; collect run; hub shows `/wiki/` + `/lib/` links.\n- [ ] No orphaned files, no dead links.\n
\u00a9 Aetoskia Internal \u2014 docforge 1.0
"},{"location":"01_overview/","title":"Library Overview","text":"docforge turns GSDFC-compliant Python docstrings into maintainable reference documentation. It never edits source docstrings; it reads them, renders them, and assembles documentation sites from all available material.
"},{"location":"01_overview/#which-build-should-you-use","title":"\ud83e\udded Which Build Should You Use?","text":"Kind Source Output lib GSDFC docstrings docs/lib/** rendered markdown api OpenAPI JSON spec docs/api/** rendered markdown wiki Hand-written markdown docs/wiki/** (unchanged) mcp GSDFC docstrings + renderers docs/mcp/** structured JSON"},{"location":"01_overview/#architecture","title":"\ud83c\udfd7\ufe0f Architecture","text":"Each enabled site kind produces its own MkDocs configuration and build:
--mkdocs (lib) writes docs/mkdocs.lib.yml and builds site/lib/.--api writes docs/mkdocs.api.yml and builds site/api/.--wiki writes docs/mkdocs.wiki.yml and builds site/wiki/.
Every site is self-contained (own theme assets and search index) with navigation derived or scoped to that kind. Hand-written wiki content is never overwritten or regenerated \u2014 only its navigation is derived automatically.
"},{"location":"01_overview/#lifecycle-rules","title":"\ud83d\udd04 Lifecycle Rules","text":"docs/mcp/** is a self-contained, machine-readable reference generated from docforge's own GSDFC docstrings. doc-forge serve --mcp --module docforge serves it over MCP. See the MCP Guide.
"},{"location":"01_overview/#read-next","title":"\u27a1\ufe0f Read Next","text":" - 02 \u2013 Components \u00b7 03 \u2013 Conventions
"},{"location":"02_components/","title":"Components","text":"docforge is split into four horizontal layers. Everything flows top to bottom through the CLI.
"},{"location":"02_components/#1-loaders-models","title":"1. Loaders & Models","text":"The docforge/loaders package wraps griffe to extract modules, functions, classes, and Google-style docstring sections. Loaded data is normalized into the object model under docforge/models (Project, Module, DocObject).
"},{"location":"02_components/#2-navigation","title":"2. Navigation","text":"docforge/nav parses docforge.nav.yml specs (NavSpec, Resolver, and the MkDocs nav emitter) and, since the wiki kind, derives wiki navigation from the file structure via build_wiki_nav.
"},{"location":"02_components/#3-renderers","title":"3. Renderers","text":"docforge/renderers turn model data into artifacts:
MkDocsRenderer \u2192 docs/lib/** reference markdownMCPRenderer \u2192 docs/mcp/** structured documentation
"},{"location":"02_components/#4-servers","title":"4. Servers","text":"docforge/servers serves generated artifacts over live protocols:
MCPServer \u2192 serves a pre-generated docs/mcp/** bundle through MCP resources (docs://index, docs://nav, docs://modules/{module})
"},{"location":"02_components/#5-cli","title":"5. CLI","text":"docforge/cli wires it all together:
commands.py \u2014 the build command and its --mkdocs / --api / --wiki / --mcp modesmkdocs_utils.py \u2014 per-kind config generation (docs/mkdocs.{lib,api,wiki}.yml) with navigation re-rooted to each kind's docs_dirapi_utils.py \u2014 OpenAPI loading and API docs generation
"},{"location":"02_components/#related","title":"Related","text":" - 01 \u2013 Overview \u00b7 03 \u2013 Conventions
"},{"location":"03_conventions/","title":"Conventions","text":""},{"location":"03_conventions/#gsdfc-docstrings","title":"GSDFC docstrings","text":"All documented source uses the Google-Styled Doc-Forge Convention (GSDFC): Args:, Returns:, Raises:, and Attributes: sections with properly typed signatures.
The authoritative GSDFC specification lives in the docforge/__init__.py package docstring, which is exported verbatim into docs/mcp/modules/docforge.json, so the MCP bundle is self-documenting.
Key rules:
- Use parenthesized types in prose entries (
name (Type):) that match the signature types. - Use
# Summary, # Examples, and # Notes sections at module level. - Use
Args:, Returns:, Raises:, Yields:, Notes:, and Example: sections at function and method level. - Always update the matching
.pyi stub alongside the .py implementation.
"},{"location":"03_conventions/#pyi-stubs","title":".pyi stubs","text":"Every module ships a matching .pyi stub kept in sync with the .py implementation. When signatures change, update both files.
"},{"location":"03_conventions/#wiki-pages","title":"Wiki pages","text":" - Hand-written markdown lives in
docs/wiki/** and is never generated. - File names use a numeric prefix:
01_overview.md, 02_components.md. - Nested directories become nested navigation groups:
05_development/01_environment.md \u2192 group Development. index.md is the site Home at the root, and a section root inside a directory.- Navigation labels are derived by stripping the numeric prefix and applying title case on the remaining words.
"},{"location":"03_conventions/#templates","title":"Templates","text":"MkDocs config fragments live in docforge/templates. The mkdocs.wiki.yml fragment carries only the search plugin, since wiki pages contain no mkdocstrings directives.
"},{"location":"03_conventions/#related","title":"Related","text":" - 02 \u2013 Components \u00b7 04 \u2013 Iterative Workflow
"},{"location":"04_iterative_workflow/","title":"Iterative Workflow","text":"A docs build runs through the CLI in a single pass.
"},{"location":"04_iterative_workflow/#build-commands","title":"\ud83d\ude80 Build commands","text":"# Library reference only\ndoc-forge build --mkdocs --module docforge\n\n# Wiki + library (each an independent MkDocs build)\ndoc-forge build --wiki --mkdocs --module docforge\n\n# Wiki only \u2014 no module required\ndoc-forge build --wiki --site-name docforge\n\n# MCP structured bundle\ndoc-forge build --mcp --module docforge\n
"},{"location":"04_iterative_workflow/#what-a-build-does","title":"\ud83d\udd04 What a build does","text":" - Validates the requested modes (
--mkdocs, --api, --wiki, --mcp). - Generates library sources under
docs/lib/** with MkDocsRenderer. - Generates API sources under
docs/api/** when --api is given. - Derives the wiki navigation from
docs/wiki/**. - Writes one MkDocs config per site kind (
docs/mkdocs.{lib,api,wiki}.yml), re-rooting navigation paths to each kind's docs_dir. - Runs
mkdocs build once per config, emitting self-contained sites site/lib/, site/api/, and site/wiki/.
"},{"location":"04_iterative_workflow/#explore-the-sites","title":"\ud83e\udded Explore the sites","text":"doc-forge build --wiki --mkdocs --module docforge\ndoc-forge serve --wiki # serves site preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or target any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n
"},{"location":"04_iterative_workflow/#serve-the-mcp-bundle","title":"\ud83d\udce6 Serve the MCP bundle","text":"doc-forge build --mcp --module docforge\ndoc-forge serve --mcp --module docforge\n
"},{"location":"04_iterative_workflow/#related","title":"Related","text":" - 03 \u2013 Conventions \u00b7 01 \u2013 Environment
"},{"location":"05_development/01_environment/","title":"Environment Setup","text":""},{"location":"05_development/01_environment/#create-the-environment","title":"\ud83d\ude80 Create the environment","text":"python -m venv .venv\n.venv\\Scripts\\activate\npip install -e .\n
Requires Python 3.10+ (per pyproject.toml).
"},{"location":"05_development/01_environment/#dependencies","title":"\ud83d\udce6 Dependencies","text":"Development extras include:
pytest, pytest-cov \u2014 test suite and coverageruff \u2014 lint and format checkingblack \u2014 auto-formattingmypy \u2014 strict typing checkspydoclint \u2014 docstring \u2194 signature consistency checks
"},{"location":"05_development/01_environment/#related","title":"Related","text":" - 04 \u2013 Iterative Workflow \u00b7 02 \u2013 Quality Gates
"},{"location":"05_development/02_quality_gates/","title":"Quality Gates","text":"Run all checks before pushing:
"},{"location":"05_development/02_quality_gates/#commands","title":"\ud83d\ude80 Commands","text":".venv\\Scripts\\python.exe -m pytest\n.venv\\Scripts\\python.exe -m ruff check docforge tests\n.venv\\Scripts\\python.exe -m black --check docforge tests\n.venv\\Scripts\\python.exe -m mypy docforge\n.venv\\Scripts\\pydoclint.exe docforge\n
"},{"location":"05_development/02_quality_gates/#test-layout","title":"\ud83d\udcc1 Test layout","text":"Path Covers tests/nav/ Nav spec, resolver, wiki nav tests/cli/ Build command flows and modes tests/renderers/ MkDocs / MCP rendering CLI tests use the cli_runner fixture with mock_mkdocs_build and mock_mkdocs_load_config so they exercise the full flow without invoking a real MkDocs build.
"},{"location":"05_development/02_quality_gates/#related","title":"Related","text":" - 01 \u2013 Environment \u00b7 03 \u2013 GSDFC Guide
"},{"location":"05_development/03_gsdfc_guide/","title":"GSDFC Docstring Guide","text":"This page is the practical companion to the authoritative GSDFC specification in the docforge/__init__.py package docstring. It describes how to write docstrings that render correctly in MkDocs and stay machine-parseable by doc-forge, MkDocs, and MCP clients.
"},{"location":"05_development/03_gsdfc_guide/#overview","title":"\ud83e\udded Overview","text":" - Docstrings are the single source of truth.
doc-forge compiles docstrings but never rewrites them.- Every public symbol should have a complete, accurate docstring.
- Type hints live in signatures; prose entries repeat the type in parentheses and must match the signature.
"},{"location":"05_development/03_gsdfc_guide/#module-docstrings","title":"\ud83d\udce6 Module docstrings","text":"Modules use Markdown headings and --- separators.
Recommended sections:
# Summary \u2014 what the subsystem does# Examples \u2014 a representative usage snippet# Notes \u2014 guarantees, lifecycle, and thread-safety notes
"},{"location":"05_development/03_gsdfc_guide/#class-docstrings","title":"\ud83d\udce6 Class docstrings","text":"Recommended sections, in order:
- summary line describing responsibility
Attributes: \u2014 instance attributes with name (Type): entriesNotes: \u2014 grouped subsections such as Guarantees, LifecycleExample: \u2014 indented python code block
"},{"location":"05_development/03_gsdfc_guide/#function-and-method-docstrings","title":"\ud83d\udce6 Function and method docstrings","text":"Recommended section order:
Args:Returns:Raises:Yields:Notes:Example:
Formatting rules:
Args: entries are name (Type): followed by an indented description.Returns: entries are Type: followed by an indented description.Raises: entries are ExceptionType: followed by an indented condition.Yields: replaces Returns: for generators.- Summaries are written in the imperative mood.
- Fenced
python blocks are allowed inside Example: sections, indented four spaces.
"},{"location":"05_development/03_gsdfc_guide/#property-docstrings","title":"\ud83d\udce6 Property docstrings","text":"Properties document their return values with a Returns: section and, when meaningful, an Example:.
"},{"location":"05_development/03_gsdfc_guide/#example","title":"\ud83d\ude80 Example","text":"def process(foo: Foo, multiplier: int) -> int:\n \"\"\"Process a Foo instance.\n\n Args:\n foo (Foo):\n Foo instance to process.\n\n multiplier (int):\n Value used to scale foo.\n\n Returns:\n int:\n Processed result.\n\n Raises:\n ValueError:\n If multiplier is negative.\n\n Example:\n Process foo:\n\n ```python\n foo = Foo(\"example\", value=10)\n result = process(foo, multiplier=2)\n print(result)\n ```\n \"\"\"\n
"},{"location":"05_development/03_gsdfc_guide/#keeping-stubs-in-sync","title":"\ud83d\udd04 Keeping stubs in sync","text":"Every .py module ships a matching .pyi stub. When a signature or a public symbol changes, update both files. Signature annotations in the stub must match the implementation.
"},{"location":"05_development/03_gsdfc_guide/#enforcement","title":"\ud83d\udee1\ufe0f Enforcement","text":"pydoclint (Google style) runs in CI and verifies that Args:/Returns: sections match function signatures, including types.
allow-init-docstring = true \u2014 __init__ docstrings are allowed.skip-checking-raises = true \u2014 Raises: sections are descriptive and are not required to map to literal raise statements.check-class-attributes = false \u2014 Attributes: sections document instance attributes without class-level annotations.
"},{"location":"05_development/03_gsdfc_guide/#related","title":"Related","text":" - 02 \u2013 Quality Gates \u00b7 04 \u2013 MCP Guide
"},{"location":"05_development/04_mcp_guide/","title":"MCP Guide","text":"Doc-forge can export a machine-readable MCP bundle from a project's GSDFC docstrings and serve that bundle over the Model Context Protocol (MCP). The bundle is self-contained: readers can derive the full API reference \u2014 signatures, docstrings, and structure \u2014 for the documented project.
"},{"location":"05_development/04_mcp_guide/#building-the-bundle","title":"\ud83d\ude80 Building the bundle","text":"doc-forge build --mcp --module docforge\n
This writes structured JSON into docs/mcp/:
index.json \u2014 project metadata and module countnav.json \u2014 module list with docs://modules/{module} resource URIsmodules/{dotted.path}.json \u2014 per-module serialized documentation
"},{"location":"05_development/04_mcp_guide/#serving-the-bundle","title":"\ud83d\ude80 Serving the bundle","text":"doc-forge serve --mcp --module docforge\n
The MCPServer (in docforge/servers/mcp_server.py) exposes:
Resource Description docs://index Project metadata docs://nav Navigation structure docs://modules/{module} Individual module documentation The server also registers a single diagnostic tool, ping, and is read-only. Missing resources are returned as structured error dictionaries rather than exceptions. The default transport is streamable-http; stdio and sse are supported via MCPServer.run.
"},{"location":"05_development/04_mcp_guide/#bundle-contents","title":"\ud83d\udce6 Bundle contents","text":"Each module resource contains:
path \u2014 dotted module pathdocstring \u2014 the raw GSDFC module docstringobjects \u2014 a recursive mapping of public symbols with name, kind, path, signature, and docstring, plus nested members
Because the bundle is generated from docstrings, the quality of the bundle equals the quality of the project's GSDFC docstrings. For docforge itself, the GSDFC specification is carried in modules/docforge.json via the docforge/__init__.py package docstring, making the bundle self-documenting.
"},{"location":"05_development/04_mcp_guide/#related","title":"Related","text":" - 03 \u2013 GSDFC Guide \u00b7 05 \u2013 MkDocs Configs
"},{"location":"05_development/05_mkdocs_configs/","title":"MkDocs Configuration Model","text":"Each documentation kind (lib, api, wiki) is built by its own MkDocs site. A repo that documents kind {kind} carries a config at docs/mkdocs.{kind}.yml that sets docs_dir to the kind's source directory and site_dir to ../site/{kind}.
"},{"location":"05_development/05_mkdocs_configs/#file-wins","title":"\ud83d\udcc4 File wins","text":"docs/mkdocs.{kind}.yml is a repo-owned file, not a build byproduct:
- Absent \u2014
doc-forge build --{kind} materializes a copy from the packaged templates (see below) and then builds site/{kind}. - Present \u2014 the build uses the file verbatim. Edits to the theme, palette, plugins, markdown extensions, nav, or
site_dir are respected as-is. --refresh \u2014 force-regenerates the file from the templates, replacing any local changes.
Because a present file is never rewritten, rerunning a build is a no-op for versioned configs: the working tree stays clean.
"},{"location":"05_development/05_mkdocs_configs/#templates","title":"\ud83e\udde9 Templates","text":"The built-in defaults live in docforge/templates/:
File Role mkdocs.common.yml Shared theme + markdown extensions mkdocs.lib.yml mkdocstrings handler for library reference mkdocs.api.yml Swagger/OpenAPI plugins and API-side features mkdocs.wiki.yml Wiki look: horizontal navigation.tabs header, blue grey/teal palette, Roboto A per-kind config is generated by deep-merging the common template with the kind fragment, then filling in generation-time values (site_name, docs_dir, site_dir, nav, API site_description/site_author, and the theme icon from docforge.nav.yml). Pass --template <path> to replace the built-in templates entirely.
"},{"location":"05_development/05_mkdocs_configs/#supported-layouts","title":"\ud83c\udfd7\ufe0f Supported layouts","text":" - Per-kind config \u2014 the standard layout; each kind builds to
site/{kind} and is served under /<repo>/{kind}/. - Legacy root config \u2014 a repo with a single kind may instead author root
mkdocs.yml (for example mongo-ops, whose wiki uses docs_dir: docs/wiki). doc-forge never reads or writes root mkdocs.yml; the docs service maps the kind to the root site/ dir in this case.
Commit docs/mkdocs.{kind}.yml so served docs are reproducible from source.
"},{"location":"05_development/05_mkdocs_configs/#related","title":"Related","text":""}]}
\ No newline at end of file