ci(wiki): render option tables, pin pandoc, add visible auto-gen note
Improve the generated wiki pages: - normalize definition-style option blocks (*name*: / typeof: / default:) into scdoc tables, so every module renders options as a clean table like the table-style pages (Bluetooth, Network, ... no longer a wall of text) - drop pandoc's empty leading table-header row so the real header shows - pin pandoc to 3.5 in CI (the distro 2.x man reader mangled lists into blockquotes); matches local output - prepend a visible "auto-generated from master, do not edit here" note to every page (was an invisible HTML comment) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Alex
+102
-6
@@ -35,9 +35,74 @@ def sh(cmd, stdin=None):
|
||||
).stdout
|
||||
|
||||
|
||||
DEF_START = re.compile(r"^\s*\*(.+?)\*:\s*(?:\+\+)?\s*$")
|
||||
INDENT = re.compile(r"^(?:\t| {2,})")
|
||||
FIELD = re.compile(r"^(typeof|default)\s*:\s*(.*)$", re.IGNORECASE)
|
||||
|
||||
|
||||
def normalize_option_blocks(text):
|
||||
"""Rewrite definition-style option blocks into scdoc table syntax.
|
||||
|
||||
Some man pages document options as:
|
||||
|
||||
*name*: ++
|
||||
typeof: string ++
|
||||
default: foo ++
|
||||
Description...
|
||||
|
||||
which pandoc renders as a flat wall of text. Convert consecutive such
|
||||
blocks into the same scdoc table syntax the table-style pages already use
|
||||
(Option / Typeof / Default / Description), so every page renders as a
|
||||
clean table. Table-style pages are left untouched (they never match).
|
||||
Nested (indented) sub-option blocks become their own table. Fenced code
|
||||
blocks are passed through verbatim.
|
||||
"""
|
||||
lines = text.split("\n")
|
||||
out, i, n, in_code = [], 0, len(lines), False
|
||||
while i < n:
|
||||
if lines[i].lstrip().startswith("```"):
|
||||
in_code = not in_code
|
||||
out.append(lines[i])
|
||||
i += 1
|
||||
continue
|
||||
# A block starts with `*name*:` and its first indented line is `typeof:`.
|
||||
m = DEF_START.match(lines[i])
|
||||
nxt = lines[i + 1] if i + 1 < n else ""
|
||||
if in_code or not (m and INDENT.match(nxt)
|
||||
and nxt.strip().lower().startswith("typeof")):
|
||||
out.append(lines[i])
|
||||
i += 1
|
||||
continue
|
||||
rows = []
|
||||
while i < n and DEF_START.match(lines[i]):
|
||||
name = DEF_START.match(lines[i]).group(1)
|
||||
i += 1
|
||||
typ = default = ""
|
||||
desc = []
|
||||
while i < n and INDENT.match(lines[i]):
|
||||
cell = re.sub(r"\s*\+\+\s*$", "", lines[i].strip())
|
||||
f = FIELD.match(cell)
|
||||
if f and f.group(1).lower() == "typeof":
|
||||
typ = f.group(2).strip()
|
||||
elif f and f.group(1).lower() == "default":
|
||||
default = f.group(2).strip()
|
||||
elif cell:
|
||||
desc.append(cell)
|
||||
i += 1
|
||||
rows.append((name, typ, default, " ".join(desc)))
|
||||
if i < n and lines[i].strip() == "" and i + 1 < n and DEF_START.match(lines[i + 1]):
|
||||
i += 1 # swallow blank line between two blocks, continue the run
|
||||
out += ["[- *Option*", ":- *Typeof*", ":- *Default*", ":- *Description*"]
|
||||
for name, typ, default, desc in rows:
|
||||
out += [f"|[ *{name}*", f":[ {typ}", f":[ {default}", f":[ {desc}"]
|
||||
out.append("")
|
||||
return "\n".join(out)
|
||||
|
||||
|
||||
def man_to_gfm(scd_path):
|
||||
"""scdoc -> roff -> pandoc gfm, as raw markdown text."""
|
||||
roff = sh(["scdoc"], stdin=open(scd_path, "rb").read())
|
||||
src = normalize_option_blocks(open(scd_path, encoding="utf-8").read())
|
||||
roff = sh(["scdoc"], stdin=src.encode("utf-8"))
|
||||
gfm = sh(["pandoc", "-f", "man", "-t", "gfm", "--wrap=none"], stdin=roff)
|
||||
return gfm.decode("utf-8")
|
||||
|
||||
@@ -63,21 +128,52 @@ def demote(md, levels=1):
|
||||
return "\n".join(out)
|
||||
|
||||
|
||||
EMPTY_ROW = re.compile(r"^\|(?:\s*\|)+\s*$")
|
||||
SEP_ROW = re.compile(r"^\|[\s:\-|]+\|\s*$")
|
||||
|
||||
|
||||
def fix_tables(md):
|
||||
"""Drop pandoc's empty leading header row so the real first row is the header.
|
||||
|
||||
scdoc's `[-` header markers make pandoc emit an empty header row followed by
|
||||
the actual header as the first body row. Detect `| | |` + separator and
|
||||
remove them, promoting the next row to the header with the same alignment.
|
||||
"""
|
||||
lines = md.splitlines()
|
||||
out, i = [], 0
|
||||
while i < len(lines):
|
||||
if (EMPTY_ROW.match(lines[i]) and i + 2 < len(lines)
|
||||
and SEP_ROW.match(lines[i + 1]) and lines[i + 2].startswith("|")):
|
||||
out.append(lines[i + 2]) # real header
|
||||
out.append(lines[i + 1]) # reuse the separator (keeps alignment)
|
||||
i += 3
|
||||
else:
|
||||
out.append(lines[i])
|
||||
i += 1
|
||||
return "\n".join(out)
|
||||
|
||||
|
||||
def pretty(basename):
|
||||
"""waybar-sway-mode -> sway/mode (submodule heading for aggregated pages)."""
|
||||
return basename.removeprefix("waybar-").replace("-", "/", 1)
|
||||
|
||||
|
||||
REPO = "https://github.com/Alexays/Waybar"
|
||||
|
||||
|
||||
def build_page(man_dir, sources, page, extras_dir):
|
||||
parts = []
|
||||
banner = ("<!-- AUTOGENERATED from " + ", ".join(f"man/{s}.5.scd" for s in sources)
|
||||
+ " by .github/wiki/generate.py — DO NOT EDIT HERE."
|
||||
" Edit the man page(s); the wiki syncs automatically. -->")
|
||||
parts.append(banner)
|
||||
srclinks = ", ".join(f"[`man/{s}.5.scd`]({REPO}/blob/master/man/{s}.5.scd)"
|
||||
for s in sources)
|
||||
note = ("> [!NOTE]\n"
|
||||
f"> This page is **auto-generated from {srclinks}** on the `master` branch.\n"
|
||||
"> Do not edit it here — changes will be overwritten on the next sync.\n"
|
||||
"> To update it, edit the man page(s) and open a PR.")
|
||||
parts.append(note)
|
||||
aggregated = len(sources) > 1
|
||||
for src in sources:
|
||||
scd = os.path.join(man_dir, src + ".5.scd")
|
||||
body = strip_sections(man_to_gfm(scd))
|
||||
body = fix_tables(strip_sections(man_to_gfm(scd)))
|
||||
if aggregated:
|
||||
parts.append(f"\n# {pretty(src)}\n\n" + demote(body))
|
||||
else:
|
||||
|
||||
Reference in New Issue
Block a user