Skip to content

🛠 Building Docs

All documentation for khata-app is produced with doc-forge (installed into the khata venv from the local aetos source).

📋 What Gets Built

Target Command (from repo root) Output
Lib (mkdocs) doc-forge build --mkdocs --module <pkg> [--refresh] docs/lib/… + docs/mkdocs.lib.yml, site/lib/
MCP bundles doc-forge build --mcp --module <pkg> --out-dir docs\mcp\<pkg> docs/mcp/<pkg>/ (index.json, nav.json, modules/)
API (OpenAPI) doc-forge build --api --openapi-spec <spec.json> docs/api/ + docs/mkdocs.api.yml
Wiki doc-forge build --wiki --site-name "Khata App — Wiki" nav from docs/wiki/ + docs/mkdocs.wiki.yml
Serve doc-forge serve local preview

Builds must run from the repo root so Griffe discovers the packages.

📚 Lib Builds

1
2
3
4
5
6
7
8
# first time per package
.\.venv\Scripts\doc-forge.exe build --mkdocs --module domain
.\.venv\Scripts\doc-forge.exe build --mkdocs --module infra
.\.venv\Scripts\doc-forge.exe build --mkdocs --module interfaces
.\.venv\Scripts\doc-forge.exe build --mkdocs --module pipelines

# after docstring/nav changes, refresh and set the nice site name
.\.venv\Scripts\doc-forge.exe build --mkdocs --module domain --refresh --site-name "Khata App — Library Reference" --project-name khata-app

docforge.nav.yml drives the nav groups:

1
2
3
4
5
6
home: lib/index.md
groups:
  Domain: [lib/domain/index.md, lib/domain/enrichment/index.md, lib/domain/fetch_pipeline/index.md, lib/domain/fetch_request/index.md]
  Infra: [lib/infra/index.md]
  Interfaces: [lib/interfaces/index.md]
  Pipelines: [lib/pipelines/index.md]

🧠 MCP Bundles

Serve the API as machine-readable resources an MCP client can consume:

1
2
3
4
.\.venv\Scripts\doc-forge.exe build --mcp --module domain --out-dir docs\mcp\domain
.\.venv\Scripts\doc-forge.exe build --mcp --module infra --out-dir docs\mcp\infra
.\.venv\Scripts\doc-forge.exe build --mcp --module interfaces --out-dir docs\mcp\interfaces
.\.venv\Scripts\doc-forge.exe build --mcp --module pipelines --out-dir docs\mcp\pipelines

🌐 API Build

build --api reads JSON (not YAML). Convert openapi.yaml first:

1
2
.\.venv\Scripts\python.exe -c "import yaml,json,pathlib; p=pathlib.Path('docs/openapi.json'); p.write_text(json.dumps(yaml.safe_load(pathlib.Path('openapi.yaml').read_text(encoding='utf-8')),indent=2),encoding='utf-8')"
.\.venv\Scripts\doc-forge.exe build --api --openapi-spec docs\openapi.json

📖 Wiki Build

The wiki is hand-authored under docs/wiki/; doc-forge only derives the nav:

1
.\.venv\Scripts\doc-forge.exe build --wiki --site-name "Khata App — Wiki" --project-name khata-app

Nav labels come from filenames (01_overview.md → Overview); tune docs/mkdocs.wiki.yml after generation for nicer titles.

⚠️ Known Gotchas

  • pygments — 3.13 + pygments 2.20 crashes the highlighter; keep pygments==2.19.2.
  • nav refresh — after changing docforge.nav.yml, rebuild with --refresh or the nav won't regenerate.
  • unregistered links — MkDocs may warn about ports/ style relative links on the auto-generated index pages; cosmetic only.

Environment · GSDFC Docstrings · Testing