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

docs(wiki): align wiki structure with Aetoskia AGENTS.md guidelines

Browse Source 
- Renamed `02_architecture.md` to `02_components.md` to match the standard component page naming convention.
- Updated `docs/mkdocs.wiki.yml` to reflect renamed pages and fix navigation label acronym casing (GSDFC, MCP, MkDocs).
- Updated `index.md` to include the mandatory doc model blockquote, standardize section headers with emojis, and accurately map the `Documentation Structure` table to the navigation menu.
- Standardized all wiki pages (`01_overview.md`, `02_components.md`, `03_conventions.md`, `04_iterative_workflow.md`, and `05_development/*`) by:
  - Adding horizontal rules (`---`) between major sections.
  - Applying emoji-prefixed H2 headings for recognizable section types.
  - Appending `## Related` or `## ➡️ Read Next` footers with standard relative cross-links.
  - Adjusting H1 headers to match guide anatomy (e.g., `# Library Overview` on the overview page).
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-09-14 23:30:45 +05:30
parent c0d8a252ff
commit 4b0fdfaf85
11 changed files with 194 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/mkdocs.wiki.yml
View File

@@ -62,12 +62,12 @@ site_dir: ../site/wiki
nav: nav:
- Home: index.md - Home: index.md
- Overview: 01_overview.md - Overview: 01_overview.md
- Architecture: 02_architecture.md - Components: 02_components.md
- Conventions: 03_conventions.md - Conventions: 03_conventions.md
- Iterative Workflow: 04_iterative_workflow.md - Iterative Workflow: 04_iterative_workflow.md
- Development: - Development:
- Environment: 05_development/01_environment.md - Environment: 05_development/01_environment.md
- Quality Gates: 05_development/02_quality_gates.md - Quality Gates: 05_development/02_quality_gates.md
- Gsdfc Guide: 05_development/03_gsdfc_guide.md - GSDFC Guide: 05_development/03_gsdfc_guide.md
- Mcp Guide: 05_development/04_mcp_guide.md - MCP Guide: 05_development/04_mcp_guide.md
- Mkdocs Configs: 05_development/05_mkdocs_configs.md - MkDocs Configs: 05_development/05_mkdocs_configs.md

19
docs/wiki/01_overview.md
View File

@@ -1,10 +1,12 @@
# Overview # Library Overview
`docforge` turns GSDFC-compliant Python docstrings into maintainable reference `docforge` turns GSDFC-compliant Python docstrings into maintainable reference
documentation. It never edits source docstrings; it reads them, renders them, documentation. It never edits source docstrings; it reads them, renders them,
and assembles documentation sites from all available material. and assembles documentation sites from all available material.
## What it generates ---
## 🧭 Which Build Should You Use?
| Kind | Source | Output | | Kind | Source | Output |
|-----------|----------------------------|---------------------------------| |-----------|----------------------------|---------------------------------|
@@ -13,7 +15,9 @@ and assembles documentation sites from all available material.
| `wiki` | Hand-written markdown | `docs/wiki/**` (unchanged) | | `wiki` | Hand-written markdown | `docs/wiki/**` (unchanged) |
| `mcp` | GSDFC docstrings + renderers | `docs/mcp/**` structured JSON | | `mcp` | GSDFC docstrings + renderers | `docs/mcp/**` structured JSON |
## Per-kind MkDocs builds ---
## 🏗️ Architecture
Each enabled site kind produces its own MkDocs configuration and build: Each enabled site kind produces its own MkDocs configuration and build:
@@ -25,8 +29,15 @@ 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 navigation derived or scoped to that kind. Hand-written wiki content is never
overwritten or regenerated — only its navigation is derived automatically. overwritten or regenerated — only its navigation is derived automatically.
## MCP bundle ---
## 🔄 Lifecycle Rules
`docs/mcp/**` is a self-contained, machine-readable reference generated from `docs/mcp/**` is a self-contained, machine-readable reference generated from
docforge's own GSDFC docstrings. `doc-forge serve --mcp --module docforge` docforge's own GSDFC docstrings. `doc-forge serve --mcp --module docforge`
serves it over MCP. See the [MCP Guide](05_development/04_mcp_guide.md). serves it over MCP. See the [MCP Guide](05_development/04_mcp_guide.md).
---
## ➡️ Read Next
- [02 – Components](02_components.md) · [03 – Conventions](03_conventions.md)

27
docs/wiki/02_architecture.md → docs/wiki/02_components.md
View File

@@ -1,35 +1,45 @@
# Architecture # Components
`docforge` is split into four horizontal layers. Everything flows top to `docforge` is split into four horizontal layers. Everything flows top to
bottom through the CLI. bottom through the CLI.
## Loaders → Models ---
## 1. Loaders & Models
The `docforge/loaders` package wraps `griffe` to extract modules, functions, The `docforge/loaders` package wraps `griffe` to extract modules, functions,
classes, and Google-style docstring sections. Loaded data is normalized into classes, and Google-style docstring sections. Loaded data is normalized into
the object model under `docforge/models` (`Project`, `Module`, `DocObject`). the object model under `docforge/models` (`Project`, `Module`, `DocObject`).
## Navigation ---
## 2. Navigation
`docforge/nav` parses `docforge.nav.yml` specs (`NavSpec`, `Resolver`, and the `docforge/nav` parses `docforge.nav.yml` specs (`NavSpec`, `Resolver`, and the
MkDocs nav emitter) and, since the wiki kind, derives wiki navigation from the MkDocs nav emitter) and, since the wiki kind, derives wiki navigation from the
file structure via `build_wiki_nav`. file structure via `build_wiki_nav`.
## Renderers ---
## 3. Renderers
`docforge/renderers` turn model data into artifacts: `docforge/renderers` turn model data into artifacts:
- `MkDocsRenderer` → `docs/lib/**` reference markdown - `MkDocsRenderer` → `docs/lib/**` reference markdown
- `MCPRenderer` → `docs/mcp/**` structured documentation - `MCPRenderer` → `docs/mcp/**` structured documentation
## Servers ---
## 4. Servers
`docforge/servers` serves generated artifacts over live protocols: `docforge/servers` serves generated artifacts over live protocols:
- `MCPServer` → serves a pre-generated `docs/mcp/**` bundle through MCP - `MCPServer` → serves a pre-generated `docs/mcp/**` bundle through MCP
resources (`docs://index`, `docs://nav`, `docs://modules/{module}`) resources (`docs://index`, `docs://nav`, `docs://modules/{module}`)
## CLI ---
## 5. CLI
`docforge/cli` wires it all together: `docforge/cli` wires it all together:
@@ -38,3 +48,8 @@ file structure via `build_wiki_nav`.
- `mkdocs_utils.py` — per-kind config generation (`docs/mkdocs.{lib,api,wiki}.yml`) - `mkdocs_utils.py` — per-kind config generation (`docs/mkdocs.{lib,api,wiki}.yml`)
with navigation re-rooted to each kind's `docs_dir` with navigation re-rooted to each kind's `docs_dir`
- `api_utils.py` — OpenAPI loading and API docs generation - `api_utils.py` — OpenAPI loading and API docs generation
---
## Related
- [01 – Overview](01_overview.md) · [03 – Conventions](03_conventions.md)

41
docs/wiki/03_conventions.md
View File

