mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-11-16 12:05:12 -06:00
Adds docstrings to the 900 definitions and 8 modules that had none across the binder CLI, its checks, and the audit and maintenance tools, and corrects a few docstrings that no longer matched the code. Only documentation changed.
90 lines
2.8 KiB
Python
90 lines
2.8 KiB
Python
#!/usr/bin/env python3
|
|
"""Move tbl-colwidths from wrapper divs onto table caption lines."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import re
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
WRAPPER_RE = re.compile(r'^::: \{tbl-colwidths="(\[[^\]]+\])"\}\s*$')
|
|
CAPTION_RE = re.compile(r'^(: .* \{#tbl-[^\s\}]+)(.*\})\s*$')
|
|
|
|
def normalize_content(text: str) -> tuple[str, int]:
|
|
"""Unwrap ``::: {tbl-colwidths="[...]"}`` divs, moving the widths onto the table caption line.
|
|
|
|
Returns the new text and the number of captions changed. A caption that
|
|
already has ``tbl-colwidths`` keeps its own value, though the wrapper is
|
|
still removed. The wrapper ends at the first bare ``:::`` line. Raises
|
|
``ValueError`` when a wrapper holds no ``: ... {#tbl-...}`` caption.
|
|
"""
|
|
lines =text.splitlines(keepends=True)
|
|
out: list[str] = []
|
|
i = 0
|
|
changes = 0
|
|
|
|
while i < len(lines):
|
|
m = WRAPPER_RE.match(lines[i].rstrip("\n"))
|
|
if not m:
|
|
out.append(lines[i])
|
|
i += 1
|
|
continue
|
|
|
|
colwidths = m.group(1)
|
|
i += 1
|
|
block: list[str] = []
|
|
while i < len(lines):
|
|
if lines[i].strip() == ":::":
|
|
i += 1
|
|
break
|
|
block.append(lines[i])
|
|
i += 1
|
|
|
|
caption_idx = None
|
|
for j, line in enumerate(block):
|
|
cm = CAPTION_RE.match(line.rstrip("\n"))
|
|
if not cm:
|
|
continue
|
|
prefix, suffix = cm.group(1), cm.group(2)
|
|
if "tbl-colwidths=" in line:
|
|
caption_idx = j
|
|
break
|
|
block[j] = f'{prefix} tbl-colwidths="{colwidths}"{suffix}\n'
|
|
caption_idx = j
|
|
changes += 1
|
|
break
|
|
|
|
if caption_idx is None:
|
|
raise ValueError("tbl-colwidths wrapper without table caption")
|
|
|
|
out.extend(block)
|
|
|
|
return "".join(out), changes
|
|
|
|
def main(argv: list[str]) -> int:
|
|
"""Normalize the QMD files named in ``argv[1:]``, or all of ``books/**/*.qmd``.
|
|
|
|
The default glob is resolved against the current directory. Files are
|
|
rewritten in place, but only when at least one caption changed. A wrapper
|
|
without a caption raises ``ValueError`` and stops the run; otherwise
|
|
returns 0.
|
|
"""
|
|
paths =[Path(p) for p in argv[1:]] if len(argv) > 1 else list(
|
|
Path("books").rglob("*.qmd")
|
|
)
|
|
total = 0
|
|
for path in paths:
|
|
text = path.read_text(encoding="utf-8")
|
|
if "::: {tbl-colwidths=" not in text:
|
|
continue
|
|
new_text, n = normalize_content(text)
|
|
if n:
|
|
path.write_text(new_text, encoding="utf-8")
|
|
print(f"{path}: {n} table(s)")
|
|
total += n
|
|
print(f"Normalized {total} table(s)")
|
|
return 0
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main(sys.argv))
|