Orkuncakilkaya
9ed0070039
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>
84 lines
3.3 KiB
YAML
84 lines
3.3 KiB
YAML
name: docs
|
|
|
|
# Rebuild the documentation site and publish it to the `pages` branch on every
|
|
# push to main that touches the docs sources. The site is generated from the
|
|
# per-symbol source of truth in docs/language/** — nothing is hand-edited on the
|
|
# pages branch.
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
paths:
|
|
- 'docs/**'
|
|
- 'tools/docgen/**'
|
|
- 'tools/x/**'
|
|
- '.forgejo/workflows/docs.yml'
|
|
workflow_dispatch: {}
|
|
|
|
permissions:
|
|
contents: write
|
|
|
|
jobs:
|
|
build-and-deploy:
|
|
# Match the label our Forgejo runner actually advertises. The runner is
|
|
# Docker-capable (it provides the `container:` below); `ubuntu-latest` is a
|
|
# GitHub-ism this runner does not register, so a job requesting it sits in
|
|
# "Waiting" forever with "no online runner found matching this label".
|
|
runs-on: docker
|
|
# The generator is now Ludic, so this builds the toolchain from its IR seed
|
|
# (clang assembles the seed into bin/ludicc, which compiles bin/x) exactly
|
|
# like the ci workflow, then runs `x docs-gen`. node:20-bookworm carries git
|
|
# for the clone + publish; clang-16 is the only extra the bootstrap needs.
|
|
container: node:20-bookworm
|
|
steps:
|
|
- name: Install clang-16
|
|
run: |
|
|
set -eu
|
|
export DEBIAN_FRONTEND=noninteractive
|
|
apt-get update -qq
|
|
apt-get install -y -qq --no-install-recommends clang-16 git ca-certificates
|
|
clang-16 --version | head -1
|
|
|
|
- name: Generate the documentation site
|
|
env:
|
|
SOURCE_REF: ${{ github.ref_name }}
|
|
run: |
|
|
set -eu
|
|
git config --global --add safe.directory '*'
|
|
git clone --depth 1 --branch "${SOURCE_REF:-main}" \
|
|
https://git.workshopsoft.io/workshopsoft/ludic.git src
|
|
cd src
|
|
# The toolchain is macOS-first; on this Linux runner it links against a
|
|
# tiny C-free IR shim supplying the Darwin stdout/stderr globals over
|
|
# glibc's, injected through LUDIC_CC. docs-gen is a pure CLI (no
|
|
# windowing), so the C-free bootstrap is all it needs.
|
|
export LUDIC_CC="clang-16 $(pwd)/tools/ci/linux_stdio_shim.ll"
|
|
export LUDIC_HOME="$(pwd)"
|
|
mkdir -p bin
|
|
clang-16 tools/ci/linux_stdio_shim.ll selfhost/ludicc.seed.ll -o bin/ludicc
|
|
bin/ludicc tools/x/main.ludic -o bin/x
|
|
bin/x docs-gen --out ../public
|
|
bin/x docs-check ../public
|
|
cd ..
|
|
echo "--- generated files ---"
|
|
ls -la public
|
|
|
|
- name: Publish to the pages branch
|
|
env:
|
|
PAGES_TOKEN: ${{ secrets.PAGES_TOKEN }}
|
|
AUTO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
SOURCE_SHA: ${{ github.sha }}
|
|
run: |
|
|
set -eu
|
|
TOKEN="${PAGES_TOKEN:-${AUTO_TOKEN:-}}"
|
|
if [ -z "$TOKEN" ]; then
|
|
echo "::error::No deploy token. Add a repo secret PAGES_TOKEN (write access) or enable the automatic Actions token for pushes."
|
|
exit 1
|
|
fi
|
|
cd public
|
|
git init -q -b pages
|
|
git config user.name "ludic-docs-bot"
|
|
git config user.email "docs@workshopsoft.io"
|
|
git add -A
|
|
git commit -q -m "docs: regenerate site from ${SOURCE_SHA}"
|
|
git push -f "https://ludic-docs-bot:${TOKEN}@git.workshopsoft.io/workshopsoft/ludic.git" pages
|
|
echo "published $(git rev-parse --short HEAD) to pages"
|