feat(cli): generate CLI reference documentation.

Adds the "docs" subcommand to allow the CLI reference documentation
generation in markdown format.

Signed-off-by: José Guilherme Vanz <[email protected]>

.github/workflows/ci.yml

@@ -118,3 +118,18 @@ jobs:
           directory: coverage/integration-tests
           flags: integration-tests
           verbose: true
+
+  docs:
+    name: Update documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - run: |
+          make build-docs
+          if ! git diff --quiet cli-docs.md; then
+            echo "Changes detected in cli-docs.md. Please run `make build-docs` and commit the changes."
+            gh run cancel ${{ github.run_id }}
+          fi
+

Cargo.toml

@@ -66,6 +66,7 @@ jemalloc_pprof = "0.6.0"
 tikv-jemalloc-ctl = "0.6.0"
 rhai = { version = "1.19.0", features = ["sync"] }
 tonic = { version = "0.12.3" }
+clap-markdown = "0.1.4"
 
 [target.'cfg(target_os = "linux")'.dependencies]
 inotify = "0.11"

Makefile

@@ -74,3 +74,7 @@ download-spdx-sbom-generator: bin
 .PHONY: sbom
 sbom:
 	./$(BINDIR)/spdx-sbom-generator -f json
+
+.PHONY:build-docs
+build-docs:
+	cargo run --release -- docs --output cli-docs.md

README.md

@@ -373,3 +373,8 @@ in our Kubewarden docs.
 ## Changelog
 
 See [GitHub Releases content](https://github.com/kubewarden/policy-server/releases).
+
+# CLI documentation
+
+If you want a complete list of the available commands, you can read the 
+[cli-docs.md](./cli-docs.md) file.

cli-docs.md

@@ -0,0 +1,94 @@
+# Command-Line Help for `policy-server`
+
+This document contains the help content for the `policy-server` command-line program.
+
+**Command Overview:**
+
+* [`policy-server`↴](#policy-server)
+* [`policy-server docs`↴](#policy-server-docs)
+
+## `policy-server`
+
+
+
+**Usage:** `policy-server [OPTIONS] [COMMAND]`
+
+###### **Subcommands:**
+
+* `docs` — Generates the markdown documentation for policy-server commands
+
+###### **Options:**
+
+* `--addr <BIND_ADDRESS>` — Bind against ADDRESS
+
+  Default value: `0.0.0.0`
+* `--always-accept-admission-reviews-on-namespace <NAMESPACE>` — Always accept AdmissionReviews that target the given namespace
+* `--cert-file <CERT_FILE>` — Path to an X.509 certificate file for HTTPS
+
+  Default value: ``
+* `--daemon` — If set, runs policy-server in detached mode as a daemon
+* `--daemon-pid-file <DAEMON-PID-FILE>` — Path to the PID file, used only when running in daemon mode
+
+  Default value: `policy-server.pid`
+* `--daemon-stderr-file <DAEMON-STDERR-FILE>` — Path to the file holding stderr, used only when running in daemon mode
+* `--daemon-stdout-file <DAEMON-STDOUT-FILE>` — Path to the file holding stdout, used only when running in daemon mode
+* `--disable-timeout-protection` — Disable policy timeout protection
+* `--docker-config-json-path <DOCKER_CONFIG>` — Path to a Docker config.json-like path. Can be used to indicate registry authentication details
+* `--enable-metrics` — Enable metrics
+* `--enable-pprof` — Enable pprof profiling
+* `--ignore-kubernetes-connection-failure` — Do not exit with an error if the Kubernetes connection fails. This will cause context-aware policies to break when there's no connection with Kubernetes.
+* `--key-file <KEY_FILE>` — Path to an X.509 private key file for HTTPS
+
+  Default value: ``
+* `--log-fmt <LOG_FMT>` — Log output format
+
+  Default value: `text`
+
+  Possible values: `text`, `json`, `otlp`
+
+* `--log-level <LOG_LEVEL>` — Log level
+
+  Default value: `info`
+
+  Possible values: `trace`, `debug`, `info`, `warn`, `error`
+
+* `--log-no-color` — Disable colored output for logs
+* `--policies <POLICIES_FILE>` — YAML file holding the policies to be loaded and their settings
+
+  Default value: `policies.yml`
+* `--policies-download-dir <POLICIES_DOWNLOAD_DIR>` — Download path for the policies
+
+  Default value: `.`
+* `--policy-timeout <MAXIMUM_EXECUTION_TIME_SECONDS>` — Interrupt policy evaluation after the given time
+
+  Default value: `2`
+* `--port <PORT>` — Listen on PORT
+
+  Default value: `3000`
+* `--sigstore-cache-dir <SIGSTORE_CACHE_DIR>` — Directory used to cache sigstore data
+
+  Default value: `sigstore-data`
+* `--sources-path <SOURCES_PATH>` — YAML file holding source information (https, registry insecure hosts, custom CA's...)
+* `--verification-path <VERIFICATION_CONFIG_PATH>` — YAML file holding verification information (URIs, keys, annotations...)
+* `--workers <WORKERS_NUMBER>` — Number of worker threads to create
+
+
+
+## `policy-server docs`
+
+Generates the markdown documentation for policy-server commands
+
+**Usage:** `policy-server docs --output <FILE>`
+
+###### **Options:**
+
+* `-o`, `--output <FILE>` — path where the documentation file will be stored
+
+
+
+<hr/>
+
+<small><i>
+    This document was generated automatically by
+    <a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
+</i></small>

src/cli.rs

@@ -204,4 +204,16 @@ pub(crate) fn build_cli() -> Command {
         .about(crate_description!())
         .long_version(VERSION_AND_BUILTINS.as_str())
         .args(args)
+        .subcommand(
+            Command::new("docs")
+                .about("Generates the markdown documentation for policy-server commands")
+                .arg(
+                    Arg::new("output")
+                        .long("output")
+                        .short('o')
+                        .required(true)
+                        .value_name("FILE")
+                        .help("path where the documentation file will be stored"),
+                ),
+        )
 }

src/main.rs

@@ -1,10 +1,12 @@
 mod cli;
 
 use std::fs;
+use std::io::prelude::*;
 
 use ::tracing::info;
 use anyhow::anyhow;
 use anyhow::Result;
+use clap::ArgMatches;
 use opentelemetry::global::shutdown_tracer_provider;
 use policy_server::metrics::setup_metrics;
 use policy_server::tracing::setup_tracing;
@@ -19,6 +21,10 @@ async fn main() -> Result<()> {
         .expect("Failed to install crypto provider");
 
     let matches = cli::build_cli().get_matches();
+    if matches.subcommand_name() == Some("docs") {
+        return run_docs_subcommand(matches.subcommand_matches("docs"));
+    }
+
     let config = policy_server::config::Config::from_args(&matches)?;
 
     setup_tracing(&config.log_level, &config.log_fmt, config.log_no_color)?;
@@ -56,3 +62,16 @@ async fn main() -> Result<()> {
 
     Ok(())
 }
+
+/// Handle the docs subcommand and generates markdown documentation for the CLI
+fn run_docs_subcommand(matches: Option<&ArgMatches>) -> Result<()> {
+    if let Some(matches) = matches {
+        let output = matches.get_one::<String>("output").unwrap();
+        let mut file = std::fs::File::create(output)
+            .map_err(|e| anyhow!("cannot create file {}: {}", output, e))?;
+        let docs_content = clap_markdown::help_markdown_command(&cli::build_cli());
+        file.write_all(docs_content.as_bytes())
+            .map_err(|e| anyhow!("cannot write to file {}: {}", output, e))?;
+    }
+    Ok(())
+}