@@ -1,5 +1,7 @@
# Conventions # Conventions
---
## GSDFC docstrings ## GSDFC docstrings
All documented source uses the Google-Styled Doc-Forge Convention (GSDFC): All documented source uses the Google-Styled Doc-Forge Convention (GSDFC):
@@ -12,31 +14,42 @@ package docstring, which is exported verbatim into
Key rules: Key rules:
- Use parenthesized types in prose entries (`name (Type):`) that match the 1. Use parenthesized types in prose entries (`name (Type):`) that match the
signature types. signature types.
- Use `# Summary`, `# Examples`, and `# Notes` sections at module level. 2. Use `# Summary`, `# Examples`, and `# Notes` sections at module level.
- Use `Args:`, `Returns:`, `Raises:`, `Yields:`, `Notes:`, and `Example:` 3. Use `Args:`, `Returns:`, `Raises:`, `Yields:`, `Notes:`, and `Example:`
sections at function and method level. sections at function and method level.
- Always update the matching `.pyi` stub alongside the `.py` implementation. 4. Always update the matching `.pyi` stub alongside the `.py` implementation.
---
## `.pyi` stubs ## `.pyi` stubs
Every module ships a matching `.pyi` stub kept in sync with the `.py` Every module ships a matching `.pyi` stub kept in sync with the `.py`
implementation. When signatures change, update both files. implementation. When signatures change, update both files.
---
## Wiki pages ## Wiki pages
- Hand-written markdown lives in `docs/wiki/**` and is never generated. 1. Hand-written markdown lives in `docs/wiki/**` and is never generated.
- File names use a numeric prefix: `01_overview.md`, `02_architecture.md`. 2. File names use a numeric prefix: `01_overview.md`, `02_components.md`.
- Nested directories become nested navigation groups: 3. Nested directories become nested navigation groups:
`05_development/01_environment.md` → group *Development*. `05_development/01_environment.md` → group *Development*.
- `index.md` is the site `Home` at the root, and a section root inside a 4. `index.md` is the site `Home` at the root, and a section root inside a
directory. directory.
- Navigation labels are derived by stripping the numeric prefix and applying 5. Navigation labels are derived by stripping the numeric prefix and applying
title case on the remaining words. title case on the remaining words.
---
## Templates ## Templates
MkDocs config fragments live in `docforge/templates`. The `mkdocs.wiki.yml` MkDocs config fragments live in `docforge/templates`. The `mkdocs.wiki.yml`
fragment carries only the `search` plugin, since wiki pages contain no fragment carries only the `search` plugin, since wiki pages contain no
mkdocstrings directives. mkdocstrings directives.
---
## Related
- [02 – Components](02_components.md) · [04 – Iterative Workflow](04_iterative_workflow.md)

21
docs/wiki/04_iterative_workflow.md
View File

@@ -2,7 +2,9 @@
A docs build runs through the CLI in a single pass. A docs build runs through the CLI in a single pass.
## Build commands ---
## 🚀 Build commands
```bash ```bash
# Library reference only # Library reference only
@@ -18,7 +20,9 @@ doc-forge build --wiki --site-name docforge
doc-forge build --mcp --module docforge doc-forge build --mcp --module docforge
``` ```
## What a build does ---
## 🔄 What a build does
1. Validates the requested modes (`--mkdocs`, `--api`, `--wiki`, `--mcp`). 1. Validates the requested modes (`--mkdocs`, `--api`, `--wiki`, `--mcp`).
2. Generates library sources under `docs/lib/**` with `MkDocsRenderer`. 2. Generates library sources under `docs/lib/**` with `MkDocsRenderer`.
@@ -29,7 +33,9 @@ doc-forge build --mcp --module docforge
6. Runs `mkdocs build` once per config, emitting self-contained sites 6. Runs `mkdocs build` once per config, emitting self-contained sites
`site/lib/`, `site/api/`, and `site/wiki/`. `site/lib/`, `site/api/`, and `site/wiki/`.
## Explore the sites ---
## 🧭 Explore the sites
```bash ```bash
doc-forge build --wiki --mkdocs --module docforge doc-forge build --wiki --mkdocs --module docforge
@@ -40,9 +46,16 @@ doc-forge serve --api
doc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml doc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml
``` ```
## Serve the MCP bundle ---
## 📦 Serve the MCP bundle
```bash ```bash
doc-forge build --mcp --module docforge doc-forge build --mcp --module docforge
doc-forge serve --mcp --module docforge doc-forge serve --mcp --module docforge
``` ```
---
## Related
- [03 – Conventions](03_conventions.md) · [01 – Environment](05_development/01_environment.md)

13
docs/wiki/05_development/01_environment.md
View File

@@ -1,6 +1,8 @@
# Environment Setup # Environment Setup
## Create the environment ---
## 🚀 Create the environment
```bash ```bash
python -m venv .venv python -m venv .venv
@@ -10,7 +12,9 @@ pip install -e .
Requires Python 3.10+ (per `pyproject.toml`). Requires Python 3.10+ (per `pyproject.toml`).
## Dependencies ---
## 📦 Dependencies
Development extras include: Development extras include:
@@ -19,3 +23,8 @@ Development extras include:
- `black` — auto-formatting - `black` — auto-formatting
- `mypy` — strict typing checks - `mypy` — strict typing checks
- `pydoclint` — docstring ↔ signature consistency checks - `pydoclint` — docstring ↔ signature consistency checks
---
## Related
- [04 – Iterative Workflow](../04_iterative_workflow.md) · [02 – Quality Gates](02_quality_gates.md)

13
docs/wiki/05_development/02_quality_gates.md
View File

@@ -2,6 +2,10 @@
Run all checks before pushing: Run all checks before pushing:
---
## 🚀 Commands
```bash ```bash
.venv\Scripts\python.exe -m pytest .venv\Scripts\python.exe -m pytest
.venv\Scripts\python.exe -m ruff check docforge tests .venv\Scripts\python.exe -m ruff check docforge tests
@@ -10,7 +14,9 @@ Run all checks before pushing:
.venv\Scripts\pydoclint.exe docforge .venv\Scripts\pydoclint.exe docforge
``` ```
## Test layout ---
## 📁 Test layout
| Path | Covers | | Path | Covers |
|--------------------------|------------------------------------| |--------------------------|------------------------------------|
@@ -21,3 +27,8 @@ Run all checks before pushing:
CLI tests use the `cli_runner` fixture with `mock_mkdocs_build` and 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 `mock_mkdocs_load_config` so they exercise the full flow without invoking a
real MkDocs build. real MkDocs build.
---
## Related
- [01 – Environment](01_environment.md) · [03 – GSDFC Guide](03_gsdfc_guide.md)

37
docs/wiki/05_development/03_gsdfc_guide.md
View File

@@ -5,7 +5,9 @@ in the `docforge/__init__.py` package docstring. It describes how to write
docstrings that render correctly in MkDocs and stay machine-parseable by docstrings that render correctly in MkDocs and stay machine-parseable by
doc-forge, MkDocs, and MCP clients. doc-forge, MkDocs, and MCP clients.
## Overview ---
## 🧭 Overview
- Docstrings are the single source of truth. - Docstrings are the single source of truth.
- `doc-forge` compiles docstrings but never rewrites them. - `doc-forge` compiles docstrings but never rewrites them.
@@ -13,7 +15,9 @@ doc-forge, MkDocs, and MCP clients.
- Type hints live in signatures; prose entries repeat the type in - Type hints live in signatures; prose entries repeat the type in
parentheses and must match the signature. parentheses and must match the signature.
## Module docstrings ---
## 📦 Module docstrings
Modules use Markdown headings and `---` separators. Modules use Markdown headings and `---` separators.
@@ -23,7 +27,9 @@ Recommended sections:
- `# Examples` — a representative usage snippet - `# Examples` — a representative usage snippet
- `# Notes` — guarantees, lifecycle, and thread-safety notes - `# Notes` — guarantees, lifecycle, and thread-safety notes
## Class docstrings ---
## 📦 Class docstrings
Recommended sections, in order: Recommended sections, in order:
@@ -32,7 +38,9 @@ Recommended sections, in order:
- `Notes:` — grouped subsections such as **Guarantees**, **Lifecycle** - `Notes:` — grouped subsections such as **Guarantees**, **Lifecycle**
- `Example:` — indented `python` code block - `Example:` — indented `python` code block
## Function and method docstrings ---
## 📦 Function and method docstrings
Recommended section order: Recommended section order:
@@ -53,12 +61,16 @@ Formatting rules:
- Fenced `python` blocks are allowed inside `Example:` sections, indented - Fenced `python` blocks are allowed inside `Example:` sections, indented
four spaces. four spaces.
## Property docstrings ---
## 📦 Property docstrings
Properties document their return values with a `Returns:` section and, when Properties document their return values with a `Returns:` section and, when
meaningful, an `Example:`. meaningful, an `Example:`.
## Example ---
## 🚀 Example
```python ```python
def process(foo: Foo, multiplier: int) -> int: def process(foo: Foo, multiplier: int) -> int:
@@ -90,13 +102,17 @@ def process(foo: Foo, multiplier: int) -> int:
""" """
``` ```
## Keeping stubs in sync ---
## 🔄 Keeping stubs in sync
Every `.py` module ships a matching `.pyi` stub. When a signature or a public 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 symbol changes, update both files. Signature annotations in the stub must
match the implementation. match the implementation.
## Enforcement ---
## 🛡️ Enforcement
`pydoclint` (Google style) runs in CI and verifies that `Args:`/`Returns:` `pydoclint` (Google style) runs in CI and verifies that `Args:`/`Returns:`
sections match function signatures, including types. sections match function signatures, including types.
@@ -106,3 +122,8 @@ sections match function signatures, including types.
not required to map to literal `raise` statements. not required to map to literal `raise` statements.
- `check-class-attributes = false` — `Attributes:` sections document instance - `check-class-attributes = false` — `Attributes:` sections document instance
attributes without class-level annotations. attributes without class-level annotations.
---
## Related
- [02 – Quality Gates](02_quality_gates.md) · [04 – MCP Guide](04_mcp_guide.md)

