AlexandClaude Opus 4.8
c76bfc018b
Add tooling that makes the scdoc man pages the single source of truth and regenerates the wiki module pages from them: - .github/wiki/mapping.json: man-page -> wiki-page mapping (aggregation-aware) - .github/wiki/generate.py: scdoc -> pandoc -> gfm, strips man-only sections, concatenates aggregated pages, appends optional extras/<Page>.md - .github/wiki/extras/: hand-kept appendices (screenshots) with no man equivalent - .github/workflows/wiki.yml: on push to man/** (or the tooling), regenerate and push the wiki; other wiki pages are left untouched Covers all 65 man pages -> 45 wiki pages (5 new: GPS, Inhibitor, Mango, Menu, WWAN). Non-module and hand-written wiki pages are never modified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Wiki sync
The scdoc man pages under man/ are the single source of truth
for module documentation. The GitHub wiki module pages are generated from them by
generate.py and kept in sync automatically by the
wiki.yml workflow on every push to master that
touches man/** or this tooling.
Files
mapping.json— maps each wiki page to the ordered list of man-page basenames that compose it. Several man pages are concatenated into one aggregated page (e.g.Module:-Hyprland← the fourwaybar-hyprland-*pages). Add an entry here when you add a new man page — the workflow fails the mapping check otherwise.generate.py—scdoc → roff → pandoc → gfm, strips theNAME/FILES/AUTHORman sections, and writes oneModule:-*.mdper mapping entry.extras/<Page>.md— optional hand-maintained appendix (screenshots, showcase snippets that have no man equivalent), appended verbatim after the generated body.
What it touches
Only the pages listed in mapping.json are (re)written. Every other wiki page
(Home, Installation, user showcases, the hand-written Module:-Cava:-GLSL,
Module:-Group, Module:-Load, …) is left untouched.
To edit a module's docs
Edit the man page under man/, not the wiki. The wiki page is overwritten on the
next sync. Put anything with no man equivalent (images, etc.) in extras/.
Run locally
python3 .github/wiki/generate.py --check # validate mapping only
python3 .github/wiki/generate.py --out-dir /tmp/wiki-out # generate a preview
One-time setup
The repository wiki must be enabled (Settings → Features → Wikis) with at least
one initial page so the .wiki.git remote exists.