# 🔨 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](01_overview.md)                   | What docforge is and how it fits the pipeline      |
| [Architecture](02_architecture.md)           | Loaders, models, nav, renderers, CLI, servers     |
| [Conventions](03_conventions.md)             | GSDFC, `.pyi` stubs, and template conventions      |
| [Iterative Workflow](04_iterative_workflow.md) | How a docs build runs end to end                  |
| [Development](05_development/01_environment.md) | Environment setup and quality gates              |
| [Docstring Guide](05_development/03_gsdfc_guide.md) | How to write GSDFC-conformant docstrings        |
| [MCP Guide](05_development/04_mcp_guide.md)  | 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
````markdown
# AGENTS.md — Wiki Authoring Guide (Aetoskia)

This file instructs AI agents how to create, extend, and maintain the wiki
(`docs/wiki/**`) for any Aetoskia repository. The reference implementation is
`mongo-ops` — its wiki went through several revisions to reach the structure
below and should be treated as the canonical example.

---

## 1. Doc model — know the two sources of truth

Every repo keeps two distinct kinds of documentation that must **not** bleed
into each other:

| Kind              | Source                | Where                                    | Audience                           |
|-------------------|-----------------------|------------------------------------------|------------------------------------|
| **Wiki**          | Hand-written markdown | `docs/wiki/**`                           | Humans (how-to, examples, testing) |
| **API reference** | Docstrings (GSDFC)    | Generated → `docs/lib/**`, `docs/mcp/**` | Consumers (exact contracts)        |

Rules:

- The wiki is written **for humans** — how-to guides, recipes, and testing
  patterns. It is never generated.
- API contracts (signatures, parameter types, exact behavior) live in the
  docstrings and the machine-readable bundle under `docs/mcp/`. **Never**
  duplicate full API documentation in the wiki — link to the lib site instead.
- If a page starts to drift into contract territory, cut it down to usage and
  point at `docs/lib/`.
- This doc model is stated on every index page as a blockquote; keep it there:
  > **Doc model:** this wiki is written for humans — how‑to guides, examples,
  > and testing recipes. The authoritative API contracts live in the code
  > (docstrings) and the machine‑readable bundle under `docs/mcp/`.

---

## 2. Directory layout & file naming

```
docs/wiki/
├── index.md                      # site Home
├── 01_overview.md
├── 02_components.md
├── 03_use_cases/                 # nested directory → nav group
│   ├── 01_basic_crud.md
│   ├── 02_custom_repo.md
│   └── ...
├── 04_best_practices.md
├── 06_error_handling.md
└── 07_testing_example.md
```

- Location: `docs/wiki/` (hand-written only).
- File names: `NN_snake_case_name.md` with a **zero-padded two-digit** numeric
  prefix. e.g. `01_overview.md`, `03_use_cases/07_caching.md`.
- Top-level pages use `NN_name.md` directly. High-volume sections get their own
  directory, e.g. `03_use_cases/NN_name.md` (nav group "Use Cases").
- **No frontmatter.** Every file opens directly with an H1 `# Title`.
- Navigation labels are short human titles set explicitly in
  `docs/mkdocs.wiki.yml` (title case) — often **shorter** than the page H1.
  Example: nav label `Basic CRUD` vs page H1 `Use Case 1: Basic FastAPI CRUD API`.
  Never use the raw filename slug as the label.
- Renumbering: prefixes order pages. When inserting a page, pick the next
  number in the relevant group (subgroup numbers stay grouped).

---

## 3. Navigation — `docs/mkdocs.wiki.yml` is the source of truth

Every wiki page **must** be wired into the nav defined in
`docs/mkdocs.wiki.yml`. If a page is not in the nav, it is orphaned.

- The `nav:` block mirrors the directory tree; directories become nested
  groups.
- When a section has many pages, group them **by theme** into nested
  subgroups. mongo-ops groups its use cases into:
  `Getting Started`, `Data & Queries`, `Caching`, `Population`,
  `Advanced Usage`.
- Keep `index.md`'s **Documentation Structure** table in sync with the nav —
  it is the human-facing version of the same TOC. Every nav entry needs a row
  (or nested bullet group) there.
- Nav label = human title (title case), not the filename slug.

---

## 4. Page anatomy

### 4.1 `index.md` (Home)

```
# 🧩 <package> — <slogan>
<one-paragraph pitch>

> **Doc model:** …   (see §1)

---

## 🚀 Key Features         (bullet list, emoji per feature)
## 📦 Installation         (code blocks: internal PyPI, extras, local source)
## 📁 Documentation Structure   (table = TOC, mirrors nav exactly)
## 🔗 Related Resources    (bullets: source repo, internal PyPI, CI)
---
© Aetoskia Internal — `<package>` <version>
```

### 4.2 Overview page (`01_*`)

- Opens with `# Library Overview`, one sentence about what the library does,
  then a line stating the page builds the mental model.
- Sections: `## 🏗️ Architecture` (ASCII diagram + numbered layer list),
  `## 🔄 Lifecycle Rules` (table: step / call / why),
  `## 🧭 Which … Should You Use?` (decision table).
- Ends with `## ➡️ Read Next` (cross-links to the next pages to read).

### 4.3 Components page (`02_*`)

- Validated reference for the public API surface — describes what each
  component is for and how the pieces wire together. Keep it usage-level;
  exact signatures belong in `docs/lib/`.
