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