feat(docs): generate Section 5 from function comment headers

The man-page-style comment header above each function in functions/*.fish
becomes the SSOT for that function's documentation. Writing a new function
and documenting it are now the same act.

- manualtools.parse_functions() parses every header carrying a # CATEGORY;
  absence of one is the opt-in, keeping bundled-plugin and prompt internals
  out of the manual with no exclusion list to maintain.
- build-manual.py generates entries for both --concat and --site, with
  **Dependencies:** rendered as links and a **Used by:** reverse index
  computed in one pass. Cross-category links are the navigation win.
- docs/manual/05-functions/*.md reduced to frontmatter-only stubs. Every
  intro measured zero words, so the category files were pure entry
  containers; ordering, titles, and helpKeywords routing are untouched.
- _first_sentence() unwraps the leading hard-wrapped paragraph and skips
  the whole Synopsis block, not just its label line. Site cards no longer
  truncate mid-clause or show a synopsis as their description.

Verification, per the design spec:
- test_concat_roundtrips_original scoped to sections 0-4 and 6-11. It
  guarded a format migration; this is a content migration.
- replaced by structural checks: one entry per categorised function, the
  required sections present, every category resolving to a stub with no
  stub empty, and every declared dependency resolving to a real function
  or a type -q-guarded binary.
- public functions lacking # CATEGORY warn rather than fail, so a new
  user-facing function going undocumented stays visible in CI.

24/24 checks pass. 94 entries generated from 94 parsed headers.

Also drops a stale claim from open-url's NOTES: config-help --html calls
xdg-open directly and has never called open-url.
This commit is contained in:
2026-07-26 04:12:48 -04:00
parent 00f70e8558
commit a65e05b661
24 changed files with 1594 additions and 1601 deletions
@@ -7,57 +7,4 @@ helpKeywords:
- system
---
## top
Synopsis: top [args...]
Launches btop as a modern resource monitor. Falls back to system top.
## swapstat
Synopsis: swapstat
Displays a colorized memory report: kernel swappiness, zRAM compression
ratio, zRAM device details, and active swap priorities.
## sbver
Synopsis: sbver [--brief]
Verifies Secure Boot signatures on all EFI binaries tracked by sbctl.
Color-codes results: green checkmark (verified), red X (unsigned).
Prints a pass/fail summary.
--brief Suppress per-file output, show only the summary
sbver
sbver --brief
## ports
Synopsis: ports
Lists active TCP listeners with lsof, showing port/address without
hostname resolution.
## screensleep
Synopsis: screensleep
Turns off the display via KDE PowerDevil's "Turn Off Screen" action,
invoked through busctl.
## lock
Synopsis: lock
Locks the current desktop session using loginctl lock-session.
## sudo-toggle
Synopsis: sudo-toggle
Toggles the sudo NOPASSWD rule on/off via /etc/sudoers.d/nofail-toggle.
Useful for automated tasks that would otherwise require password entry.
## limine-edit
Synopsis: limine-edit
Opens /boot/limine.conf in sudoedit, then automatically re-enrolls the
config hash, runs CachyOS boot hooks, and re-signs Secure Boot files.
Combines the edit and sign steps into a single command.
---