docs: include default in flags (#882)

Author: Proximyst

.github/workflows/publish-technical-documentation-next.yml

@@ -9,7 +9,7 @@ concurrency:
 on:
   push:
     branches:
-      - main
+      - master
     paths:
       - "docs/sources/**"
   workflow_dispatch:

docs/sources/flags.md

@@ -50,99 +50,99 @@ This is a verbatim copy of the output of the `grafana-image-renderer server --he
 ```
 --browser.flag=<string> / --browser.flags=<string> [${BROWSER_FLAG}]
     Flags to pass to the browser. These are syntaxed `${flag}` or `${flag}=${value}`. [config: browser.flag]
---browser.gpu [${BROWSER_GPU}]
+--browser.gpu [default: false] [${BROWSER_GPU}]
     Enable GPU support in the browser. [config: browser.gpu]
 --browser.header=<string> / --browser.headers=<string> [${BROWSER_HEADER}]
     Headers to add to every request the browser makes. Syntax is `${key}=${value}`. May be repeated. [config: browser.header]
---browser.max-height=<int> [${BROWSER_MAX_HEIGHT}]
+--browser.max-height=<int> [default: 3000] [${BROWSER_MAX_HEIGHT}]
     The maximum height of the browser viewport. Requests cannot request a larger height than this, except for when capturing full-page screenshots. Negative means ignored. [config: browser.max-height]
---browser.max-width=<int> [${BROWSER_MAX_WIDTH}]
+--browser.max-width=<int> [default: 3000] [${BROWSER_MAX_WIDTH}]
     The maximum width of the browser viewport. Requests cannot request a larger width than this. Negative means ignored. [config: browser.max-width]
---browser.min-height=<int> [${BROWSER_MIN_HEIGHT}]
+--browser.min-height=<int> [default: 500] [${BROWSER_MIN_HEIGHT}]
     The minimum height of the browser viewport. This is the default height in requests. [config: browser.min-height]
---browser.min-width=<int> [${BROWSER_MIN_WIDTH}]
+--browser.min-width=<int> [default: 1000] [${BROWSER_MIN_WIDTH}]
     The minimum width of the browser viewport. This is the default width in requests. [config: browser.min-width]
---browser.namespaced [${BROWSER_NAMESPACED}]
+--browser.namespaced [default: false] [${BROWSER_NAMESPACED}]
     Enable namespacing the browser. This requires Linux and the CAP_SYS_ADMIN and CAP_SYS_CHROOT capabilities, or a privileged user. [config: browser.namespaced]
---browser.page-scale-factor=<float> [${BROWSER_PAGE_SCALE_FACTOR}]
+--browser.page-scale-factor=<float> [default: 1] [${BROWSER_PAGE_SCALE_FACTOR}]
     The page scale factor of the browser. [config: browser.page-scale-factor]
---browser.path=<string> [${BROWSER_PATH}]
+--browser.path=<string> [default: "chromium"] [${BROWSER_PATH}]
     The path to the browser's binary. This is resolved against PATH. [config: browser.path]
---browser.portrait [${BROWSER_PORTRAIT}]
+--browser.portrait [default: false] [${BROWSER_PORTRAIT}]
     Use a portrait viewport instead of the default landscape. [config: browser.portrait]
---browser.readiness.disable-dom-hashcode-wait [${BROWSER_READINESS_DISABLE_DOM_HASHCODE_WAIT}]
+--browser.readiness.disable-dom-hashcode-wait [default: false] [${BROWSER_READINESS_DISABLE_DOM_HASHCODE_WAIT}]
     Disable waiting for the DOM to stabilize (i.e. not change) before capturing. [config: browser.readiness.disable-dom-hashcode-wait]
---browser.readiness.disable-network-wait [${BROWSER_READINESS_DISABLE_NETWORK_WAIT}]
+--browser.readiness.disable-network-wait [default: false] [${BROWSER_READINESS_DISABLE_NETWORK_WAIT}]
     Disable waiting for network requests to finish before capturing. [config: browser.readiness.disable-network-wait]
---browser.readiness.disable-query-wait [${BROWSER_READINESS_DISABLE_QUERY_WAIT}]
+--browser.readiness.disable-query-wait [default: false] [${BROWSER_READINESS_DISABLE_QUERY_WAIT}]
     Disable waiting for queries to finish before capturing. [config: browser.readiness.disable-query-wait]
---browser.readiness.dom-hashcode-timeout=<duration> [${BROWSER_READINESS_DOM_HASHCODE_TIMEOUT}]
+--browser.readiness.dom-hashcode-timeout=<duration> [default: 0s] [${BROWSER_READINESS_DOM_HASHCODE_TIMEOUT}]
     How long to wait before giving up on the DOM stabilizing (i.e. not changing). If <= 0, the timeout is disabled. [config: browser.readiness.dom-hashcode-timeout]
---browser.readiness.give-up-on-all-queries=<duration> [${BROWSER_READINESS_GIVE_UP_ON_ALL_QUERIES}]
+--browser.readiness.give-up-on-all-queries=<duration> [default: 0s] [${BROWSER_READINESS_GIVE_UP_ON_ALL_QUERIES}]
     How long to wait before giving up on all running queries. If <= 0, the give-up is disabled. [config: browser.readiness.give-up-on-all-queries]
---browser.readiness.give-up-on-first-query=<duration> [${BROWSER_READINESS_GIVE_UP_ON_FIRST_QUERY}]
+--browser.readiness.give-up-on-first-query=<duration> [default: 3s] [${BROWSER_READINESS_GIVE_UP_ON_FIRST_QUERY}]
     How long to wait before giving up on a first query being registered. If <= 0, the give-up is disabled. [config: browser.readiness.give-up-on-first-query]
---browser.readiness.iteration-interval=<duration> [${BROWSER_READINESS_ITERATION_INTERVAL}]
+--browser.readiness.iteration-interval=<duration> [default: 100ms] [${BROWSER_READINESS_ITERATION_INTERVAL}]
     How long to wait between each iteration of checking whether the page is ready. Must be positive. [config: browser.readiness.iteration-interval]
---browser.readiness.network-idle-timeout=<duration> [${BROWSER_READINESS_NETWORK_IDLE_TIMEOUT}]
+--browser.readiness.network-idle-timeout=<duration> [default: 0s] [${BROWSER_READINESS_NETWORK_IDLE_TIMEOUT}]
     How long to wait before giving up on the network being idle. If <= 0, the timeout is disabled. [config: browser.readiness.network-idle-timeout]
---browser.readiness.prior-wait=<duration> [${BROWSER_READINESS_PRIOR_WAIT}]
+--browser.readiness.prior-wait=<duration> [default: 1s] [${BROWSER_READINESS_PRIOR_WAIT}]
     The time to wait before checking for how ready the page is. This lets you force the webpage to take a beat and just do its thing before the service starts looking for whether it's time to render anything. If <= 0, this is disabled. [config: browser.readiness.prior-wait]
---browser.readiness.timeout=<duration> [${BROWSER_READINESS_TIMEOUT}]
+--browser.readiness.timeout=<duration> [default: 30s] [${BROWSER_READINESS_TIMEOUT}]
     The maximum time to wait for a web-page to become ready (i.e. no longer loading anything). If <= 0, the timeout is disabled. [config: browser.readiness.timeout]
---browser.readiness.wait-for-n-query-cycles=<int> [${BROWSER_READINESS_WAIT_FOR_N_QUERY_CYCLES}]
+--browser.readiness.wait-for-n-query-cycles=<int> [default: 1] [${BROWSER_READINESS_WAIT_FOR_N_QUERY_CYCLES}]
     The number of readiness checks that must pass consecutively before considering the page ready. [config: browser.readiness.wait-for-n-query-cycles]
---browser.sandbox [${BROWSER_SANDBOX}]
+--browser.sandbox [default: false] [${BROWSER_SANDBOX}]
     Enable the browser's sandbox. Sets the `no-sandbox` flag to `false` for you. [config: browser.sandbox]
---browser.time-between-scrolls=<duration> [${BROWSER_TIME_BETWEEN_SCROLLS}]
+--browser.time-between-scrolls=<duration> [default: 50ms] [${BROWSER_TIME_BETWEEN_SCROLLS}]
     The time between scroll events when capturing a full-page screenshot. [config: browser.time-between-scrolls]
---browser.time-zone=<string> / --browser.timezone=<string> / --browser.tz=<string> [${BROWSER_TIMEZONE}, ${TZ}]
+--browser.time-zone=<string> / --browser.timezone=<string> / --browser.tz=<string> [default: "Etc/UTC"] [${BROWSER_TIMEZONE}, ${TZ}]
     The timezone for the browser to use, e.g. 'America/New_York'. [config: browser.timezone]
 --help / -h
     show help
---log.level=<string> [${LOG_LEVEL}]
+--log.level=<string> [default: "info"] [${LOG_LEVEL}]
     The minimum level to log at (enum: debug, info, warn, error) [config: log.level]
---rate-limit.disabled [${RATE_LIMIT_DISABLED}]
+--rate-limit.disabled [default: false] [${RATE_LIMIT_DISABLED}]
     Disable rate limiting entirely. [config: rate-limit.disabled]
---rate-limit.headroom=<uint> [${RATE_LIMIT_HEADROOM}]
+--rate-limit.headroom=<uint> [default: 33554432] [${RATE_LIMIT_HEADROOM}]
     The amount of memory (in bytes) to leave as headroom after allocating memory for browser processes. Set to 0 to disable headroom. [config: rate-limit.headroom]
---rate-limit.max-available=<uint> [${RATE_LIMIT_MAX_AVAILABLE}]
+--rate-limit.max-available=<uint> [default: 0] [${RATE_LIMIT_MAX_AVAILABLE}]
     The maximum amount of memory (in bytes) available to processes. If more memory exists, only this amount is used. 0 disables the maximum. [config: rate-limit.max-available]
---rate-limit.max-limit=<uint> [${RATE_LIMIT_MAX_LIMIT}]
+--rate-limit.max-limit=<uint> [default: 0] [${RATE_LIMIT_MAX_LIMIT}]
     The maximum number of requests to permit. Ratelimiting will reject requests if the number of currently running requests is at or above this value. Set to 0 to disable maximum. The v4 service used 5 by default. [config: rate-limit.max-limit]
---rate-limit.min-limit=<uint> [${RATE_LIMIT_MIN_LIMIT}]
+--rate-limit.min-limit=<uint> [default: 3] [${RATE_LIMIT_MIN_LIMIT}]
     The minimum number of requests to permit. Ratelimiting will not reject requests if the number of currently running requests is below this value. Set to 0 to disable minimum (not recommended). [config: rate-limit.min-limit]
---rate-limit.min-memory-per-browser=<uint> [${RATE_LIMIT_MIN_MEMORY_PER_BROWSER}]
+--rate-limit.min-memory-per-browser=<uint> [default: 67108864] [${RATE_LIMIT_MIN_MEMORY_PER_BROWSER}]
     The minimum amount of memory (in bytes) each browser process is expected to use. Set to 0 to disable the minimum. [config: rate-limit.min-memory-per-browser]
---rate-limit.process-tracker.decay=<int> [${RATE_LIMIT_PROCESS_TRACKER_DECAY}]
+--rate-limit.process-tracker.decay=<int> [default: 5] [${RATE_LIMIT_PROCESS_TRACKER_DECAY}]
     The decay factor N to use in slow-moving averages of process statistics, where `avg = ((N-1)*avg + new) / N`. Must be at least 1. [config: rate-limit.process-tracker.decay]
---rate-limit.process-tracker.interval=<duration> [${RATE_LIMIT_PROCESS_TRACKER_INTERVAL}]
+--rate-limit.process-tracker.interval=<duration> [default: 50ms] [${RATE_LIMIT_PROCESS_TRACKER_INTERVAL}]
     How often to sample process statistics on the browser processes. Must be >= 1ms. [config: rate-limit.process-tracker.interval]
---server.addr=<string> [${SERVER_ADDR}]
+--server.addr=<string> [default: ":8081"] [${SERVER_ADDR}]
     The address to listen on for HTTP requests. [config: server.addr]
---server.auth-token=<string> / --server.auth-tokens=<string> / --server.token=<string> / --server.tokens=<string> [${AUTH_TOKEN}]
+--server.auth-token=<string> / --server.auth-tokens=<string> / --server.token=<string> / --server.tokens=<string> [default: "-"] [${AUTH_TOKEN}]
     The X-Auth-Token header value that must be sent to the service to permit requests. May be repeated. [config: server.auth-token]
 --server.cert-file=<string> / --server.cert=<string> / --server.certificate-file=<string> / --server.certificate=<string> [${SERVER_CERTIFICATE_FILE}]
     A path to a TLS certificate file to use for HTTPS. If not set, HTTP is used. [config: server.certificate-file]
 --server.key-file=<string> / --server.key=<string> [${SERVER_KEY_FILE}]
     A path to a TLS key file to use for HTTPS. [config: server.key-file]
---server.min-tls-version=<string> [${SERVER_MIN_TLS_VERSION}]
+--server.min-tls-version=<string> [default: "1.2"] [${SERVER_MIN_TLS_VERSION}]
     The minimum TLS version to accept for HTTPS connections. (enum: 1.0, 1.1, 1.2, 1.3) [config: server.min-tls-version]
 --tracing.client-certificate=<string> [${TRACING_CLIENT_CERTIFICATE}]
     A path to a PEM-encoded client certificate to use for mTLS when connecting to the tracing endpoint over gRPC or HTTPS. [config: tracing.client_certificate]
 --tracing.client-key=<string> [${TRACING_CLIENT_KEY}]
     A path to a PEM-encoded client key to use for mTLS when connecting to the tracing endpoint over gRPC or HTTPS. [config: tracing.client_key]
---tracing.compressor=<string> [${TRACING_COMPRESSOR}]
+--tracing.compressor=<string> [default: "none"] [${TRACING_COMPRESSOR}]
     The compression algorithm to use when sending traces. (enum: none, gzip) [config: tracing.compressor]
 --tracing.endpoint=<string> [${TRACING_ENDPOINT}]
     The tracing endpoint to send spans to. Use grpc://, http://, or https:// to specify the protocol (grpc:// is implied). [config: tracing.endpoint]
 --tracing.header=<string> / --tracing.headers=<string> [${TRACING_HEADER}]
     A header to add to requests to the tracing endpoint. Syntax is `${key}=${value}`. May be repeated. This is useful for things like authentication. [config: tracing.header]
---tracing.insecure [${TRACING_INSECURE}]
+--tracing.insecure [default: false] [${TRACING_INSECURE}]
     Whether to skip TLS verification when connecting. If set, the scheme in the endpoint is overridden to be insecure. [config: tracing.insecure]
---tracing.service-name=<string> [${TRACING_SERVICE_NAME}]
+--tracing.service-name=<string> [default: "grafana-image-renderer"] [${TRACING_SERVICE_NAME}]
     The service name to use in traces. [config: tracing.service_name]
---tracing.timeout=<duration> [${TRACING_TIMEOUT}]
+--tracing.timeout=<duration> [default: 10s] [${TRACING_TIMEOUT}]
     The timeout for requests to the tracing endpoint. [config: tracing.timeout]
 --tracing.trusted-certificate=<string> [${TRACING_TRUSTED_CERTIFICATE}]
     A path to a PEM-encoded certificate to use as a trusted root when connecting to the tracing endpoint over gRPC or HTTPS. [config: tracing.trusted_certificate]

scripts/help-documentation/main.go

@@ -138,11 +138,16 @@ func flagString(flag cli.Flag) (string, error) {
 	}
 	slices.Sort(envVars)
 
+	var defaultText string
+	if docFlag.IsDefaultVisible() && docFlag.GetValue() != "" {
+		defaultText = fmt.Sprintf(" [default: %v]", docFlag.GetValue())
+	}
+
 	namesStr := strings.Join(names, " / ")
 	var envVarsStr string
 	if len(envVars) > 0 {
 		envVarsStr = fmt.Sprintf(" [%s]", strings.Join(envVars, ", "))
 	}
 
-	return fmt.Sprintf("%s%s\n    %s", namesStr, envVarsStr, docFlag.GetUsage()), nil
+	return fmt.Sprintf("%s%s%s\n    %s", namesStr, defaultText, envVarsStr, docFlag.GetUsage()), nil
 }