feat(docs): add offline documentation, config_help viewer, and CI pipelines
- docs/fish-config.md: curated terminal-optimized manual covering all public functions, keybindings, abbreviations, configuration variables, dependency catalog, and customization guide. Written for ov/bat/less readability rather than browser rendering — no callouts, no hyperlinks. Pandoc-compatible YAML front matter for man page compilation. - functions/config_help.fish: viewer function with fallback chain ov -> bat -> man -l -> less -> cat. Accepts an optional section keyword to jump directly to the first matching heading. - .gitea/workflows/man-page.yml: compiles docs/fish-config.md to docs/fish-config.1 via pandoc on every push to main that touches the source doc, then commits the result automatically. - .gitea/workflows/docs-drift.yml: opens a reminder issue whenever README.md changes without a corresponding docs/fish-config.md update in the same push. - README.md: documents config_help and the offline manual. - AGENTS.md: adds Convention 10 requiring offline doc to be updated alongside any function, keybinding, or config change.
This commit is contained in:
@@ -0,0 +1,45 @@
|
||||
name: Offline docs drift reminder
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- 'README.md'
|
||||
|
||||
jobs:
|
||||
remind:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 2
|
||||
|
||||
- name: Check whether offline doc changed in same push
|
||||
id: drift
|
||||
run: |
|
||||
if git diff --name-only HEAD~1 HEAD | grep -q '^docs/fish-config\.md$'; then
|
||||
echo "synced=true" >> "$GITHUB_OUTPUT"
|
||||
else
|
||||
echo "synced=false" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
|
||||
- name: Open drift reminder issue
|
||||
if: steps.drift.outputs.synced == 'false'
|
||||
uses: actions/gitea-issue-create@v1
|
||||
with:
|
||||
token: ${{ secrets.GITEA_TOKEN }}
|
||||
title: "docs: README updated — review docs/fish-config.md for drift"
|
||||
body: |
|
||||
README.md was modified in commit ${{ github.sha }} but
|
||||
`docs/fish-config.md` (the offline manual) was not updated in
|
||||
the same push.
|
||||
|
||||
Please review the README diff and update the offline documentation
|
||||
if any functions, keybindings, abbreviations, or configuration
|
||||
options were added, removed, or changed.
|
||||
|
||||
Commit: ${{ github.sha }}
|
||||
Branch: ${{ github.ref_name }}
|
||||
labels: documentation
|
||||
@@ -0,0 +1,37 @@
|
||||
name: Generate man page
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- 'docs/fish-config.md'
|
||||
|
||||
jobs:
|
||||
build-manpage:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
token: ${{ secrets.GITEA_TOKEN }}
|
||||
|
||||
- name: Install pandoc
|
||||
run: sudo apt-get update -qq && sudo apt-get install -y pandoc
|
||||
|
||||
- name: Compile man page
|
||||
run: |
|
||||
pandoc --standalone \
|
||||
--from markdown \
|
||||
--to man \
|
||||
docs/fish-config.md \
|
||||
-o docs/fish-config.1
|
||||
|
||||
- name: Commit man page
|
||||
run: |
|
||||
git config user.name "Gitea Actions"
|
||||
git config user.email "actions@gitea"
|
||||
git add docs/fish-config.1
|
||||
git diff --cached --quiet && echo "No changes to commit" && exit 0
|
||||
git commit -m "chore(docs): regenerate fish-config.1 man page"
|
||||
git push
|
||||
@@ -305,6 +305,19 @@ rm -f file.txt # Falls through to standard rm -f
|
||||
|
||||
`conf.d/paru-wrapper.fish` and `conf.d/yay-wrapper.fish` auto-generate thin wrapper scripts at `~/.local/bin/paru` and `~/.local/bin/yay` on first shell start (when the respective AUR helper is installed). These wrappers tee all output to timestamped log files in `SCROLLBACK_HISTORY_DIR` and prune old logs to stay under `SCROLLBACK_HISTORY_MAX_FILES`.
|
||||
|
||||
### Offline Documentation
|
||||
|
||||
A curated offline reference manual is available at `docs/fish-config.md`. It covers every function, keybinding, abbreviation, and configuration variable, written for terminal readability (no hyperlinks or GitHub-specific callouts).
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `config_help` | Open the offline manual in the best available pager |
|
||||
| `config_help <keyword>` | Jump directly to a section matching the keyword |
|
||||
|
||||
The viewer falls back through: **ov** (syntax highlight + section navigation) → **bat** (syntax highlight) → **man -l** (pre-compiled man page) → **less** → **cat**.
|
||||
|
||||
Examples: `config_help keybindings` · `config_help pkg` · `config_help fish-deps` · `config_help abbreviations`
|
||||
|
||||
### Dependency Management
|
||||
|
||||
`fish-deps` is a unified command for checking, installing, and updating all tools this config depends on.
|
||||
|
||||
+1237
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,75 @@
|
||||
# Copyright (C) 2026 Rootiest
|
||||
# SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
|
||||
# SYNOPSIS
|
||||
# config_help [section]
|
||||
#
|
||||
# DESCRIPTION
|
||||
# Opens the offline fish shell configuration manual in the best available
|
||||
# pager. Falls back through ov -> bat -> man -> less -> cat.
|
||||
# If a section keyword is provided, the pager opens at the first heading
|
||||
# that matches the keyword (case-insensitive).
|
||||
#
|
||||
# ARGUMENTS
|
||||
# section Optional keyword to jump to a matching section heading
|
||||
#
|
||||
# RETURNS
|
||||
# 0 Manual displayed
|
||||
# 1 Documentation file not found
|
||||
#
|
||||
# EXAMPLE
|
||||
# config_help
|
||||
# config_help keybindings
|
||||
# config_help pkg
|
||||
# config_help fish-deps
|
||||
function config_help --description 'Open the offline fish shell configuration manual'
|
||||
set -l doc_file "$__fish_config_dir/docs/fish-config.md"
|
||||
set -l man_file "$__fish_config_dir/docs/fish-config.1"
|
||||
|
||||
if not test -f "$doc_file"
|
||||
set_color red
|
||||
echo "error: documentation not found at $doc_file" >&2
|
||||
set_color normal
|
||||
return 1
|
||||
end
|
||||
|
||||
# ── Resolve section start line ───────────────────────────────
|
||||
set -l start_line 1
|
||||
if test -n "$argv[1]"
|
||||
set -l found (grep -n -im 1 "^#\+.*$argv[1]" "$doc_file" | cut -d: -f1)
|
||||
if test -n "$found"
|
||||
set start_line $found
|
||||
else
|
||||
set_color yellow
|
||||
echo "note: no section matching '$argv[1]' — opening at top" >&2
|
||||
set_color normal
|
||||
end
|
||||
end
|
||||
|
||||
# ── Viewer fallback chain ────────────────────────────────────
|
||||
if type -q ov
|
||||
ov --syntax --syntax-name markdown \
|
||||
--section-delimiter "^#" \
|
||||
--section-header \
|
||||
+"$start_line" "$doc_file"
|
||||
|
||||
else if type -q bat
|
||||
if test $start_line -gt 1
|
||||
# bat can't jump to a line in paging mode; show a hint instead
|
||||
set_color brblack
|
||||
echo "note: bat pager active — use / to search for your section" >&2
|
||||
set_color normal
|
||||
end
|
||||
bat --language=markdown --paging=always "$doc_file"
|
||||
|
||||
else if test -f "$man_file"
|
||||
# Pre-compiled man page as a pager-independent fallback
|
||||
man -l "$man_file"
|
||||
|
||||
else if type -q less
|
||||
less +"$start_line" "$doc_file"
|
||||
|
||||
else
|
||||
cat "$doc_file"
|
||||
end
|
||||
end
|
||||
Reference in New Issue
Block a user