17
docs/wiki/05_development/04_mcp_guide.md
View File

@@ -5,7 +5,9 @@ GSDFC docstrings and serve that bundle over the Model Context Protocol (MCP).
The bundle is self-contained: readers can derive the full API reference — The bundle is self-contained: readers can derive the full API reference —
signatures, docstrings, and structure — for the documented project. signatures, docstrings, and structure — for the documented project.
## Building the bundle ---
## 🚀 Building the bundle
```bash ```bash
doc-forge build --mcp --module docforge doc-forge build --mcp --module docforge
@@ -17,7 +19,9 @@ This writes structured JSON into `docs/mcp/`:
- `nav.json` — module list with `docs://modules/{module}` resource URIs - `nav.json` — module list with `docs://modules/{module}` resource URIs
- `modules/{dotted.path}.json` — per-module serialized documentation - `modules/{dotted.path}.json` — per-module serialized documentation
## Serving the bundle ---
## 🚀 Serving the bundle
```bash ```bash
doc-forge serve --mcp --module docforge doc-forge serve --mcp --module docforge
@@ -36,7 +40,9 @@ Missing resources are returned as structured error dictionaries rather than
exceptions. The default transport is `streamable-http`; `stdio` and `sse` are exceptions. The default transport is `streamable-http`; `stdio` and `sse` are
supported via `MCPServer.run`. supported via `MCPServer.run`.
## Bundle contents ---
## 📦 Bundle contents
Each module resource contains: Each module resource contains:
@@ -49,3 +55,8 @@ Because the bundle is generated from docstrings, the quality of the bundle
equals the quality of the project's GSDFC docstrings. For docforge itself, equals the quality of the project's GSDFC docstrings. For docforge itself,
the GSDFC specification is carried in `modules/docforge.json` via the the GSDFC specification is carried in `modules/docforge.json` via the
`docforge/__init__.py` package docstring, making the bundle self-documenting. `docforge/__init__.py` package docstring, making the bundle self-documenting.
---
## Related
- [03 – GSDFC Guide](03_gsdfc_guide.md) · [05 – MkDocs Configs](05_mkdocs_configs.md)

17
docs/wiki/05_development/05_mkdocs_configs.md
View File

