docs: automated documentation pipeline (per-symbol source → pages)
Some checks failed
docs / build-and-deploy (push) Failing after 38s
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>
This commit is contained in:
parent
a3a1e4d160
commit
51ddfa3ce9
121 changed files with 3827 additions and 0 deletions
104
docs/site/site.json
Normal file
104
docs/site/site.json
Normal file
|
|
@ -0,0 +1,104 @@
|
|||
{
|
||||
"brand": "Ludic",
|
||||
"tagline": "The opinionated, compiled language for 2D games.",
|
||||
"repo_url": "https://git.workshopsoft.io/workshopsoft/ludic",
|
||||
"meta": {
|
||||
"title": "Ludic — the opinionated game language",
|
||||
"description": "Ludic is an opinionated, compiled language for 2D games. The entity system, rendering, named colors, input, deterministic math and save/load are part of the language — so you build a game, not a framework.",
|
||||
"og_title": "Ludic — the opinionated game language",
|
||||
"og_description": "An opinionated, compiled language for 2D games. The ECS, rendering, colors, input and save/load are built in — build a game, not a framework."
|
||||
},
|
||||
"nav_links": [
|
||||
{ "label": "Features", "href": "#features" },
|
||||
{ "label": "Examples", "href": "#showcase" },
|
||||
{ "label": "Get started", "href": "#start" },
|
||||
{ "label": "API Reference", "href": "api.html" }
|
||||
],
|
||||
"hero": {
|
||||
"pill": "Opinionated · Batteries-included · No framework",
|
||||
"title_pre": "Build a game,",
|
||||
"title_accent": "not a framework.",
|
||||
"lead": "Ludic is an <b>opinionated, compiled language for 2D games</b>. The entity system, drawing, named colors, input, deterministic math and save/load aren't libraries you wire up — they're <b>part of the language</b>. You write the game; there's nothing to assemble first.",
|
||||
"snippet": "docs/site/snippets/hero.ludic",
|
||||
"snippet_name": "hello.ludic",
|
||||
"primary_cta": { "label": "Get started →", "href": "#start" },
|
||||
"secondary_cta": { "label": "API Reference", "href": "api.html" },
|
||||
"pipeline": [".ludic", "ludicc", "optimized IR", "native binary"],
|
||||
"pipeline_note": "One step from your code to a native binary. No engine to install, no interpreter, no runtime to ship alongside it — the game <i>is</i> the executable."
|
||||
},
|
||||
"features": {
|
||||
"kicker": "Why Ludic",
|
||||
"title": "A language shaped around the game.",
|
||||
"intro": "The things you normally bolt on — an entity-component system, a renderer, a deterministic clock, save/load — are primitives of the language itself. One opinionated way to do each, so there's little to decide and nothing to wire up.",
|
||||
"cards": [
|
||||
{ "icon": "🧩", "title": "ECS in the syntax", "html": "<code>property</code>, <code>model</code>, and <code>handler</code> are keywords. Query entities with <code>query [A, B, {Tag}]</code> and iterate matches directly — no framework to wire up." },
|
||||
{ "icon": "⏱️", "title": "Deterministic runtime", "html": "Q16.16 <code>fixed</code>-point math and a seeded RNG mean the same inputs produce the same frame — byte-for-byte — every run. Ideal for replays and lockstep netcode." },
|
||||
{ "icon": "🎨", "title": "Drawing & named colors", "html": "The <code>Screen</code> API draws rectangles, text and pixels with named arguments; <code>Color.Crimson</code> and 220 more names read like English and cost nothing at runtime." },
|
||||
{ "icon": "📦", "title": "One self-contained binary", "html": "A game compiles to a single native executable — no engine to install, no interpreter, no runtime shipped beside it. Build, and run the file." },
|
||||
{ "icon": "💾", "title": "Snapshot save/load", "html": "<code>save()</code> and <code>load()</code> serialize the entire ECS world — every entity, property and program <code>var</code> — in one call." },
|
||||
{ "icon": "🎬", "title": "Scenes & state machines", "html": "<code>scene</code>/<code>layer</code>/<code>become</code> model mutually-exclusive game states with enter/exit hooks; <code>match</code>/<code>machine</code>/<code>state</code> handle dispatch and per-entity FSMs." },
|
||||
{ "icon": "🖼️", "title": "Retained UI & assets", "html": "Declare a widget tree as data with <code>ui</code> — panels, labels, buttons, 9-slice skins, keyboard focus. Sprites decode from PNG at runtime; text is real TrueType." },
|
||||
{ "icon": "🔌", "title": "Modules & native calls", "html": "<code>module</code> + <code>@export fn</code> builds a shared library of plain native symbols; <code>extern fn … = \"symbol\"</code> reaches out to any native library when you need the platform." }
|
||||
]
|
||||
},
|
||||
"showcase": {
|
||||
"kicker": "Show, don't tell",
|
||||
"title": "Real programs, one toolchain.",
|
||||
"intro": "The same <code style=\"color:var(--mint)\">ludicc</code> that builds a JRPG builds a from-scratch Snake and a scene demo. Nothing is hardcoded to a genre — and every token below links into the reference.",
|
||||
"samples": [
|
||||
{ "label": "snake", "name": "snake.ludic", "file": "docs/site/snippets/snake.ludic",
|
||||
"note": "A complete Snake — grid, growth, food, game-over — from primitives. State is named vars, colors are named, and every draw call says what each argument is." },
|
||||
{ "label": "scenes", "name": "scenes.ludic", "file": "docs/site/snippets/scenes.ludic",
|
||||
"note": "One active scene at a time. `become` runs the old scene's on-exit and the new one's on-enter; layers draw in declaration order. State is a plain named var." },
|
||||
{ "label": "lifecycle", "name": "toggle.ludic", "file": "docs/site/snippets/lifecycle.ludic",
|
||||
"note": "Enable/disable at three scopes — entity, model, handler. Disabling never destroys data: a property's values persist, so a later enable restores them." },
|
||||
{ "label": "hello", "name": "hello.ludic", "file": "docs/site/snippets/hero.ludic",
|
||||
"note": "The smallest program that exercises the whole pipeline: properties, a spawn, a queried handler, and a render/quit." }
|
||||
]
|
||||
},
|
||||
"philosophy": {
|
||||
"kicker": "The philosophy",
|
||||
"title": "No framework. No glue. Just the game.",
|
||||
"paras": [
|
||||
"Most game code is plumbing — registering systems, wiring a renderer, threading state through a framework. Ludic makes those decisions for you and bakes them into the language, so the code you write is the game's actual logic.",
|
||||
"Opinionated on purpose: one clear way to spawn an entity, draw a frame, name a color, run a scene. Less to choose, less to learn, less to maintain."
|
||||
],
|
||||
"stats": [
|
||||
{ "big": "0", "lbl": "engines to install" },
|
||||
{ "big": "1", "lbl": "clear way to do each thing" },
|
||||
{ "big": "=", "lbl": "deterministic frames" }
|
||||
]
|
||||
},
|
||||
"start": {
|
||||
"kicker": "Get started",
|
||||
"title": "From clone to a native window.",
|
||||
"intro": "Build the toolchain once, then your game. Everything runs from the repo root.",
|
||||
"steps": [
|
||||
{ "title": "Build the toolchain", "html": "<code>bin/x build</code> produces <code>ludicc</code>, the compiler you'll use for everything below." },
|
||||
{ "title": "Compile & run an example", "html": "<code>bin/x app examples/snake.ludic</code> turns a <code>.ludic</code> file into a native binary. Run it to open a real window." },
|
||||
{ "title": "Go headless for tests", "html": "<code>--headless</code> renders frames to a <code>.ppm</code> from piped input — deterministic output you can diff." },
|
||||
{ "title": "Edit with full tooling", "html": "<code>bin/x tools</code> builds the formatter and language server; every editor gets completion, diagnostics and go-to-definition." }
|
||||
],
|
||||
"terminal_name": "zsh — ludic",
|
||||
"terminal": [
|
||||
{ "comment": "build the toolchain (once)" },
|
||||
{ "cmd": "bin/x build" },
|
||||
{ "blank": true },
|
||||
{ "comment": "build and run an example (opens a window)" },
|
||||
{ "cmd": "bin/x app examples/snake.ludic" },
|
||||
{ "cmd": "./build/snake" },
|
||||
{ "blank": true },
|
||||
{ "comment": "deterministic headless render for tests" },
|
||||
{ "cmd": "bin/x app examples/snake.ludic --headless" },
|
||||
{ "cmd": "printf 'ddddwww' | ./build/snake_headless" },
|
||||
{ "out": "→ writes out.ppm" }
|
||||
]
|
||||
},
|
||||
"editors": {
|
||||
"kicker": "Editor experience",
|
||||
"title": "One language server, every editor.",
|
||||
"intro": "<code>ludic-lsp</code> speaks LSP 3.17 over stdio: context-aware completion, diagnostics from the compiler itself, go-to-definition and rename across <code>import</code>ed files, and comment-preserving formatting. It even understands <code>```ludic</code> fences in Markdown.",
|
||||
"list": ["VS Code", "JetBrains IDEs", "Neovim", "Helix", "Emacs", "Sublime Text", "Zed"],
|
||||
"note": "<code>bin/x tools</code> builds <span class=\"mono\">ludic-fmt</span> and <span class=\"mono\">ludic-lsp</span> — the same formatter runs as a CLI for pre-commit hooks and CI."
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue