workshopsoft/ludic
2
0
Fork 0
Code Issues Pull requests Projects Releases 26 Packages Wiki Activity Actions

feat(tooling): port the docgen site generator to Ludic (no Python) (#41)
All checks were successful
bootstrap / cfree-fixpoint (push) Successful in 16s
Details
ci / build-and-test (push) Successful in 1m4s
Details
commit-lint / conventional-commits (push) Successful in 3s
Details
docs / build-and-deploy (push) Successful in 17s
Details

Browse source 
Follow-up to #31: the doc/lint/grammar checks moved to Ludic there; this ports
the remaining docgen piece (gen.py / check.py / palette.py) so nothing in the
documentation pipeline is Python any more.

Three new `x` subcommands, all in Ludic and compiled by Ludic:

  - x docs-gen [--out DIR]  the static-site generator: parses docs/language/**
    front-matter + bodies (fences, Parameters:), builds the section/symbol
    model, reads the asset templates, and emits every page + ns/color/api pages
    + the landing page + ludic-highlight.js + symbols.json + .nojekyll.
  - x docs-check [DIR]      the coverage / integrity guard (required files, a
    page per inventory.json symbol, duplicate-token and one-dir-per-namespace
    guards, highlighter link targets).
  - x docs-palette          the named-colour source of truth: the palette table
    moved into tools/x/docgen.ludic, emitting emit_color.ludic (pointer, not
    ptr) + palette.json.

Verified against the Python oracle: `x docs-gen` reproduces all 466 output files
BYTE-FOR-BYTE (a Ludic json.dumps/html.escape/front-matter port — ordered dicts,
indent=2 vs compact, ensure_ascii \uXXXX, codepoint-aware truncation), and
`x docs-check` matches check.py's pass/fail output. Wired into `x test` as a
gate (docs-gen -> docs-check on a fresh site; docs-palette stays byte-identical).

CI swap: ci.yml and docs.yml call the Ludic generator; docs.yml drops the
python:3.12 container and bootstraps the toolchain from the IR seed instead.
tools/docgen/{gen,check,palette}.py deleted; only assets/ + inventory.json
remain. Completes #31's criterion 3.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Orkun ÇAKILKAYA 2026-08-31 02:12:32 +03:00
parent 109d8c5b4f
commit 9ed0070039
13 changed files with 2027 additions and 946 deletions
Download patch file Download diff file Expand all files Collapse all files

36
tools/docgen/README.md
View file

@ -10,7 +10,7 @@ docs/
language/<category>/<id>.md one file per symbol — keyword, type, phase,
builtin, namespace method, operator, annotation
language/<category>/_section.md section title + blurb + order
language/colors/palette.json the 221 named colors (generated by palette.py)
language/colors/palette.json the 221 named colors (generated by `x docs-palette`)
site/site.json landing-page messaging (hero, features, …)
site/snippets/*.ludic the code shown on the landing page (real programs)
tools/docgen/inventory.json the authoritative symbol set the coverage guard checks
@ -61,27 +61,31 @@ hovering any token shows a summary card from the real API data.
## Build & check
The generator and its guards are written in Ludic and run through `x` — there is
no Python in the pipeline. `assets/` (the CSS/HTML/JS templates) and
`inventory.json` are the only inputs the tools here still read directly.
```bash
python3 tools/docgen/gen.py --out build/pages # generate the whole site
python3 tools/docgen/check.py build/pages # coverage + duplicate-token + link guard
bin/x check-docs # parse every ```ludic doc fence (Ludic; no Python)
bin/x docs-gen --out build/pages # generate the whole site
bin/x docs-check build/pages # coverage + duplicate-token + link guard
bin/x check-docs # parse every ```ludic doc fence
```
`check.py` fails CI if any symbol in `inventory.json` lacks a page, if a token is
documented on two pages, or if a highlighter link points at a missing page — so
"every symbol is documented, autogenerated each time" is enforced. `validate.py`
needs a built `bin/ludicc`; the deploy CI is Python-only, so run it locally or in
a toolchain-enabled job.
No third-party dependencies — Python standard library only.
`docs-check` fails CI if any symbol in `inventory.json` lacks a page, if a token
is documented on two pages, or if a highlighter link points at a missing page —
so "every symbol is documented, autogenerated each time" is enforced. It needs a
built `bin/x` (bootstrapped from the IR seed with clang alone).
## Publish
`.forgejo/workflows/docs.yml` runs `gen.py` + `check.py` on every push to `main`
that touches `docs/**` or `tools/docgen/**`, and publishes the result to the
`pages` branch root. `index.html` + `.nojekyll` always stay at the root.
`.forgejo/workflows/docs.yml` bootstraps the toolchain from the IR seed and runs
`x docs-gen` + `x docs-check` on every push to `main` that touches `docs/**`,
`tools/docgen/**` or `tools/x/**`, and publishes the result to the `pages` branch
root. `index.html` + `.nojekyll` always stay at the root.
## Colors
`palette.json` is generated by `tools/docgen/palette.py` from a single `PALETTE`
table, which also generates `selfhost/emit_color.ludic`. Regenerate colors there.
`palette.json` and `selfhost/backend/stdlib/emit_color.ludic` are both generated
by `bin/x docs-palette` from a single palette table — the `pal_add(...)` rows in
`tools/x/docgen.ludic`. Edit the table there and regenerate; do not hand-edit the
generated files.