🔨 docforge — Docstring-Driven Documentation Forge

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.

---

🚀 Key Features

• 🧪 GSDFC docstring extraction via Griffe
• 🧭 Auto-derived navigation for hand-written wiki pages
• 🗂 Independent MkDocs builds per kind (lib, api, wiki) into site/{kind}
• 🔌 Material MkDocs theming out of the box
• 📦 MCP structured documentation resources

---

📁 Documentation Structure

Section	Description
Overview	What docforge is and how it fits the pipeline
Architecture	Loaders, models, nav, renderers, CLI, servers
Conventions	GSDFC, .pyi stubs, and template conventions
Iterative Workflow	How a docs build runs end to end
Development	Environment setup and quality gates
Docstring Guide	How to write GSDFC-conformant docstrings
MCP Guide	Building, serving, and consuming the MCP bundle

---

🔗 Related Resources

• 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 — Wiki Authoring Guide (Aetoskia)
  
  This file instructs AI agents how to create, extend, and maintain the wiki
  (`docs/wiki/**`) for any Aetoskia repository. The reference implementation is
  `mongo-ops` — its wiki went through several revisions to reach the structure
  below and should be treated as the canonical example.
  
  ---
  
  ## 1. Doc model — know the two sources of truth
  
  Every repo keeps two distinct kinds of documentation that must **not** bleed
  into each other:
  
  | Kind              | Source                | Where                                    | Audience                           |
  |-------------------|-----------------------|------------------------------------------|------------------------------------|
  | **Wiki**          | Hand-written markdown | `docs/wiki/**`                           | Humans (how-to, examples, testing) |
  | **API reference** | Docstrings (GSDFC)    | Generated → `docs/lib/**`, `docs/mcp/**` | Consumers (exact contracts)        |
  
  Rules:
  
  - The wiki is written **for humans** — how-to guides, recipes, and testing
    patterns. It is never generated.
  - API contracts (signatures, parameter types, exact behavior) live in the
    docstrings and the machine-readable bundle under `docs/mcp/`. **Never**
    duplicate full API documentation in the wiki — link to the lib site instead.
  - If a page starts to drift into contract territory, cut it down to usage and
    point at `docs/lib/`.
  - This doc model is stated on every index page as a blockquote; keep it there:
    > **Doc model:** this wiki is written for humans — how‑to guides, examples,
    > and testing recipes. The authoritative API contracts live in the code
    > (docstrings) and the machine‑readable bundle under `docs/mcp/`.
  
  ---
  
  ## 2. Directory layout & file naming
  
  ```
  docs/wiki/
  ├── index.md                      # site Home
  ├── 01_overview.md
  ├── 02_components.md
  ├── 03_use_cases/                 # nested directory → nav group
  │   ├── 01_basic_crud.md
  │   ├── 02_custom_repo.md
  │   └── ...
  ├── 04_best_practices.md
  ├── 06_error_handling.md
  └── 07_testing_example.md
  ```
  
  - Location: `docs/wiki/` (hand-written only).
  - File names: `NN_snake_case_name.md` with a **zero-padded two-digit** numeric
    prefix. e.g. `01_overview.md`, `03_use_cases/07_caching.md`.
  - Top-level pages use `NN_name.md` directly. High-volume sections get their own
    directory, e.g. `03_use_cases/NN_name.md` (nav group "Use Cases").
  - **No frontmatter.** Every file opens directly with an H1 `# Title`.
  - Navigation labels are short human titles set explicitly in
    `docs/mkdocs.wiki.yml` (title case) — often **shorter** than the page H1.
    Example: nav label `Basic CRUD` vs page H1 `Use Case 1: Basic FastAPI CRUD API`.
    Never use the raw filename slug as the label.
  - Renumbering: prefixes order pages. When inserting a page, pick the next
    number in the relevant group (subgroup numbers stay grouped).
  
  ---
  
  ## 3. Navigation — `docs/mkdocs.wiki.yml` is the source of truth
  
  Every wiki page **must** be wired into the nav defined in
  `docs/mkdocs.wiki.yml`. If a page is not in the nav, it is orphaned.
  
  - The `nav:` block mirrors the directory tree; directories become nested
    groups.
  - When a section has many pages, group them **by theme** into nested
    subgroups. mongo-ops groups its use cases into:
    `Getting Started`, `Data & Queries`, `Caching`, `Population`,
    `Advanced Usage`.
  - Keep `index.md`'s **Documentation Structure** table in sync with the nav —
    it is the human-facing version of the same TOC. Every nav entry needs a row
    (or nested bullet group) there.
  - Nav label = human title (title case), not the filename slug.
  
  ---
  
  ## 4. Page anatomy
  
  ### 4.1 `index.md` (Home)
  
  ```
  # 🧩 <package> — <slogan>
  <one-paragraph pitch>
  
  > **Doc model:** …   (see §1)
  
  ---
  
  ## 🚀 Key Features         (bullet list, emoji per feature)
  ## 📦 Installation         (code blocks: internal PyPI, extras, local source)
  ## 📁 Documentation Structure   (table = TOC, mirrors nav exactly)
  ## 🔗 Related Resources    (bullets: source repo, internal PyPI, CI)
  ---
  © Aetoskia Internal — `<package>` <version>
  ```
  
  ### 4.2 Overview page (`01_*`)
  
  - Opens with `# Library Overview`, one sentence about what the library does,
    then a line stating the page builds the mental model.
  - Sections: `## 🏗️ Architecture` (ASCII diagram + numbered layer list),
    `## 🔄 Lifecycle Rules` (table: step / call / why),
    `## 🧭 Which … Should You Use?` (decision table).
  - Ends with `## ➡️ Read Next` (cross-links to the next pages to read).
  
  ### 4.3 Components page (`02_*`)
  
  - Validated reference for the public API surface — describes what each
    component is for and how the pieces wire together. Keep it usage-level;
    exact signatures belong in `docs/lib/`.
  - Anatomy: numbered sections, one per component (`## 1. MongoConnectionManager`,
    `## 2. BaseDocument`, …), with `### 8.1`-style sub-numbering for related
    types under a component (e.g. the cache layer's backend / stats / config /
    in-memory / redis implementations). Ends with `## Related`.
  
  ### 4.4 Use-case page (the most common)
  
  Standard anatomy, in this order:
  
  ```
  # Use Case N: <Human Title>
  
  **Scenario:** <one sentence: the problem this recipe solves>
  
  ---
  
  ## 📦 What's New?        (table: Component | Description — new API used here)
  ## 🚀 Example            (languaged code block, complete runnable-looking snippet)
  ## 💡 Tips               (bullets: gotchas, ordering, common mistakes)
  ## Related               (§5)
  ```
  
  ### 4.5 Deep-dive / worked-example page
  
  For intricate flows (population shapes, cache round-trips), use numbered
  depth-first sections and comparison tables:
  
  ```
  ## 1. <Write path>              (### 1a., ### 1b., … per sub-case)
  ## 2. <Read path>
  ## 3. <Round trip / tricky bit>
  ## 4. When to use which         (comparison table)
  ## Related
  ```
  
  ### 4.6 Best Practices page (`04_*`)
  
  - Flat themed `##` sections (e.g. Layering, Lifecycle, Data & Performance,
    Transactions & Errors, Testing), each a short list of numbered conventions.
  - Pure prose — no large code blocks.
  
  ### 4.7 Error Handling (`06_*`) / Testing pages
  
  - **Error Handling:** an exceptions table (`Exception | Source | Meaning / fix`),
    a `> ` note on which failures are by design, a `## 🚀 FastAPI Mapping Example`
    code block, then `## 💡 Tips` bullets, then `## Related`.
  - **Testing example (`07_*`):** `## 🚀 Mock-Based Quickstart` (focused code
    block), `## 💡 Notes` tip list, `## Related`.
  
  Common to all pages: no frontmatter, `---` between every major section, and a
  `## Related` (or variant) footer as the **last** section.
  
  ---
  
  ## 5. The `## Related` footer
  
  Every page ends with a cross-link footer. Rules:
  
  - Always the **last** section, always preceded by a `---`.
  - Standard heading: `## Related` (no emoji).
  - One bullet line; links separated by ` · ` (middle dot plus spaces).
  - Link label format: `[NN – Title](relative_path)` — en-dash, page number, title.
  - Paths are **relative**: same directory → `02_custom_repo.md`; parent →
    `../01_overview.md`; child → `03_use_cases/01_basic_crud.md`.
  - Link order follows nav order (each `Related` points to related next/sibling
    pages, plus the overview/components anchor).
  
  Examples (from mongo-ops):
  
  ```
  ## Related
  - [02 – Custom repository](02_custom_repo.md) · [04 – Pagination](04_pagination.md) · [Overview](../01_overview.md)
  ```
  
  Variants:
  
  - `## ➡️ Read Next` — used on the overview page (linear reading order).
  - `## 🔗 Related Resources` — only on `index.md`, one bullet per external resource.
  
  ---
  
  ## 6. Tone & formatting rules
  
  - **Written for humans**: short sentences, concrete examples, plain words.
  - Emoji-prefixed H2 headings for recognizable section types
    (`📦 What's New?`, `🚀 Example`, `💡 Tips`, `🚀 Key Features`).
  - `---` horizontal rule between every major section.
  - Code blocks always declare a language (```python, ```bash, etc.).
  - Use tables for comparisons and structured decisions; bullets for lists;
    ASCII diagrams for architecture.
  - Bold key terms inline. Use `inline code` for symbols/APIs.
  - Keep pages focused: one recipe/purpose per page. If a page balloons past
    ~10 KB, split it (add a numbered deep-dive page instead).
  - Match tone of existing pages in the repo before writing new ones.
  
  ---
  
  ## 7. Build & verify workflow
  
  After creating or editing wiki pages:
  
  ```bash
  # 1. Build the wiki (from the repo root)
  doc-forge build --wiki                       # wiki only
  doc-forge build --wiki --mkdocs --module <pkg>   # wiki + lib together
  
  # 2. Preview locally
  doc-forge serve --wiki
  
  # 3. Collect into the hub (run from the docs/ service repo)
  python collect.py                            # copies site, regenerates index + nginx.conf
  python collect.py --dry-run                  # preview without writing
  ```
  
  Verification checklist:
  
  - `doc-forge build --wiki` completes with no warnings about missing files.
  - Every new page is present in `docs/mkdocs.wiki.yml` **and** in the index
    Documentation Structure table.
  - Every page ends with a `## Related` block and no dead links (paths resolve).
  - After `collect.py`: the hub card links to both `/wiki/` and `/lib/` and the
    pages render (spot-check with the served site).
  - If code/docstrings changed (no change when wiki-only), run the repo gates:
    `black`, `ruff`, `mypy`, `pytest`.
  
  ---
  
  ## 8. Before/after checklist
  
  **Before creating a page:**
  
  - [ ] Confirm it is genuinely wiki material (how-to) and not API contract.
  - [ ] Find the right filename (`NN_snake_case.md`) and directory for its theme.
  - [ ] Outline the sections per §4 anatomy that fits the content.
  
  **After creating/editing a page:**
  
  - [ ] Page wired into `docs/mkdocs.wiki.yml` nav (themed subgroup if needed).
  - [ ] `index.md` Documentation Structure table updated.
  - [ ] `## Related` footer present, relative links, nav order.
  - [ ] `---` separators consistent; no frontmatter; emoji headings where apt.
  - [ ] Build passes; collect run; hub shows `/wiki/` + `/lib/` links.
  - [ ] No orphaned files, no dead links.
  

---

© Aetoskia Internal