- Anatomy: numbered sections, one per component (`## 1. MongoConnectionManager`,
  `## 2. BaseDocument`, …), with `### 8.1`-style sub-numbering for related
  types under a component (e.g. the cache layer's backend / stats / config /
  in-memory / redis implementations). Ends with `## Related`.

### 4.4 Use-case page (the most common)

Standard anatomy, in this order:

```
# Use Case N: <Human Title>

**Scenario:** <one sentence: the problem this recipe solves>

---

## 📦 What's New?        (table: Component | Description — new API used here)
## 🚀 Example            (languaged code block, complete runnable-looking snippet)
## 💡 Tips               (bullets: gotchas, ordering, common mistakes)
## Related               (§5)
```

### 4.5 Deep-dive / worked-example page

For intricate flows (population shapes, cache round-trips), use numbered
depth-first sections and comparison tables:

```
## 1. <Write path>              (### 1a., ### 1b., … per sub-case)
## 2. <Read path>
## 3. <Round trip / tricky bit>
## 4. When to use which         (comparison table)
## Related
```

### 4.6 Best Practices page (`04_*`)

- Flat themed `##` sections (e.g. Layering, Lifecycle, Data & Performance,
  Transactions & Errors, Testing), each a short list of numbered conventions.
- Pure prose — no large code blocks.

### 4.7 Error Handling (`06_*`) / Testing pages

- **Error Handling:** an exceptions table (`Exception | Source | Meaning / fix`),
  a `> ` note on which failures are by design, a `## 🚀 FastAPI Mapping Example`
  code block, then `## 💡 Tips` bullets, then `## Related`.
- **Testing example (`07_*`):** `## 🚀 Mock-Based Quickstart` (focused code
  block), `## 💡 Notes` tip list, `## Related`.

Common to all pages: no frontmatter, `---` between every major section, and a
`## Related` (or variant) footer as the **last** section.

---

## 5. The `## Related` footer

Every page ends with a cross-link footer. Rules:

- Always the **last** section, always preceded by a `---`.
- Standard heading: `## Related` (no emoji).
- One bullet line; links separated by ` · ` (middle dot plus spaces).
- Link label format: `[NN – Title](relative_path)` — en-dash, page number, title.
- Paths are **relative**: same directory → `02_custom_repo.md`; parent →
  `../01_overview.md`; child → `03_use_cases/01_basic_crud.md`.
- Link order follows nav order (each `Related` points to related next/sibling
  pages, plus the overview/components anchor).

Examples (from mongo-ops):

```
## Related
- [02 – Custom repository](02_custom_repo.md) · [04 – Pagination](04_pagination.md) · [Overview](../01_overview.md)
```

Variants:

- `## ➡️ Read Next` — used on the overview page (linear reading order).
- `## 🔗 Related Resources` — only on `index.md`, one bullet per external resource.

---

## 6. Tone & formatting rules

- **Written for humans**: short sentences, concrete examples, plain words.
- Emoji-prefixed H2 headings for recognizable section types
  (`📦 What's New?`, `🚀 Example`, `💡 Tips`, `🚀 Key Features`).
- `---` horizontal rule between every major section.
- Code blocks always declare a language (```python, ```bash, etc.).
- Use tables for comparisons and structured decisions; bullets for lists;
  ASCII diagrams for architecture.
- Bold key terms inline. Use `inline code` for symbols/APIs.
- Keep pages focused: one recipe/purpose per page. If a page balloons past
  ~10 KB, split it (add a numbered deep-dive page instead).
- Match tone of existing pages in the repo before writing new ones.

---

## 7. Build & verify workflow

After creating or editing wiki pages:

```bash
# 1. Build the wiki (from the repo root)
doc-forge build --wiki                       # wiki only
doc-forge build --wiki --mkdocs --module <pkg>   # wiki + lib together

# 2. Preview locally
doc-forge serve --wiki

# 3. Collect into the hub (run from the docs/ service repo)
python collect.py                            # copies site, regenerates index + nginx.conf
python collect.py --dry-run                  # preview without writing
```

Verification checklist:

- `doc-forge build --wiki` completes with no warnings about missing files.
- Every new page is present in `docs/mkdocs.wiki.yml` **and** in the index
  Documentation Structure table.
- Every page ends with a `## Related` block and no dead links (paths resolve).
- After `collect.py`: the hub card links to both `/wiki/` and `/lib/` and the
  pages render (spot-check with the served site).
- If code/docstrings changed (no change when wiki-only), run the repo gates:
  `black`, `ruff`, `mypy`, `pytest`.

---

## 8. Before/after checklist

**Before creating a page:**

- [ ] Confirm it is genuinely wiki material (how-to) and not API contract.
- [ ] Find the right filename (`NN_snake_case.md`) and directory for its theme.
- [ ] Outline the sections per §4 anatomy that fits the content.

**After creating/editing a page:**

- [ ] Page wired into `docs/mkdocs.wiki.yml` nav (themed subgroup if needed).
- [ ] `index.md` Documentation Structure table updated.
- [ ] `## Related` footer present, relative links, nav order.
- [ ] `---` separators consistent; no frontmatter; emoji headings where apt.
- [ ] Build passes; collect run; hub shows `/wiki/` + `/lib/` links.
- [ ] No orphaned files, no dead links.
````
---

© Aetoskia Internal