Orkuncakilkaya
51ddfa3ce9
Some checks failed
docs / build-and-deploy (push) Failing after 38s
Replace the hardcoded landing page and minimal reference with a generated documentation site driven by a single source of truth. - docs/language/**: one file per symbol (93 keywords/types/builtins/namespace methods/operators/annotations), each with front-matter (id, kind, tokens, sig, tip) + description + a ```ludic example. Seeded by exploding the former inline SECTIONS list; these files are now the source of truth. - docs/site/: site.json (editable hero/features/showcase/messaging, not hardcoded) + snippets/*.ludic (real programs shown on the landing page). - tools/docgen/gen.py: generates index.html, api.html, ludic-highlight.js and symbols.json. The highlighter's symbol tables, hover tips and jump anchors are GENERATED from the per-symbol files — add a symbol and it is recognized, tipped and linked in every snippet automatically. Python stdlib only. - tools/docgen/check.py: verifies the pages contract + that no snippet token links to a missing reference anchor. - .forgejo/workflows/docs.yml: rebuilds and publishes to the pages branch on every push to main touching the docs sources. Consumes the new Screen.*/Color.*/named-arg API and the 221-color palette. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| assets | ||
| check.py | ||
| gen.py | ||
| palette.py | ||
| README.md | ||
Ludic documentation generator
Generates the public documentation site (the pages branch) from a single
source of truth, so the site can never drift from the language.
Source of truth
docs/
language/<category>/<id>.md one file per symbol — keyword, type, 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)
site/site.json landing-page messaging (hero, features, …)
site/snippets/*.ludic the code shown on the landing page (real programs)
A symbol file
---
id: kw-handler # anchor in api.html (kw-*, type-*, fn-*, <ns>-*, op-*, annot-*)
name: handler # display name / heading
category: control # which section (matches the directory)
kind: keyword # keyword | type | phase | namespace-method | builtin | annotation | operator
tokens: handler # the literal token(s) the highlighter recognizes & links
sig: handler Name phase P { … }
tip: A block that runs each frame in a given phase. # one-line hover tip
order: 3
---
Full description — inline HTML (`<code>`, `<b>`) and `backtick code` both work.
```ludic
handler Move phase Update { … }
Add such a file and it appears in the API Reference, is recognized + tipped +
linked in **every** code snippet across the site, and lands in `symbols.json` —
with no other file to edit.
## Build
```bash
python3 tools/docgen/gen.py --out build/pages # generate the whole site
python3 tools/docgen/check.py build/pages # sanity-check before publish
Outputs into --out: index.html, api.html, ludic-highlight.js
(its symbol tables generated from the sources above), symbols.json, .nojekyll.
No third-party dependencies — Python standard library only.
Publish
.forgejo/workflows/docs.yml runs this on every push to main that touches
docs/** or tools/docgen/**, and force-publishes the result to the pages
branch root (which the pages-server serves). It needs a repo secret
PAGES_TOKEN with write access (or the automatic Actions token enabled for
pushes). index.html + .nojekyll always stay at the branch 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; never hand-edit either output.