Simplify the runner docs and fix their outdated facts (#600)

The runner pages had drifted from the runner. They claimed Podman is unsupported, a registration retry limit of 10, a `container.env` proxy override that has no effect, and they used the deprecated `generate-config` command, while the actual instructions were buried under implementation details.

The develop and 5.x pages are rewritten from the current runner sources (`main` is `v5.2.0`). They are shorter and aimed at operators, with a new page covering what jobs get. The reference generator now documents the `config` command, and the quickstart pages in every language use the `gitea-runner` binary name.

Reviewed-on: https://gitea.com/gitea/docs/pulls/600
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>

update_runner_docs.sh

@@ -72,13 +72,13 @@ checkout_runner() {
 }
 
 # the commands the reference documents, in the order they are presented
-COMMANDS=(register daemon exec cache-server generate-config bug-report)
+COMMANDS=(register daemon exec cache-server 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).'
+      echo 'Registers the runner with a Gitea instance and writes the registration file. The token comes from `--token`, `--token-file` or the `GITEA_RUNNER_REGISTRATION_TOKEN` environment variable, and the command asks for the other settings unless `--no-interactive` is given. See [Registration](../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.'
@@ -87,7 +87,10 @@ describe_command() {
       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).'
+      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).'
+      ;;
+    config)
+      echo 'Writes, reads and edits config files. `config init` writes a minimal `config.yaml`, `config set`, `add` and `remove` change it in place, and `config generate` prints every option. See [Configuration](../configuration.md).'
       ;;
     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`.'
@@ -100,10 +103,13 @@ describe_command() {
 
 # generate_reference <git ref> <target directory>
 generate_reference() {
-  local ref="$1" target="$2" cmd
+  local ref="$1" target="$2" cmd sub generate=(config generate)
 
   mkdir -p "$target"
   checkout_runner "$ref"
+  if ! "$BIN" config --help > /dev/null 2>&1; then
+    generate=(generate-config)
+  fi
 
   {
     cat <<'EOF'
@@ -126,11 +132,20 @@ EOF
     printf '```\n'
 
     for cmd in "${COMMANDS[@]}"; do
+      if [ "$cmd" = config ] && [ "${generate[0]}" = generate-config ]; then
+        cmd="generate-config"
+      fi
       printf '\n## %s\n\n' "$cmd"
       describe_command "$cmd"
       printf '\n```text\n'
       "$BIN" "$cmd" --help
       printf '```\n'
+      [ "$cmd" = config ] || continue
+      for sub in $("$BIN" config --help | awk '/^Available Commands:/ { found = 1; next } found && /^$/ { exit } found && $1 != "help" { print $1 }'); do
+        printf '\n### config %s\n\n```text\n' "$sub"
+        "$BIN" config "$sub" --help
+        printf '```\n'
+      done
     done
   } > "$target/cli.md"
 
@@ -145,14 +160,14 @@ description: The commented example configuration of the runner, generated from t
 
 {/* 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.
+EOF
+    printf 'Every option the runner understands, with its default, as printed by `gitea-runner %s`.\n' "${generate[*]}"
+    cat <<'EOF'
+See [Configuration](../configuration.md) for how to write and load a config file.
 
 ```yaml
 EOF
-    "$BIN" generate-config
+    "$BIN" "${generate[@]}"
     printf '```\n'
   } > "$target/config-example.md"