diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 28b64871..b0b83b49 100644 --- a/.github/workflows/ci.yml +++ b/.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 + diff --git a/Cargo.lock b/Cargo.lock index 6813b69c..94f6d471 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -924,6 +924,15 @@ dependencies = [ "clap_builder", ] +[[package]] +name = "clap-markdown" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ebc67e6266e14f8b31541c2f204724fa2ac7ad5c17d6f5908fbb92a60f42cff" +dependencies = [ + "clap", +] + [[package]] name = "clap_builder" version = "4.5.27" @@ -4377,6 +4386,7 @@ dependencies = [ "axum-server", "backon", "clap", + "clap-markdown", "daemonize", "futures", "http-body-util", diff --git a/Cargo.toml b/Cargo.toml index d6678fe5..c8f8b048 100644 --- a/Cargo.toml +++ b/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" diff --git a/Makefile b/Makefile index 99854e04..5bab1fb7 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index 4628eb40..28a08120 100644 --- a/README.md +++ b/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. diff --git a/cli-docs.md b/cli-docs.md new file mode 100644 index 00000000..6379646c --- /dev/null +++ b/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 against ADDRESS + + Default value: `0.0.0.0` +* `--always-accept-admission-reviews-on-namespace ` — Always accept AdmissionReviews that target the given namespace +* `--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 ` — Path to the PID file, used only when running in daemon mode + + Default value: `policy-server.pid` +* `--daemon-stderr-file ` — Path to the file holding stderr, used only when running in daemon mode +* `--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 ` — 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 ` — Path to an X.509 private key file for HTTPS + + Default value: `` +* `--log-fmt ` — Log output format + + Default value: `text` + + Possible values: `text`, `json`, `otlp` + +* `--log-level ` — Log level + + Default value: `info` + + Possible values: `trace`, `debug`, `info`, `warn`, `error` + +* `--log-no-color` — Disable colored output for logs +* `--policies ` — YAML file holding the policies to be loaded and their settings + + Default value: `policies.yml` +* `--policies-download-dir ` — Download path for the policies + + Default value: `.` +* `--policy-timeout ` — Interrupt policy evaluation after the given time + + Default value: `2` +* `--port ` — Listen on PORT + + Default value: `3000` +* `--sigstore-cache-dir ` — Directory used to cache sigstore data + + Default value: `sigstore-data` +* `--sources-path ` — YAML file holding source information (https, registry insecure hosts, custom CA's...) +* `--verification-path ` — YAML file holding verification information (URIs, keys, annotations...) +* `--workers ` — Number of worker threads to create + + + +## `policy-server docs` + +Generates the markdown documentation for policy-server commands + +**Usage:** `policy-server docs --output ` + +###### **Options:** + +* `-o`, `--output ` — path where the documentation file will be stored + + + +
+ + + This document was generated automatically by + clap-markdown. + diff --git a/src/cli.rs b/src/cli.rs index 85efeb51..7fae35fa 100644 --- a/src/cli.rs +++ b/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"), + ), + ) } diff --git a/src/main.rs b/src/main.rs index 045985c2..1706e114 100644 --- a/src/main.rs +++ b/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::("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(()) +}