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>
43 lines
1.7 KiB
Markdown
43 lines
1.7 KiB
Markdown
# Wiki sync
|
|
|
|
The scdoc man pages under [`man/`](../../man) are the **single source of truth**
|
|
for module documentation. The GitHub wiki module pages are generated from them by
|
|
[`generate.py`](generate.py) and kept in sync automatically by the
|
|
[`wiki.yml`](../workflows/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 four `waybar-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 the `NAME`/`FILES`/`AUTHOR`
|
|
man sections, and writes one `Module:-*.md` per 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
|
|
|
|
```sh
|
|
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.
|