docs/update_runner_docs.sh

#!/bin/bash
#
# Regenerates the generated pages of the runner documentation from the runner
# source: the command line reference and the example configuration file.
#
# Usage:
#
#   ./update_runner_docs.sh                     develop docs, from the main branch
#   ./update_runner_docs.sh --released          every documented release series
#   ./update_runner_docs.sh <git ref> <dir>     one ref into one directory
#
# --released needs no version list: the documented series are the
# runner-docs_versioned_docs/version-<series>/reference directories, and the tag
# each one is generated from is the newest stable v<series>.x.y tag of
# gitea/runner, looked up through the Gitea API. A new series is documented by
# running `make cut-version PRODUCT=runner VERSION=<series>`, nothing here has
# to be edited.

set -euo pipefail

RUNNER_REMOTE="${RUNNER_REMOTE:-https://gitea.com/gitea/runner.git}"
RUNNER_API="${RUNNER_API:-https://gitea.com/api/v1/repos/gitea/runner}"
VERSIONED_DOCS="runner-docs_versioned_docs"
SRC_DIR=".tmp/upstream-runner"
BIN="$PWD/.tmp/gitea-runner"
TAGS_FILE=".tmp/runner-tags.txt"

mkdir -p .tmp

# prints every tag name of the runner repository, one per line
list_runner_tags() {
  local page=1 names
  while :; do
    names="$(curl --silent --show-error --fail \
      "$RUNNER_API/tags?limit=50&page=$page" |
      grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d '"' -f 4)"
    [ -n "$names" ] || return 0
    printf '%s\n' "$names"
    page=$((page + 1))
  done
}

# latest_stable_tag <series>, e.g. "3" -> "v3.0.2", empty if the series has no
# release yet. Pre-release tags (v3.0.0-rc1) are ignored on purpose.
latest_stable_tag() {
  local series="$1"
  if [ ! -s "$TAGS_FILE" ]; then
    list_runner_tags > "$TAGS_FILE"
  fi
  grep -E "^v${series}\.[0-9]+\.[0-9]+$" "$TAGS_FILE" |
    sed 's/^v//' |
    sort -t . -k1,1n -k2,2n -k3,3n |
    tail -n 1 |
    sed 's/^/v/'
}

# checkout_runner <git ref>, builds the runner binary at $BIN
checkout_runner() {
  local ref="$1"

  if [ -d "$SRC_DIR/.git" ]; then
    git -C "$SRC_DIR" remote set-url origin "$RUNNER_REMOTE"
  else
    rm -rf "$SRC_DIR"
    git init --quiet "$SRC_DIR"
    git -C "$SRC_DIR" remote add origin "$RUNNER_REMOTE"
  fi
  git -C "$SRC_DIR" fetch --quiet --depth 1 origin "$ref"
  git -C "$SRC_DIR" checkout --quiet --detach FETCH_HEAD

  (cd "$SRC_DIR" && go build -o "$BIN" .)
}

# the commands the reference documents, in the order they are presented
COMMANDS=(register daemon exec cache-server generate-config bug-report)

# one short paragraph per command, printed above its help output
describe_command() {
  case "$1" in
    register)
      echo 'Registers the runner against a Gitea instance and writes the registration file. Interactive unless `--no-interactive` is given; the token can also come from `--token-file` or the `GITEA_RUNNER_REGISTRATION_TOKEN` environment variable. See [Registering a runner](../registration.md).'
      ;;
    daemon)
      echo 'Runs the runner: it polls the instance for jobs and executes them until it is stopped. `--labels` (default: `GITEA_RUNNER_LABELS`) overrides the labels of an already registered runner, and `--once` exits after a single job.'
      ;;
    exec)
      echo 'Runs a workflow from the current repository locally, without a Gitea instance and without the runner configuration file. Useful for debugging a workflow before pushing it. Runner YAML is not loaded, so hooks and cache settings do not apply.'
      ;;
    cache-server)
      echo 'Runs only the cache server, so several runners can share one cache. `--dir`, `--host` and `--port` override the matching `cache.*` keys; every other setting, `cache.external_secret` included, has to come from the config file. See [Caching](../cache.md#sharing-a-cache-between-runners).'
      ;;
    generate-config)
      echo 'Prints the commented example configuration on stdout, which is the starting point for a config file: `gitea-runner generate-config > config.yaml`.'
      ;;
    bug-report)
      echo 'Prints the runner version, Go version, OS/architecture and CPU count, for pasting into an issue.'
      ;;
  esac
}

# generate_reference <git ref> <target directory>
generate_reference() {
  local ref="$1" target="$2" cmd

  mkdir -p "$target"
  checkout_runner "$ref"

  {
    cat <<'EOF'
---
sidebar_position: 1
description: Every gitea-runner command and flag, generated from the runner sources.
---

# Command line reference

{/* Generated by update_runner_docs.sh from the gitea/runner sources, do not edit. */}

`gitea-runner` is a single binary with one subcommand per task. `--config` / `-c` is
global: every command that reads configuration accepts it, and commands that do not
read any ignore it.

EOF
    printf '## gitea-runner\n\n```text\n'
    "$BIN" --help
    printf '```\n'

    for cmd in "${COMMANDS[@]}"; do
      printf '\n## %s\n\n' "$cmd"
      describe_command "$cmd"
      printf '\n```text\n'
      "$BIN" "$cmd" --help
      printf '```\n'
    done
  } > "$target/cli.md"

  {
    cat <<'EOF'
---
sidebar_position: 2
description: The commented example configuration of the runner, generated from the runner sources.
---

# Example configuration

{/* Generated by update_runner_docs.sh from the gitea/runner sources, do not edit. */}

This is the output of `gitea-runner generate-config`. It is safe to use unmodified,
and it is the authoritative list of every option the runner understands. See
[Configuration](../configuration.md) for what the options mean and how the file is
loaded.

```yaml
EOF
    "$BIN" generate-config
    printf '```\n'
  } > "$target/config-example.md"

  echo "wrote $target/cli.md and $target/config-example.md from $RUNNER_REMOTE@$ref"
}

# regenerates every documented release series from its newest stable tag
generate_released() {
  local dir series tag found=0

  for dir in "$VERSIONED_DOCS"/version-*/reference; do
    [ -d "$dir" ] || continue
    found=1
    series="${dir#"$VERSIONED_DOCS"/version-}"
    series="${series%/reference}"

    tag="$(latest_stable_tag "$series")"
    if [ -z "$tag" ]; then
      echo "no stable v$series tag in $RUNNER_API, skipping $dir" >&2
      continue
    fi
    generate_reference "$tag" "$dir"
  done

  if [ "$found" -eq 0 ]; then
    echo "no $VERSIONED_DOCS/version-*/reference directory to regenerate" >&2
    exit 1
  fi
}

case "${1:-}" in
  --released)
    generate_released
    ;;
  -h | --help)
    sed -n '3,17s/^#\{1,2\} \{0,1\}//p' "$0"
    ;;
  *)
    generate_reference "${1:-main}" "${2:-runner-docs/reference}"
    ;;
esac