Artifact [db502bde38]

Artifact db502bde385bcc0c8b255da71c49137cc6cc6326a50f306b82ed699bf41ccb1c:

• Executable file scripts/gen-cli-docs.sh — part of check-in [d7fd910ffc] at 2026-10-23 21:12:43 on branch main — docs: generate the site's data, CLI reference and llms.txt from the code

  tools/docsgen/engine records one check-in as an artifact, as its derived rows and as the cards of a pull, from a real engine run with fixed inputs. tools/docsgen/conformance turns TestCoverage's report into per-draft and per-requirement data. scripts/gen-cli-docs.sh writes one page per command group from the libfossil binary's --help. gen-llms-txt.sh and check-llms-txt.sh are ported from dagnats, and sync-version.sh now takes the highest release tag and writes the go.mod version too.

  scripts/check-docs-generated.sh regenerates everything into a scratch dir and fails on any difference; make docs-check and the test-docs CI job run it. (user: [email protected], size: 3104) [annotate] [blame] [check-ins using] [more...]

#!/usr/bin/env bash
# Generates the CLI reference from the real libfossil binary's --help output:
# an index page with the top-level help, and one page per command group
# ("repo new", "repo stash", "version"), holding the group's help and, for a
# group with subcommands, each subcommand's help.
#
# Builds cmd/libfossil into a scratch dir. Pages are marked `generated: true`;
# edit the command's help text in cli/, not the pages. Output is deterministic.
#
# Env: OUT_DIR (docs/site/content/docs/reference/cli).
set -euo pipefail

OUT_DIR="${OUT_DIR:-docs/site/content/docs/reference/cli}"

work="$(mktemp -d)"
trap 'rm -rf "$work"' EXIT INT TERM

GOWORK=off go build -o "$work/libfossil" ./cmd/libfossil
# kong wraps help to the terminal; pin the width so output does not depend on it.
help() { COLUMNS=80 "$work/libfossil" "$@" --help; }

help > "$work/top.txt"

# Command groups, in help order: "repo <name>" or a top-level command.
awk '/^Commands:/ { on = 1; next }
     on && /^  [a-z]/ {
       g = ($1 == "repo") ? $1 " " $2 : $1
       if (!(g in seen)) { seen[g] = 1; print g }
     }' "$work/top.txt" > "$work/groups.txt"
[ -s "$work/groups.txt" ] || { echo "gen-cli-docs: no commands in --help" >&2; exit 1; }

mkdir -p "$OUT_DIR"
rm -f "$OUT_DIR"/*.md

notice='<!-- Generated by scripts/gen-cli-docs.sh from the libfossil --help output. Do not edit; change the help text in cli/ and run make docs-gen. -->'

# yaml_quote wraps a string in single quotes, doubling any inside.
yaml_quote() { printf "'%s'" "$(printf '%s' "$1" | sed "s/'/''/g")"; }

{
  printf -- '---\ntitle: CLI\nweight: 20\ngenerated: true\n---\n\n%s\n\n' "$notice"
  echo 'The `libfossil` command, one page per command group. Every page is the output of the binary'"'"'s own `--help`.'
  echo
  echo '```text'
  cat "$work/top.txt"
  echo '```'
  echo
  echo '## Command groups'
  echo
  while IFS= read -r group; do
    summary="$(help $group | sed -n 3p)"
    echo "- [\`libfossil $group\`](/docs/reference/cli/${group// /-}/): $summary"
  done < "$work/groups.txt"
} > "$OUT_DIR/_index.md"

weight=0
while IFS= read -r group; do
  weight=$((weight + 10))
  help $group > "$work/group.txt"
  summary="$(sed -n 3p "$work/group.txt")"
  # A group's subcommands: "  <group> <word> ..." lines in the top-level help.
  awk -v g="$group" '/^Commands:/ { on = 1; next }
       on && index($0, "  " g " ") == 1 {
         rest = substr($0, length(g) + 4); split(rest, w, " ")
         if (w[1] ~ /^[a-z]/) print w[1]
       }' "$work/top.txt" > "$work/subs.txt"
  {
    printf -- '---\ntitle: %s\nweight: %d\ngenerated: true\ndescription: %s\n---\n\n%s\n\n' \
      "$(yaml_quote "$group")" "$weight" "$(yaml_quote "$summary")" "$notice"
    echo '```text'
    cat "$work/group.txt"
    echo '```'
    while IFS= read -r sub; do
      echo
      echo "## $group $sub"
      echo
      echo '```text'
      help $group $sub
      echo '```'
    done < "$work/subs.txt"
  } > "$OUT_DIR/${group// /-}.md"
done < "$work/groups.txt"

echo "gen-cli-docs: wrote $(wc -l < "$work/groups.txt" | tr -d ' ') command groups to $OUT_DIR/"