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:
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user