diff --git a/doc-forge/wiki/index.html b/doc-forge/wiki/index.html
index 5429634..afda55e 100644
--- a/doc-forge/wiki/index.html
+++ b/doc-forge/wiki/index.html
@@ -790,7 +790,8 @@ and testing recipes. The authoritative API contracts live in the code
- 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
+ - Wiki Kind: hand-written content lives in
docs/wiki/; use the prompt in the
+ wiki-related resource below
1
2
3
@@ -1051,267 +1052,283 @@ and testing recipes. The authoritative API contracts live in the code
258
259
260
-261 | | # 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
+(`docs/wiki/**`) for any Aetoskia repository.
+
+> **Workflow:** this prompt covers **phase 2 only**. Phase 1 — writing GSDFC docstrings
+> (plus `.pyi` stubs and `py.typed`) — is done by the agent using the doc-forge MCP
+> bundle: `doc://modules/docforge` carries the full GSDFC spec. Write the wiki only
+> after docstrings exist and `doc-forge build --mcp --module <pkg>` produced the
+> repo's own bundle.
-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
+---
+
+## 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/`.
-```
-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
+---
+
+## 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).
-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
+---
+
+## 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.1 `index.md` (Home)
+---
-```
-# 🧩 <package> — <slogan>
-<one-paragraph pitch>
+## 4. Page anatomy
+
+### 4.1 `index.md` (Home)
-> **Doc model:** … (see §1)
-
----
+```
+# 🧩 <package> — <slogan>
+<one-paragraph pitch>
-## 🚀 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:
+> **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`.
-```
-# Use Case N: <Human Title>
-
-**Scenario:** <one sentence: the problem this recipe solves>
-
----
+### 4.4 Use-case page (the most common)
+
+Standard anatomy, in this order:
+
+```
+# Use Case N: <Human Title>
-## 📦 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.
+**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_*`)
-### 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
+- 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.
-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
+## 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.
-- **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
+---
+
+## 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.
+- Ground every `## 🚀 Example`, `💡 Tips`, and `📦 What's New?` row in the
+ library's actual source, tests, and its `docs/mcp` bundle — never invent
+ APIs or behavior. Signatures and exceptions come from the code; gotchas
+ come from the tests.
+
+---
+
+## 7. Build & verify workflow
+
+After creating or editing wiki pages:
-# 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
-```
+```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
-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.
+# 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`.
+
+---
-**After creating/editing a page:**
+## 8. Before/after checklist
-- [ ] 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.
+**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.
|
diff --git a/doc-forge/wiki/search/search_index.json b/doc-forge/wiki/search/search_index.json
index 88b0ca9..89a44aa 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":"\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
+{"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/; use the prompt in the wiki-related resource 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.\n\n> **Workflow:** this prompt covers **phase 2 only**. Phase 1 \u2014 writing GSDFC docstrings\n> (plus `.pyi` stubs and `py.typed`) \u2014 is done by the agent using the doc-forge MCP\n> bundle: `doc://modules/docforge` carries the full GSDFC spec. Write the wiki only\n> after docstrings exist and `doc-forge build --mcp --module <pkg>` produced the\n> repo's own bundle.\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- Ground every `## \ud83d\ude80 Example`, `\ud83d\udca1 Tips`, and `\ud83d\udce6 What's New?` row in the\n library's actual source, tests, and its `docs/mcp` bundle \u2014 never invent\n APIs or behavior. Signatures and exceptions come from the code; gotchas\n come from the tests.\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. - Every distributable package ships a
py.typed marker so type checkers consume the authored signatures instead of Any.
"},{"location":"03_conventions/#pyi-stubs-and-pytyped","title":".pyi stubs and py.typed","text":"Every module ships a matching .pyi stub kept in sync with the .py implementation. When signatures change, update both files. Packages expose a py.typed marker so consumers and type checkers use the authored signatures.
"},{"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
diff --git a/doc-forge/wiki/sitemap.xml.gz b/doc-forge/wiki/sitemap.xml.gz
index 2984a5c..0146525 100644
Binary files a/doc-forge/wiki/sitemap.xml.gz and b/doc-forge/wiki/sitemap.xml.gz differ
diff --git a/mcp/doc-forge/modules/docforge.cli.commands.json b/mcp/doc-forge/modules/docforge.cli.commands.json
index dcec1a1..79af154 100644
--- a/mcp/doc-forge/modules/docforge.cli.commands.json
+++ b/mcp/doc-forge/modules/docforge.cli.commands.json
@@ -557,21 +557,21 @@
"name": "build",
"kind": "function",
"path": "docforge.cli.commands.build",
- "signature": "",
- "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
+ "signature": "",
+ "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n - Configuration files are generated only when absent; an existing\n `docs/mkdocs.{kind}.yml` is used as-is. Pass `--refresh` to\n rebaseline it from the templates.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n refresh (bool):\n Regenerate ``docs/mkdocs.{kind}.yml`` from templates even when\n it already exists. By default, existing configs are used as-is.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
},
"serve": {
"name": "serve",
"kind": "function",
"path": "docforge.cli.commands.serve",
- "signature": "",
+ "signature": "",
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing a site, or\n- An MCP server exposing structured documentation resources\n\nThe kind flags (`--lib`, `--api`, `--wiki`) select the generated\nper-kind config (`docs/mkdocs.{kind}.yml`); `--mkdocs` serves the config\npassed via `--mkdocs-yml`.\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site from ``--mkdocs-yml``.\n\n lib (bool):\n Serve the lib MkDocs site.\n\n api (bool):\n Serve the API MkDocs site.\n\n wiki (bool):\n Serve the wiki MkDocs site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided."
},
"tree": {
"name": "tree",
"kind": "function",
"path": "docforge.cli.commands.tree",
- "signature": "",
+ "signature": "",
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (str | None):\n Optional name to display as the project root."
},
"Group": {
diff --git a/mcp/doc-forge/modules/docforge.cli.json b/mcp/doc-forge/modules/docforge.cli.json
index 75cc4e9..be6964a 100644
--- a/mcp/doc-forge/modules/docforge.cli.json
+++ b/mcp/doc-forge/modules/docforge.cli.json
@@ -689,21 +689,21 @@
"name": "build",
"kind": "function",
"path": "docforge.cli.commands.build",
- "signature": "",
- "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
+ "signature": "",
+ "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n - Configuration files are generated only when absent; an existing\n `docs/mkdocs.{kind}.yml` is used as-is. Pass `--refresh` to\n rebaseline it from the templates.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n refresh (bool):\n Regenerate ``docs/mkdocs.{kind}.yml`` from templates even when\n it already exists. By default, existing configs are used as-is.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
},
"serve": {
"name": "serve",
"kind": "function",
"path": "docforge.cli.commands.serve",
- "signature": "",
+ "signature": "",
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing a site, or\n- An MCP server exposing structured documentation resources\n\nThe kind flags (`--lib`, `--api`, `--wiki`) select the generated\nper-kind config (`docs/mkdocs.{kind}.yml`); `--mkdocs` serves the config\npassed via `--mkdocs-yml`.\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site from ``--mkdocs-yml``.\n\n lib (bool):\n Serve the lib MkDocs site.\n\n api (bool):\n Serve the API MkDocs site.\n\n wiki (bool):\n Serve the wiki MkDocs site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided."
},
"tree": {
"name": "tree",
"kind": "function",
"path": "docforge.cli.commands.tree",
- "signature": "",
+ "signature": "",
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (str | None):\n Optional name to display as the project root."
},
"Group": {
diff --git a/mcp/doc-forge/modules/docforge.json b/mcp/doc-forge/modules/docforge.json
index 17b68ad..99ac7a0 100644
--- a/mcp/doc-forge/modules/docforge.json
+++ b/mcp/doc-forge/modules/docforge.json
@@ -2,7 +2,7 @@
"module": "docforge",
"content": {
"path": "docforge",
- "docstring": "# Summary\n\nRenderer-agnostic Python documentation compiler that converts Python docstrings\ninto structured documentation for both humans (MkDocs) and machines (MCP / AI agents).\n\n`doc-forge` statically analyzes source code, builds a semantic model of modules,\nclasses, functions, and attributes, and renders that model into documentation\noutputs without executing user code.\n\n---\n\n# Installation\n\nInstall using pip:\n\n```bash\npip install doc-forge\n```\n\n---\n\n# CLI usage\n\nEach site kind (`lib`, `api`, `wiki`) is built independently into `site/{kind}`.\n\n## Build the library reference from a Python package:\n\n```bash\ndoc-forge build --mkdocs --module my_package\n```\n\n## Build the API reference from an OpenAPI spec:\n\n```bash\ndoc-forge build --api --openapi-spec spec.json\n```\n\n## Build the hand-written wiki:\n\n```bash\ndoc-forge build --wiki --site-name my_package\n```\n\n## Generate MCP JSON documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\n## Build several kinds in one pass:\n\n```bash\ndoc-forge build --mcp --mkdocs --wiki --module my_package\n```\n\nEach enabled kind gets its own MkDocs config (`docs/mkdocs.{lib,api,wiki}.yml`)\nand its own site under `site/`.\n\n## Serve a site locally:\n\n```bash\ndoc-forge serve --wiki # preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n```\n\n## Serve MCP locally:\n\n```bash\ndoc-forge serve --mcp --module my_package\n```\n\n---\n\n# Core concepts\n\n## Loader\nExtracts symbols, signatures, and docstrings using static analysis.\n\n## Semantic model\nStructured, renderer-agnostic representation of the API.\n\n## Renderer\nConverts the semantic model into output formats such as MkDocs or MCP JSON.\n\n## Symbol\nAny documentable object\n\n- module\n- class\n- function\n- method\n- property\n- attribute\n\n---\n\n# Architecture\n\n`doc-forge` follows a compiler architecture:\n\n## Front-end:\n\nStatic analysis of modules, classes, functions, type hints, and docstrings.\n\n## Middle-end:\n\nBuilds a semantic model describing symbols and relationships.\n\n## Back-end:\n\nRenders documentation using interchangeable renderers.\n\nThis architecture ensures deterministic documentation generation.\n\n---\n\n# Rendering pipeline\n\nTypical flow:\n\n Python package\n |\n Loader (static analysis)\n |\n Semantic model\n |\n Renderer\n |\n MkDocs site or MCP JSON\n\n---\n\n# Google-Styled Doc-Forge Convention (GSDFC)\n\nGSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.\n\n- Docstrings are the single source of truth.\n- `doc-forge` compiles docstrings but does not generate documentation content.\n- Documentation follows the Python import hierarchy.\n- Every public symbol should have a complete and accurate docstring.\n\n---\n\n## General rules\n\n- Use **Markdown headings** at package and module level.\n- Use **Google-style structured sections** at class, function, and method level.\n- Use type hints in signatures.\n- Use parenthesized types in prose entries (`name (Type):`) that match the\n signature types. This keeps docstrings self-contained and machine-parseable.\n- Write summaries in imperative form.\n- Sections are separated by `---`\n\n---\n\n# Notes subsection grouping\n\nGroup related information using labeled subsections.\n\nExample:\n\n Notes:\n **Guarantees:**\n\n - deterministic behavior\n\n **Lifecycle:**\n\n - created during initialization\n - reused across executions\n\n **Thread safety:**\n\n - safe for concurrent reads\n\n---\n\n# Example formatting\n\n- Use indentation for examples.\n- Indent section contents using four spaces.\n- Use code blocks for example code.\n\nExample:\n Single example:\n\n Example:\n\n ```python\n foo = Foo(\"example\")\n process(foo, multiplier=2)\n ```\n\n Multiple examples:\n\n Example:\n Create foo:\n\n ```python\n foo = Foo(\"example\")\n ```\n\n Run engine:\n\n ```python\n engine = BarEngine([foo])\n engine.run()\n ```\n\nAvoid fenced code blocks inside argument descriptions and other prose lines.\n\nInside `Example:` sections, fenced `python` code blocks are allowed and must be\nindented four spaces, matching the examples below.\n\n---\n\n# Separator rules\n\nUse horizontal separators only at docstring root level to separate sections:\n\n```markdown\n---\n```\n\nAllowed locations:\n\n- package docstrings\n- module docstrings\n- major documentation sections\n\nDo not use separators inside code sections.\n\n---\n\n# Package docstrings\n\nPackage docstrings act as the documentation home page.\n\nRecommended sections:\n\n # Summary\n # Installation\n # Quick start\n # CLI usage\n # Core concepts\n # Architecture\n # Rendering pipeline\n # Examples\n # Notes\n\nExample:\n Package Doc String:\n\n '''\n # Summary\n\n Foo-bar processing framework.\n\n Provides tools for defining Foo objects and executing Bar pipelines.\n\n ---\n\n # Installation\n\n ```bash\n pip install foo-bar\n ```\n\n ---\n\n # Quick start\n\n ```python\n from foobar import Foo, BarEngine\n\n foo = Foo(\"example\")\n engine = BarEngine([foo])\n\n result = engine.run()\n ```\n\n ---\n '''\n\n---\n\n# Module docstrings\n\nModule docstrings describe a subsystem.\n\nRecommended sections:\n\n # Summary\n # Examples\n # Notes\n\nExample:\n Module Doc String:\n\n '''\n # Summary\n\n Foo execution subsystem.\n\n Provides utilities for executing Foo objects through Bar stages.\n\n ---\n\n Example:\n\n ```python\n from foobar.engine import BarEngine\n from foobar.foo import Foo\n\n foo = Foo(\"example\")\n\n engine = BarEngine([foo])\n engine.run()\n ```\n\n ---\n '''\n\n---\n\n# Class docstrings\n\nClass docstrings define object responsibility, lifecycle, and attributes.\n\nRecommended sections:\n\n Attributes:\n Notes:\n Example:\n Raises:\n\nExample:\n Simple Foo:\n\n ```python\n class Foo:\n '''\n Represents a unit of work.\n\n Attributes:\n name (str):\n Identifier of the foo instance.\n\n value (int):\n Numeric value associated with foo.\n\n Notes:\n Guarantees:\n\n - instances are immutable after creation\n\n Lifecycle:\n\n - create instance\n - pass to processing engine\n\n Example:\n Create and inspect a Foo:\n\n ```python\n foo = Foo(\"example\", value=42)\n print(foo.name)\n ```\n '''\n ```\n\n Complex Bar:\n\n ```python\n class BarEngine:\n '''\n Executes Foo objects through Bar stages.\n\n Attributes:\n foos (tuple[Foo, ...]):\n Foo instances managed by the engine.\n\n Notes:\n Guarantees:\n\n - deterministic execution order\n\n Example:\n Run engine:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n ```\n\n---\n\n# Function and method docstrings\n\nFunction docstrings define API contracts.\n\nRecommended sections:\n\n Args:\n Returns:\n Raises:\n Yields:\n Notes:\n Example:\n\nExample:\n Simple process method:\n\n ```python\n def process(foo: Foo, multiplier: int) -> int:\n '''\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 Notes:\n Guarantees:\n\n - foo is not modified\n\n Example:\n Process foo:\n\n ```python\n foo = Foo(\"example\", value=10)\n\n result = process(foo, multiplier=2)\n print(result)\n ```\n '''\n ```\n\n Multiple Examples:\n\n ```python\n def combine(foo_a: Foo, foo_b: Foo) -> Foo:\n '''\n Combine two Foo instances.\n\n Args:\n foo_a (Foo):\n First foo.\n\n foo_b (Foo):\n Second foo.\n\n Returns:\n Foo:\n Combined foo.\n\n Example:\n Basic usage:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n combined = combine(foo1, foo2)\n ```\n\n Pipeline usage:\n\n ```python\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n ```\n\n---\n\n# Property docstrings\n\nProperties must document return values.\n\nExample:\n Property Doc String:\n\n ```python\n @property\n def foos(self) -> tuple[Foo, ...]:\n '''\n Return contained Foo instances.\n\n Returns:\n tuple[Foo, ...]:\n Stored foo objects.\n\n Example:\n ```python\n container = FooContainer()\n\n foos = container.foos\n ```\n '''\n ```\n\n---\n\n# Attribute documentation\n\nDocument attributes in class docstrings using `Attributes:`.\n\nExample:\n Attribute Doc String:\n\n ```python\n '''\n Represents a processing stage.\n\n Attributes:\n id (str):\n Unique identifier.\n\n enabled (bool):\n Whether the stage is active.\n '''\n ```\n\n---\n\n# Parsing guarantees\n\nGSDFC ensures doc-forge can deterministically extract:\n\n- symbol kind (module, class, function, property, attribute)\n- symbol name\n- parameters\n- return values\n- attributes\n- examples\n- structured Notes subsections\n\nThis enables:\n\n- reliable MkDocs rendering\n- deterministic MCP export\n- accurate AI semantic interpretation\n\n---\n\nNotes:\n - doc-forge never executes analyzed modules.\n - Documentation is generated entirely through static analysis.",
+ "docstring": "# Summary\n\nRenderer-agnostic Python documentation compiler that converts Python docstrings\ninto structured documentation for both humans (MkDocs) and machines (MCP / AI agents).\n\n`doc-forge` statically analyzes source code, builds a semantic model of modules,\nclasses, functions, and attributes, and renders that model into documentation\noutputs without executing user code.\n\n---\n\n# Installation\n\nInstall using pip:\n\n```bash\npip install doc-forge\n```\n\n---\n\n# CLI usage\n\nEach site kind (`lib`, `api`, `wiki`) is built independently into `site/{kind}`.\n\n## Build the library reference from a Python package:\n\n```bash\ndoc-forge build --mkdocs --module my_package\n```\n\n## Build the API reference from an OpenAPI spec:\n\n```bash\ndoc-forge build --api --openapi-spec spec.json\n```\n\n## Build the hand-written wiki:\n\n```bash\ndoc-forge build --wiki --site-name my_package\n```\n\n## Generate MCP JSON documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\n## Build several kinds in one pass:\n\n```bash\ndoc-forge build --mcp --mkdocs --wiki --module my_package\n```\n\nEach enabled kind gets its own MkDocs config (`docs/mkdocs.{lib,api,wiki}.yml`)\nand its own site under `site/`.\n\n## Serve a site locally:\n\n```bash\ndoc-forge serve --wiki # preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n```\n\n## Serve MCP locally:\n\n```bash\ndoc-forge serve --mcp --module my_package\n```\n\n---\n\n# Core concepts\n\n## Loader\nExtracts symbols, signatures, and docstrings using static analysis.\n\n## Semantic model\nStructured, renderer-agnostic representation of the API.\n\n## Renderer\nConverts the semantic model into output formats such as MkDocs or MCP JSON.\n\n## Symbol\nAny documentable object\n\n- module\n- class\n- function\n- method\n- property\n- attribute\n\n---\n\n# Architecture\n\n`doc-forge` follows a compiler architecture:\n\n## Front-end:\n\nStatic analysis of modules, classes, functions, type hints, and docstrings.\n\n## Middle-end:\n\nBuilds a semantic model describing symbols and relationships.\n\n## Back-end:\n\nRenders documentation using interchangeable renderers.\n\nThis architecture ensures deterministic documentation generation.\n\n---\n\n# Rendering pipeline\n\nTypical flow:\n\n Python package\n |\n Loader (static analysis)\n |\n Semantic model\n |\n Renderer\n |\n MkDocs site or MCP JSON\n\n---\n\n# Google-Styled Doc-Forge Convention (GSDFC)\n\nGSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.\n\n- Docstrings are the single source of truth.\n- `doc-forge` compiles docstrings but does not generate documentation content.\n- Documentation follows the Python import hierarchy.\n- Every public symbol should have a complete and accurate docstring.\n\n---\n\n## General rules\n\n- Use **Markdown headings** at package and module level.\n- Use **Google-style structured sections** at class, function, and method level.\n- Use type hints in signatures.\n- Use parenthesized types in prose entries (`name (Type):`) that match the\n signature types. This keeps docstrings self-contained and machine-parseable.\n- Write summaries in imperative form.\n- Sections are separated by `---`\n\n---\n\n# Notes subsection grouping\n\nGroup related information using labeled subsections.\n\nExample:\n\n Notes:\n **Guarantees:**\n\n - deterministic behavior\n\n **Lifecycle:**\n\n - created during initialization\n - reused across executions\n\n **Thread safety:**\n\n - safe for concurrent reads\n\n---\n\n# Example formatting\n\n- Use indentation for examples.\n- Indent section contents using four spaces.\n- Use code blocks for example code.\n\nExample:\n Single example:\n\n Example:\n\n ```python\n foo = Foo(\"example\")\n process(foo, multiplier=2)\n ```\n\n Multiple examples:\n\n Example:\n Create foo:\n\n ```python\n foo = Foo(\"example\")\n ```\n\n Run engine:\n\n ```python\n engine = BarEngine([foo])\n engine.run()\n ```\n\nAvoid fenced code blocks inside argument descriptions and other prose lines.\n\nInside `Example:` sections, fenced `python` code blocks are allowed and must be\nindented four spaces, matching the examples below.\n\n---\n\n# Separator rules\n\nUse horizontal separators only at docstring root level to separate sections:\n\n```markdown\n---\n```\n\nAllowed locations:\n\n- package docstrings\n- module docstrings\n- major documentation sections\n\nDo not use separators inside code sections.\n\n---\n\n# Package docstrings\n\nPackage docstrings act as the documentation home page.\n\nRecommended sections:\n\n # Summary\n # Installation\n # Quick start\n # CLI usage\n # Core concepts\n # Architecture\n # Rendering pipeline\n # Examples\n # Notes\n\nExample:\n Package Doc String:\n\n '''\n # Summary\n\n Foo-bar processing framework.\n\n Provides tools for defining Foo objects and executing Bar pipelines.\n\n ---\n\n # Installation\n\n ```bash\n pip install foo-bar\n ```\n\n ---\n\n # Quick start\n\n ```python\n from foobar import Foo, BarEngine\n\n foo = Foo(\"example\")\n engine = BarEngine([foo])\n\n result = engine.run()\n ```\n\n ---\n '''\n\n---\n\n# Module docstrings\n\nModule docstrings describe a subsystem.\n\nRecommended sections:\n\n # Summary\n # Examples\n # Notes\n\nExample:\n Module Doc String:\n\n '''\n # Summary\n\n Foo execution subsystem.\n\n Provides utilities for executing Foo objects through Bar stages.\n\n ---\n\n Example:\n\n ```python\n from foobar.engine import BarEngine\n from foobar.foo import Foo\n\n foo = Foo(\"example\")\n\n engine = BarEngine([foo])\n engine.run()\n ```\n\n ---\n '''\n\n---\n\n# Class docstrings\n\nClass docstrings define object responsibility, lifecycle, and attributes.\n\nRecommended sections:\n\n Attributes:\n Notes:\n Example:\n Raises:\n\nExample:\n Simple Foo:\n\n ```python\n class Foo:\n '''\n Represents a unit of work.\n\n Attributes:\n name (str):\n Identifier of the foo instance.\n\n value (int):\n Numeric value associated with foo.\n\n Notes:\n Guarantees:\n\n - instances are immutable after creation\n\n Lifecycle:\n\n - create instance\n - pass to processing engine\n\n Example:\n Create and inspect a Foo:\n\n ```python\n foo = Foo(\"example\", value=42)\n print(foo.name)\n ```\n '''\n ```\n\n Complex Bar:\n\n ```python\n class BarEngine:\n '''\n Executes Foo objects through Bar stages.\n\n Attributes:\n foos (tuple[Foo, ...]):\n Foo instances managed by the engine.\n\n Notes:\n Guarantees:\n\n - deterministic execution order\n\n Example:\n Run engine:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n ```\n\n---\n\n# Function and method docstrings\n\nFunction docstrings define API contracts.\n\nRecommended sections:\n\n Args:\n Returns:\n Raises:\n Yields:\n Notes:\n Example:\n\nExample:\n Simple process method:\n\n ```python\n def process(foo: Foo, multiplier: int) -> int:\n '''\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 Notes:\n Guarantees:\n\n - foo is not modified\n\n Example:\n Process foo:\n\n ```python\n foo = Foo(\"example\", value=10)\n\n result = process(foo, multiplier=2)\n print(result)\n ```\n '''\n ```\n\n Multiple Examples:\n\n ```python\n def combine(foo_a: Foo, foo_b: Foo) -> Foo:\n '''\n Combine two Foo instances.\n\n Args:\n foo_a (Foo):\n First foo.\n\n foo_b (Foo):\n Second foo.\n\n Returns:\n Foo:\n Combined foo.\n\n Example:\n Basic usage:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n combined = combine(foo1, foo2)\n ```\n\n Pipeline usage:\n\n ```python\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n ```\n\n---\n\n# Property docstrings\n\nProperties must document return values.\n\nExample:\n Property Doc String:\n\n ```python\n @property\n def foos(self) -> tuple[Foo, ...]:\n '''\n Return contained Foo instances.\n\n Returns:\n tuple[Foo, ...]:\n Stored foo objects.\n\n Example:\n ```python\n container = FooContainer()\n\n foos = container.foos\n ```\n '''\n ```\n\n---\n\n# Attribute documentation\n\nDocument attributes in class docstrings using `Attributes:`.\n\nExample:\n Attribute Doc String:\n\n ```python\n '''\n Represents a processing stage.\n\n Attributes:\n id (str):\n Unique identifier.\n\n enabled (bool):\n Whether the stage is active.\n '''\n ```\n\n---\n\n# Type parity (`.pyi` stubs and `py.typed`)\n\nDocumented APIs ship matching type information:\n\n- Each `.py` module has a synchronized `.pyi` stub in the same package.\n- Packages expose a `py.typed` marker so type checkers (and consumers)\n use the authored signatures instead of `Any`.\n- When signatures change, update the `.py` implementation and its `.pyi`\n stub together.\n- Doc-forge documents the docstrings in `.py`; the `.pyi` stub is the\n machine-consumable signature surface.\n\n---\n\n# Parsing guarantees\n\nGSDFC ensures doc-forge can deterministically extract:\n\n- symbol kind (module, class, function, property, attribute)\n- symbol name\n- parameters\n- return values\n- attributes\n- examples\n- structured Notes subsections\n\nThis enables:\n\n- reliable MkDocs rendering\n- deterministic MCP export\n- accurate AI semantic interpretation\n\n---\n\nNotes:\n - doc-forge never executes analyzed modules.\n - Documentation is generated entirely through static analysis.",
"objects": {
"GriffeLoader": {
"name": "GriffeLoader",
@@ -802,21 +802,21 @@
"name": "build",
"kind": "function",
"path": "docforge.cli.commands.build",
- "signature": "",
- "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
+ "signature": "",
+ "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n - Configuration files are generated only when absent; an existing\n `docs/mkdocs.{kind}.yml` is used as-is. Pass `--refresh` to\n rebaseline it from the templates.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n refresh (bool):\n Regenerate ``docs/mkdocs.{kind}.yml`` from templates even when\n it already exists. By default, existing configs are used as-is.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
},
"serve": {
"name": "serve",
"kind": "function",
"path": "docforge.cli.commands.serve",
- "signature": "",
+ "signature": "",
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing a site, or\n- An MCP server exposing structured documentation resources\n\nThe kind flags (`--lib`, `--api`, `--wiki`) select the generated\nper-kind config (`docs/mkdocs.{kind}.yml`); `--mkdocs` serves the config\npassed via `--mkdocs-yml`.\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site from ``--mkdocs-yml``.\n\n lib (bool):\n Serve the lib MkDocs site.\n\n api (bool):\n Serve the API MkDocs site.\n\n wiki (bool):\n Serve the wiki MkDocs site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided."
},
"tree": {
"name": "tree",
"kind": "function",
"path": "docforge.cli.commands.tree",
- "signature": "",
+ "signature": "",
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (str | None):\n Optional name to display as the project root."
},
"Group": {