From e20cff41d44065ec44aa89ec1a9dbe613e61c426 Mon Sep 17 00:00:00 2001 From: rootiest Date: Sun, 26 Jul 2026 05:01:01 -0400 Subject: [PATCH 1/2] docs(site): replace starter README and title synopsis fences Swap the Starlight scaffold README for one describing this project's two-source SSOT and dev/deploy workflow. Give the generated function synopsis fence a Starlight filename title (`fish title="name.fish"`) so it reads as a snippet of the function it documents. --- docs/build-manual.py | 6 +++- docs/site/README.md | 65 +++++++++++++++++-------------------------- docs/verify-manual.py | 4 ++- 3 files changed, 33 insertions(+), 42 deletions(-) diff --git a/docs/build-manual.py b/docs/build-manual.py index 961eb7b..7f0468e 100644 --- a/docs/build-manual.py +++ b/docs/build-manual.py @@ -288,7 +288,11 @@ def _prettify_block(block: list[str], entry_name: str | None) -> str: # keep the whole thing in one fence rather than orphaning the rest. while lines and lines[0].startswith(" "): synopsis.append(lines.pop(0).strip()) - out.append("```fish\n" + "\n".join(synopsis) + "\n```") + # Titling the fence with the source file name (Starlight's + # filename-title convention) makes the synopsis read as a snippet + # of the function it documents rather than a bare command example. + info = f'fish title="{entry_name}.fish"' if entry_name else "fish" + out.append(f"```{info}\n" + "\n".join(synopsis) + "\n```") para: list[str] = [] for line in lines + [""]: diff --git a/docs/site/README.md b/docs/site/README.md index 1b7f5c3..93321ec 100644 --- a/docs/site/README.md +++ b/docs/site/README.md @@ -1,49 +1,34 @@ -# Starlight Starter Kit: Basics +# fish-config docs site -[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build) +[Starlight](https://starlight.astro.build) site for the +[fish-config](https://git.rootiest.dev/rootiest/fish-config) manual. -``` -npm create astro@latest -- --template starlight +## Generated, not authored + +Everything under `src/content/docs/` is generated β€” **do not edit it +directly**, changes will be overwritten. The sources are: + +- `docs/manual/**` β€” prose for every section except the functions reference +- `functions/*.fish` comment headers β€” the functions reference (Section 5) + +Regenerate from the repo root: + +```fish title="regenerate the site content" +python3 docs/build-manual.py --site ``` -> πŸ§‘β€πŸš€ **Seasoned astronaut?** Delete this file. Have fun! +`docs/verify-manual.py` validates both sources before you build; run it +first if you've touched a header or a manual page. -## πŸš€ Project Structure +## Development -Inside of your Astro + Starlight project, you'll see the following folders and files: - -``` -. -β”œβ”€β”€ public/ -β”œβ”€β”€ src/ -β”‚ β”œβ”€β”€ assets/ -β”‚ β”œβ”€β”€ content/ -β”‚ β”‚ └── docs/ -β”‚ └── content.config.ts -β”œβ”€β”€ astro.config.mjs -β”œβ”€β”€ package.json -└── tsconfig.json +```fish title="local dev server" +cd docs/site +npm install +npm run dev ``` -Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name. +## Deploy -Images can be added to `src/assets/` and embedded in Markdown with a relative link. - -Static assets, like favicons, can be placed in the `public/` directory. - -## 🧞 Commands - -All commands are run from the root of the project, from a terminal: - -| Command | Action | -| :------------------------ | :----------------------------------------------- | -| `npm install` | Installs dependencies | -| `npm run dev` | Starts local dev server at `localhost:4321` | -| `npm run build` | Build your production site to `./dist/` | -| `npm run preview` | Preview your build locally, before deploying | -| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` | -| `npm run astro -- --help` | Get help using the Astro CLI | - -## πŸ‘€ Want to learn more? - -Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat). +Built and deployed to Cloudflare Pages by the Gitea Actions workflow on +every push to `main` β€” there's no manual deploy step. diff --git a/docs/verify-manual.py b/docs/verify-manual.py index 74d6c94..c91ae27 100644 --- a/docs/verify-manual.py +++ b/docs/verify-manual.py @@ -338,7 +338,9 @@ def test_prettify_splits_an_entry_block(): ) out = build_manual.prettify(body, "rm") - assert "```fish\nrm [-e | args...]\n```" in out, "synopsis was not fenced as fish" + assert '```fish title="rm.fish"\nrm [-e | args...]\n```' in out, ( + "synopsis was not fenced as fish with a filename title" + ) assert "```fish\nrm file.txt" in out, "examples were not fenced as fish" assert out.count("```") == 4, f"expected exactly two fences, got:\n{out}" assert "\nSafe rm wrapper routing to trash:" in out, "description stayed indented" -- 2.52.0 From 625a58fa9f26ce9ebf08d8668526e2ffc4b64cbb Mon Sep 17 00:00:00 2001 From: rootiest Date: Sun, 26 Jul 2026 05:27:26 -0400 Subject: [PATCH 2/2] docs(site): title Examples fences and auto-title file-scoped snippets Function EXAMPLE blocks now render as their own fish fence titled "Examples" (matching the existing "Usage" title on the Synopsis fence), triggered by a flat Example: label line mirroring the Synopsis: prefix. Prose pages get two new generic titling signals in _render_para: a bare indented path ending in a known extension is titled by its basename, and a leading "# in " / "# " comment on a shell paragraph is promoted to the fence title and stripped from the body. This picks up local.fish/secrets.fish path displays and override examples in 07-customization.md for free, plus a bonus .logging_disabled hit. 10-personalization.md's secrets.fish block gets an explicit "# secrets.fish" comment to title it the same way. The four local.fish examples keep their existing descriptive comments rather than a redundant local.fish title. --- docs/build-manual.py | 49 ++++++++++++---- docs/fish-config.md | 97 +++++++++++++++++++++++++++++++ docs/manual/10-personalization.md | 1 + docs/verify-manual.py | 27 ++++++++- 4 files changed, 161 insertions(+), 13 deletions(-) diff --git a/docs/build-manual.py b/docs/build-manual.py index 7f0468e..d249d7e 100644 --- a/docs/build-manual.py +++ b/docs/build-manual.py @@ -154,7 +154,7 @@ def _first_sentence(body: str) -> str: SHELL_HEADS = frozenset( """ abbr alias apt bg bind brew builtin cargo cat cd chmod code command cp curl - dnf echo end env exec export fg fish fisher for funcsave function git help + dnf docker echo end env exec export fg fish fisher for funcsave function git help if jobs kitty ls man math mkdir mv nvim npm pacman paru pip pip3 pkg printf python python3 rm set shutdown source string sudo switch systemctl test time tmux touch trash type wget wezterm while yay zellij zypper @@ -162,6 +162,7 @@ SHELL_HEADS = frozenset( ) SYNOPSIS_PREFIX = "Synopsis:" +EXAMPLE_PREFIX = "Example:" INDENT = " " @@ -201,6 +202,16 @@ def _is_shell(para: list[str], entry_name: str | None) -> bool: return True +# A lone indented line that's just a path ending in a known extension β€” +# e.g. pointing at where a file lives β€” reads better as a titled snippet +# than an unhighlighted grey slab. +PATH_LINE_RE = re.compile(r"^[~$][\w./{}-]*\.\w+$") + +# A leading "# in local.fish" / "# local.fish" comment names the file an +# example belongs to; promote it to the fence title instead of leaving it +# as a literal comment inside the code. +FILENAME_COMMENT_RE = re.compile(r"^#\s*(?:in\s+)?([\w-]+\.\w+)\s*$") + CELL_SPLIT = re.compile(r"\s{2,}") @@ -262,9 +273,18 @@ def _render_para(para: list[str], entry_name: str | None, deeper: bool) -> str: if not deeper: if _is_prose(para): return "\n".join(line.strip() for line in para) + if len(para) == 1 and PATH_LINE_RE.match(para[0].strip()): + path = para[0].strip() + name = path.rsplit("/", 1)[-1] + return f'```fish title="{name}"\n{path}\n```' if _is_shell(para, entry_name): - body = "\n".join(para) - return f"```fish\n{body}\n```" + body = para + title = None + m = FILENAME_COMMENT_RE.match(para[0].strip()) + if m: + title, body = m.group(1), para[1:] + info = f'fish title="{title}"' if title else "fish" + return f"```{info}\n" + "\n".join(body) + "\n```" table = _as_table(para) if table is not None: return table @@ -288,10 +308,10 @@ def _prettify_block(block: list[str], entry_name: str | None) -> str: # keep the whole thing in one fence rather than orphaning the rest. while lines and lines[0].startswith(" "): synopsis.append(lines.pop(0).strip()) - # Titling the fence with the source file name (Starlight's - # filename-title convention) makes the synopsis read as a snippet - # of the function it documents rather than a bare command example. - info = f'fish title="{entry_name}.fish"' if entry_name else "fish" + # A "Usage" title (Starlight's filename-title convention, repurposed + # as a label) makes the synopsis read as a snippet of the function + # it documents rather than a bare command example. + info = 'fish title="Usage"' if entry_name else "fish" out.append(f"```{info}\n" + "\n".join(synopsis) + "\n```") para: list[str] = [] @@ -300,8 +320,17 @@ def _prettify_block(block: list[str], entry_name: str | None) -> str: para.append(line) continue if para: - deeper = any(line.startswith(" ") for line in para) - out.append(_render_para(para, entry_name, deeper)) + if para[0].strip() == EXAMPLE_PREFIX: + example = para[1:] + if example and _is_shell(example, entry_name): + body = "\n".join(example) + out.append(f'```fish title="Examples"\n{body}\n```') + else: + deeper = any(line.startswith(" ") for line in example) + out.append(_render_para(example, entry_name, deeper)) + else: + deeper = any(line.startswith(" ") for line in para) + out.append(_render_para(para, entry_name, deeper)) para = [] return "\n\n".join(chunk for chunk in out if chunk.strip()) @@ -366,7 +395,7 @@ def render_entry(fn: dict[str, list[str]], used_by: list[str], link=None) -> str continue out += ["", head] + [" " + line for line in body] if fn.get("EXAMPLE"): - out += [""] + fn["EXAMPLE"] + out += ["", EXAMPLE_PREFIX] + fn["EXAMPLE"] block = "\n".join((INDENT + line).rstrip() for line in out) diff --git a/docs/fish-config.md b/docs/fish-config.md index 9d3b7d5..d4022fa 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -536,6 +536,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Files or directories to display + Example: cat README.md cat ~/projects/myapp @@ -550,6 +551,7 @@ Add -i (interactive confirmation) to destructive commands: source Source file or directory dest Destination path + Example: copy ./mydir/ ~/backup copy ./mydir/ ~/backup # copies mydir INTO backup, not backup/mydir/ @@ -567,6 +569,7 @@ Add -i (interactive confirmation) to destructive commands: --dua Force dua (fast interactive space analyzer) args... Files/directories or flags forwarded to the selected tool + Example: du ~/Downloads du --disk @@ -580,6 +583,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: dir Directory to summarize (defaults to current directory) + Example: dusize ~/Downloads dusize ~/Videos @@ -593,6 +597,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to the listing command + Example: lD ~/projects ### ls @@ -605,6 +610,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to the listing command + Example: ls ~/projects ls ls -a ~/projects @@ -619,6 +625,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to the listing command + Example: lsr ~/projects ### lss @@ -631,6 +638,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to the listing command + Example: lss ~/downloads ### lstree @@ -643,6 +651,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to the listing command + Example: lstree ~/projects/myapp ### lt @@ -655,6 +664,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to the listing command + Example: lt ~/projects ### ltr @@ -668,6 +678,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to the listing command + Example: ltr ~/projects ### lx @@ -680,6 +691,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to the listing command + Example: lx ~/projects ### mkcd @@ -700,6 +712,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Directory created (or already existed) and entered successfully 1 Directory creation or cd failed + Example: mkcd ~/projects/myapp mkcd ~/projects/newapp/src @@ -715,6 +728,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Directories to create, or flags passed through to command mkdir + Example: mkdir ~/projects/myapp/src ### poke @@ -731,6 +745,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Files created 1 No file argument provided + Example: poke ~/projects/new/src/main.fish ### rg @@ -744,6 +759,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to ripgrep + Example: rg "TODO" src/ rg "fish_greeting" ~/.config/fish/ rg -l "TODO" ~/projects/myapp @@ -776,6 +792,7 @@ Add -i (interactive confirmation) to destructive commands: Notes: Falls back to /usr/bin/rm when trash is unavailable. + Example: rm file.txt rm -e rm -S sensitive_key.pem @@ -799,6 +816,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Sweep completed (or dry run shown) 1 fd not found, or unknown argument provided + Example: scrub scrub -a scrub -d @@ -815,6 +833,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: query Optional search term to pre-filter the directory list + Example: cdi myproject ### clone @@ -831,6 +850,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Repository cloned 1 Not running inside Kitty terminal + Example: clone https://github.com/user/repo.git ### clonet @@ -847,6 +867,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Repository cloned 1 Not running inside Kitty terminal + Example: clonet https://github.com/user/repo.git ## 5.3 Editors and Viewers @@ -882,6 +903,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Editor launched successfully 1 Conflicting flags, no editor found, or clipboard read failed + Example: edit notes.txt edit --visual ~/.config/fish/config.fish edit --terminal --new todo.md @@ -904,6 +926,7 @@ Add -i (interactive confirmation) to destructive commands: The edited command's exit status, or a message when history lookup found nothing. + Example: fc fc git @@ -917,6 +940,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Files or options forwarded to the pager + Example: less /var/log/syslog ### rawfish @@ -929,6 +953,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to fish + Example: rawfish ### view @@ -941,6 +966,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Files or options forwarded to nvim -R or less + Example: view /etc/fstab ## 5.4 Git and Version Control @@ -974,6 +1000,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Subcommand succeeded 1 Bad usage, target is not a git repo, or target not registered + Example: cd ~/src/qmk_firmware; and auto-pull add auto-pull add ~/work/api auto-pull list @@ -993,6 +1020,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Branch checked out or created 1 Not inside a git work tree + Example: branch feature/new-ui ### gi @@ -1017,6 +1045,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Patterns appended or printed 1 Not in a git repository or API fetch failed + Example: gi python,venv gi -b -p gi -s node > .gitignore @@ -1037,6 +1066,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Cleanup complete 1 Argument parsing failed + Example: git-clean --force git-clean @@ -1050,6 +1080,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to the gitui command + Example: gitui ### gitup @@ -1066,6 +1097,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Fetch and status succeeded 1 Not inside a git work tree + Example: gitup gitup --all @@ -1076,6 +1108,7 @@ Add -i (interactive confirmation) to destructive commands: Searches fish history interactively using fzf, inserts the selected command into the command line, and copies it to the clipboard via wl-copy. + Example: hist ## 5.5 Package Management @@ -1087,6 +1120,7 @@ Add -i (interactive confirmation) to destructive commands: Identifies and removes Arch Linux orphan packages using pacman. Logs package names and versions to ~/.removed_orphans before removal. + Example: cleanup ### parur @@ -1101,6 +1135,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Packages removed or none selected 1 No AUR helper (paru or yay) found + Example: parur ### pkg @@ -1130,6 +1165,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Operation completed 1 No supported package manager found, unknown flag, or package operation failed + Example: pkg firefox pkg -i ripgrep fd-find pkg -u cowsay @@ -1148,6 +1184,7 @@ Add -i (interactive confirmation) to destructive commands: 0 AUR helper ran successfully 1 No AUR helper (paru or yay) found + Example: search neovim ### upgrade @@ -1161,6 +1198,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Upgrade completed successfully 1 No AUR helper (paru or yay) found + Example: upgrade ## 5.6 Dependency Management @@ -1172,6 +1210,7 @@ Add -i (interactive confirmation) to destructive commands: Backwards-compatibility wrapper that delegates to fish-deps status to report which fish shell dependencies are installed or missing. + Example: check_fish_deps ### fish-deps @@ -1209,6 +1248,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Subcommand completed 1 Unknown subcommand + Example: fish-deps sync fish-deps fish-deps install @@ -1221,6 +1261,7 @@ Add -i (interactive confirmation) to destructive commands: Installs or upgrades fzf from git HEAD into ~/.fzf. Pulls the latest changes if ~/.fzf already exists, or clones the repository if not. + Example: fzf-update ## 5.7 System and Monitoring @@ -1234,6 +1275,7 @@ Add -i (interactive confirmation) to destructive commands: files tracked by sbctl. Combines the edit and sign steps into a single command. + Example: limine-edit ### lock @@ -1242,6 +1284,7 @@ Add -i (interactive confirmation) to destructive commands: Locks the current desktop session using loginctl lock-session. + Example: lock ### ports @@ -1251,6 +1294,7 @@ Add -i (interactive confirmation) to destructive commands: Lists all active TCP listeners on the system using lsof, showing port numbers and addresses without hostname resolution. + Example: ports ### sbver @@ -1269,6 +1313,7 @@ Add -i (interactive confirmation) to destructive commands: 0 All binaries verified (or summary shown) 1 sbctl is not installed + Example: sbver sbver --brief @@ -1279,6 +1324,7 @@ Add -i (interactive confirmation) to destructive commands: Turns off the display after a 1-second delay by invoking the KDE PowerDevil "Turn Off Screen" global shortcut via busctl. + Example: screensleep ### sudo-toggle @@ -1293,6 +1339,7 @@ Add -i (interactive confirmation) to destructive commands: Returns: 0 Rule toggled + Example: sudo-toggle ### swapstat @@ -1303,6 +1350,7 @@ Add -i (interactive confirmation) to destructive commands: zRAM compression ratio, zRAM device details (via zramctl), and active swap priority (via swapon). + Example: swapstat ### top @@ -1315,6 +1363,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to btop or system top + Example: top ## 5.8 Terminal Management @@ -1335,6 +1384,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Command launched successfully 1 No command provided + Example: bkg firefox ### detach @@ -1355,6 +1405,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Command launched or help/version shown 1 No command provided or unknown option + Example: detach rsync -a ./data remote:/backup/ ### split @@ -1375,6 +1426,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Pane opened successfully 1 Not running inside Kitty or WezTerm + Example: split split -v nvim README.md @@ -1392,6 +1444,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Window opened successfully 1 Not running inside Kitty or WezTerm + Example: spwin ### ssh @@ -1406,6 +1459,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to kitten ssh or system ssh + Example: ssh user@host ### tab @@ -1423,6 +1477,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Tab opened successfully 1 No supported terminal found + Example: tab ## 5.9 Clipboard @@ -1442,6 +1497,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Clipboard contents printed successfully 1 No supported clipboard tool found + Example: p | grep foo p > file.txt @@ -1459,6 +1515,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Clipboard contents printed successfully 1 No supported clipboard tool found + Example: paste > file.txt ### y @@ -1475,6 +1532,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Text copied to clipboard 1 No clipboard provider found + Example: y "hello world" ls | y cat file.txt | y @@ -1488,6 +1546,7 @@ Add -i (interactive confirmation) to destructive commands: Fetches and prints both the public IPv4 and IPv6 addresses using icanhazip.com. Shows "Not detected" for any address that times out. + Example: gip ### gip4 @@ -1496,6 +1555,7 @@ Add -i (interactive confirmation) to destructive commands: Fetches and prints the machine's public IPv4 address using icanhazip.com. + Example: gip4 ### gip6 @@ -1509,6 +1569,7 @@ Add -i (interactive confirmation) to destructive commands: 0 IPv6 address printed 1 IPv6 unavailable or not supported on this network + Example: gip6 ### ping @@ -1523,6 +1584,7 @@ Add -i (interactive confirmation) to destructive commands: --legend Show the prettyping legend (overrides default --nolegend) args... Arguments forwarded to prettyping or system ping + Example: ping google.com ping --legend google.com @@ -1537,6 +1599,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: text... Text to encode; reads from stdin if omitted + Example: qr "https://example.com" echo "hello" | qr @@ -1567,6 +1630,7 @@ Add -i (interactive confirmation) to destructive commands: 0 File viewed or no file selected 1 No log files found + Example: logs -c paru logs logs -c scrollback @@ -1592,6 +1656,7 @@ Add -i (interactive confirmation) to destructive commands: The exit builtin is wired to smart_exit for interactive sessions. Typing `exit` or Ctrl+D behaves identically to calling smart_exit directly. + Example: smart_exit smart_exit --no-log @@ -1663,6 +1728,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Setup completed successfully 1 Fatal error (git init failed, move failed, etc.) + Example: agents-init agents-init --agents agents-init --plugins @@ -1691,6 +1757,7 @@ Add -i (interactive confirmation) to destructive commands: Returns: Exit status of the underlying agy binary + Example: agy agy chat agy resume @@ -1707,6 +1774,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments passed through to the antigravity-ide command + Example: antigravity-ide ### claude @@ -1730,6 +1798,7 @@ Add -i (interactive confirmation) to destructive commands: Returns: Exit status of the underlying claude binary + Example: claude claude --resume claude "Explain the recent changes" @@ -1744,6 +1813,7 @@ Add -i (interactive confirmation) to destructive commands: README.md, ensuring all features and examples are accurate and pruning obsolete content. + Example: claude-docs ### claude-pr @@ -1754,6 +1824,7 @@ Add -i (interactive confirmation) to destructive commands: branch, write a Conventional Commit, run verification, push, and open a pull request with a manual verification checklist. + Example: claude-pr ### dops @@ -1768,6 +1839,7 @@ Add -i (interactive confirmation) to destructive commands: subcommand Docker subcommand (ps is redirected to dops) args... Arguments forwarded to docker or dops + Example: docker ps ### qc @@ -1791,6 +1863,7 @@ Add -i (interactive confirmation) to destructive commands: Returns: aichat's exit status. + Example: qc "how do I list open ports on linux?" qc -m ollama:llama3 "explain this error" qc --role coder "refactor this function" @@ -1813,6 +1886,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Mode applied successfully 1 No on/off mode specified + Example: superpowers on superpowers off -g @@ -1837,6 +1911,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Conversion complete 1 File not found, missing dependency, or encode step failed + Example: dng2avif photo.dng dng2avif -q 85 -s 5 -i shot.dng -o out.avif @@ -1855,6 +1930,7 @@ Add -i (interactive confirmation) to destructive commands: -v, --version Print version -h, --help Show usage help + Example: spark 1 1 2 5 14 42 seq 64 | sort --random-sort | spark echo "3 7 2 9 1" | spark @@ -1866,6 +1942,7 @@ Add -i (interactive confirmation) to destructive commands: Launches Steam with systemd-inhibit to prevent the system from idling or sleeping during active downloads. + Example: steam-dl ### yt-dlp @@ -1888,6 +1965,7 @@ Add -i (interactive confirmation) to destructive commands: args... Arguments forwarded to yt-dlp (defaults prepended) --no-embed-thumbnail Skip thumbnail embedding for this run + Example: yt-dlp dQw4w9WgXcQ yt-dlp --no-embed-thumbnail dQw4w9WgXcQ # drops our thumbnail default @@ -1903,6 +1981,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments passed through to the bash command + Example: bash ### bd-pull @@ -1920,6 +1999,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Issues linked and synced (or no unlinked issues found) 1 Missing required argument or environment variables + Example: bd-pull myuser/myproject bd-pull rootiest/fish-config @@ -1933,6 +2013,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Additional arguments forwarded to fastfetch or neofetch + Example: cffetch ### cheat @@ -1946,6 +2027,7 @@ Add -i (interactive confirmation) to destructive commands: topic The command or topic to look up args... Additional arguments forwarded to cheat, tldr, or man + Example: cheat tar cheat git @@ -1986,6 +2068,7 @@ Add -i (interactive confirmation) to destructive commands: registered as a handler in the help wrapper so that syntax works transparently. Direct `config-help` calls are also valid. + Example: config-help config-help keybindings config-help pkg @@ -2052,6 +2135,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Exited normally (q or Escape pressed) 1 Unknown flag passed + Example: config-settings **Used by:** `config-toggle` @@ -2069,6 +2153,7 @@ Add -i (interactive confirmation) to destructive commands: Returns: Same as config-settings + Example: config-toggle # opens config-settings with a deprecation notice **Dependencies:** `config-settings` @@ -2091,6 +2176,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Config updated (or already up to date) 1 Update failed (network error, merge conflict, or not a git repo) + Example: config-update config-update --dry-run config-update --force @@ -2110,6 +2196,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Services updated and running 1 Directory not found or no docker-compose.yml present + Example: dockup ~/myapp ### ffetch @@ -2122,6 +2209,7 @@ Add -i (interactive confirmation) to destructive commands: Arguments: args... Arguments forwarded to fastfetch or neofetch + Example: ffetch ### joplin @@ -2138,6 +2226,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Joplin ran successfully 1 joplin binary not found in PATH + Example: joplin ls ### kitty-logging @@ -2167,6 +2256,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Success 1 Unknown subcommand/flag, kitty missing, or a write failure + Example: kitty-logging install kitty-logging status @@ -2177,6 +2267,7 @@ Add -i (interactive confirmation) to destructive commands: Launches lazydocker targeting the currently active Docker context by resolving the host endpoint from docker context inspect. + Example: ld ### open-url @@ -2212,6 +2303,7 @@ Add -i (interactive confirmation) to destructive commands: Notes: Typo abbreviation: url-open (expands to open-url on space/enter). + Example: open-url https://git.rootiest.dev/rootiest/fish-config open-url -v https://fish-config-docs.pages.dev/ @@ -2232,6 +2324,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Commands ran successfully and changes were replayed 1 Bash command exited with a non-zero status + Example: replay "source ~/.bashrc" replay "export FOO=bar" @@ -2272,6 +2365,7 @@ Add -i (interactive confirmation) to destructive commands: Notes: Typo abbreviation: open-repo (expands to repo-open on space/enter). + Example: repo-open # open current branch (+ subdir) in browser repo-open --print # just print the URL repo-open --root # repo home page for the current branch @@ -2285,6 +2379,7 @@ Add -i (interactive confirmation) to destructive commands: Kills all detached (unattached) tmux sessions, leaving any currently attached sessions running. + Example: tmux-clean ### wake-lock @@ -2302,6 +2397,7 @@ Add -i (interactive confirmation) to destructive commands: 0 Command ran and completed 1 No command provided + Example: wake-lock rsync -avz src/ dest/ # 6. DEPENDENCY CATALOG @@ -2962,6 +3058,7 @@ fish_variables (auto-managed by fish) is excluded from this repo via Store anything you would not commit to a public repo: API keys, auth tokens, passwords, and personal identifiers. + # secrets.fish set -gx MY_NAME "Your Name" set -gx MY_EMAIL "you@example.com" set -gx GPG_RECIPIENT "you@example.com" diff --git a/docs/manual/10-personalization.md b/docs/manual/10-personalization.md index 81cd4b7..0e5e4c6 100644 --- a/docs/manual/10-personalization.md +++ b/docs/manual/10-personalization.md @@ -33,6 +33,7 @@ fish_variables (auto-managed by fish) is excluded from this repo via Store anything you would not commit to a public repo: API keys, auth tokens, passwords, and personal identifiers. + # secrets.fish set -gx MY_NAME "Your Name" set -gx MY_EMAIL "you@example.com" set -gx GPG_RECIPIENT "you@example.com" diff --git a/docs/verify-manual.py b/docs/verify-manual.py index c91ae27..7cb1133 100644 --- a/docs/verify-manual.py +++ b/docs/verify-manual.py @@ -332,16 +332,19 @@ def test_prettify_splits_an_entry_block(): "", " Falls back to /usr/bin/rm when trash is unavailable.", "", + " Example:", " rm file.txt # moves to trash", " rm -e # empty trash", ] ) out = build_manual.prettify(body, "rm") - assert '```fish title="rm.fish"\nrm [-e | args...]\n```' in out, ( - "synopsis was not fenced as fish with a filename title" + assert '```fish title="Usage"\nrm [-e | args...]\n```' in out, ( + "synopsis was not fenced as fish with a Usage title" + ) + assert '```fish title="Examples"\nrm file.txt' in out, ( + "examples were not fenced as fish with an Examples title" ) - assert "```fish\nrm file.txt" in out, "examples were not fenced as fish" assert out.count("```") == 4, f"expected exactly two fences, got:\n{out}" assert "\nSafe rm wrapper routing to trash:" in out, "description stayed indented" assert "| `(no args)` | List current trash contents |" in out, ( @@ -431,6 +434,24 @@ def test_prettify_leaves_reference_tables_alone(): assert "```fish" in build_manual.prettify(shell), "a shell block was not fenced" +def test_prettify_titles_paths_and_commented_examples(): + """A bare file path or a leading '# in x.fish' comment become a title.""" + import build_manual + + path = " $__fish_user_dots_path/local.fish" + assert '```fish title="local.fish"\n$__fish_user_dots_path/local.fish\n```' in ( + build_manual.prettify(path) + ), "a bare file path was not titled" + + commented = "\n".join( + [" # in local.fish", " set -gx SCROLLBACK_HISTORY_MAX_FILES 200"] + ) + out = build_manual.prettify(commented) + assert '```fish title="local.fish"\nset -gx SCROLLBACK_HISTORY_MAX_FILES 200\n```' in out, ( + f"a filename comment was not promoted to the fence title:\n{out}" + ) + + def test_prettify_is_site_only(): """The SSOT keeps the indented form the man-page pipeline depends on.""" import build_manual -- 2.52.0