@@ -5,7 +5,9 @@ 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 that sets `docs_dir` to the kind's source directory and `site_dir` to
`../site/{kind}`. `../site/{kind}`.
## File wins ---
## 📄 File wins
`docs/mkdocs.{kind}.yml` is a repo-owned file, not a build byproduct: `docs/mkdocs.{kind}.yml` is a repo-owned file, not a build byproduct:
@@ -19,7 +21,9 @@ that sets `docs_dir` to the kind's source directory and `site_dir` to
Because a present file is never rewritten, rerunning a build is a no-op for Because a present file is never rewritten, rerunning a build is a no-op for
versioned configs: the working tree stays clean. versioned configs: the working tree stays clean.
## Templates ---
## 🧩 Templates
The built-in defaults live in `docforge/templates/`: The built-in defaults live in `docforge/templates/`:
@@ -36,7 +40,9 @@ kind fragment, then filling in generation-time values (`site_name`,
theme `icon` from `docforge.nav.yml`). Pass `--template <path>` to replace the theme `icon` from `docforge.nav.yml`). Pass `--template <path>` to replace the
built-in templates entirely. built-in templates entirely.
## Supported layouts ---
## 🏗️ Supported layouts
- **Per-kind config** — the standard layout; each kind builds to - **Per-kind config** — the standard layout; each kind builds to
`site/{kind}` and is served under `/<repo>/{kind}/`. `site/{kind}` and is served under `/<repo>/{kind}/`.
@@ -46,3 +52,8 @@ built-in templates entirely.
kind to the root `site/` dir in this case. kind to the root `site/` dir in this case.
Commit `docs/mkdocs.{kind}.yml` so served docs are reproducible from source. Commit `docs/mkdocs.{kind}.yml` so served docs are reproducible from source.
---
## Related
- [04 – MCP Guide](04_mcp_guide.md)

30
docs/wiki/index.md
View File

@@ -1,9 +1,10 @@
# 🔨 docforge — Docstring-Driven Documentation Forge # 🧩 docforge — Docstring-Driven Documentation Forge
`docforge` is an internal documentation tool that generates reference `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.
documentation from Google-Styled Doc-Forge Convention (GSDFC) docstrings and
assembles it into per-kind MkDocs sites, alongside hand-written wiki pages and > **Doc model:** this wiki is written for humans — how‑to guides, examples,
OpenAPI-based API docs. > and testing recipes. The authoritative API contracts live in the code
> (docstrings) and the machine‑readable bundle under `docs/mcp/`.
--- ---
@@ -17,17 +18,28 @@ OpenAPI-based API docs.
--- ---
## 📦 Installation
```bash
# Internal PyPI (TBD)
pip install docforge
```
---
## 📁 Documentation Structure ## 📁 Documentation Structure
| Section | Description | | Section | Description |
|----------------------------------------------| -------------------------------------------------- | |----------------------------------------------| -------------------------------------------------- |
| [Overview](01_overview.md) | What docforge is and how it fits the pipeline | | [Overview](01_overview.md) | What docforge is and how it fits the pipeline |
| [Architecture](02_architecture.md) | Loaders, models, nav, renderers, CLI, servers | | [Components](02_components.md) | Loaders, models, nav, renderers, CLI, servers |
| [Conventions](03_conventions.md) | GSDFC, `.pyi` stubs, and template conventions | | [Conventions](03_conventions.md) | GSDFC, `.pyi` stubs, and template conventions |
| [Iterative Workflow](04_iterative_workflow.md) | How a docs build runs end to end | | [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 | | [Environment](05_development/01_environment.md) | Environment setup |
| [Docstring Guide](05_development/03_gsdfc_guide.md) | How to write GSDFC-conformant docstrings | | [Quality Gates](05_development/02_quality_gates.md) | Test layout and quality checks |
| [GSDFC 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 | | [MCP Guide](05_development/04_mcp_guide.md) | Building, serving, and consuming the MCP bundle |
| [MkDocs Configs](05_development/05_mkdocs_configs.md) | MkDocs config generation and templates |
--- ---
@@ -301,4 +313,4 @@ Verification checklist:
```` ````
--- ---
© Aetoskia Internal © Aetoskia Internal — `docforge` 1.0