Skip to content

Commit 5594c7d

Browse files
authored
Merge pull request #1056 from jvanz/main
feat(cli): generate CLI reference documentation.
2 parents 8e5c493 + e1cb432 commit 5594c7d

File tree

8 files changed

+160
-0
lines changed

8 files changed

+160
-0
lines changed

.github/workflows/ci.yml

+15
Original file line numberDiff line numberDiff line change
@@ -118,3 +118,18 @@ jobs:
118118
directory: coverage/integration-tests
119119
flags: integration-tests
120120
verbose: true
121+
122+
docs:
123+
name: Update documentation
124+
runs-on: ubuntu-latest
125+
steps:
126+
- name: Checkout
127+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
128+
129+
- run: |
130+
make build-docs
131+
if ! git diff --quiet cli-docs.md; then
132+
echo "Changes detected in cli-docs.md. Please run `make build-docs` and commit the changes."
133+
gh run cancel ${{ github.run_id }}
134+
fi
135+

Cargo.lock

+10
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Cargo.toml

+1
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ jemalloc_pprof = "0.6.0"
6666
tikv-jemalloc-ctl = "0.6.0"
6767
rhai = { version = "1.19.0", features = ["sync"] }
6868
tonic = { version = "0.12.3" }
69+
clap-markdown = "0.1.4"
6970

7071
[target.'cfg(target_os = "linux")'.dependencies]
7172
inotify = "0.11"

Makefile

+4
Original file line numberDiff line numberDiff line change
@@ -74,3 +74,7 @@ download-spdx-sbom-generator: bin
7474
.PHONY: sbom
7575
sbom:
7676
./$(BINDIR)/spdx-sbom-generator -f json
77+
78+
.PHONY:build-docs
79+
build-docs:
80+
cargo run --release -- docs --output cli-docs.md

README.md

+5
Original file line numberDiff line numberDiff line change
@@ -373,3 +373,8 @@ in our Kubewarden docs.
373373
## Changelog
374374

375375
See [GitHub Releases content](https://github.com/kubewarden/policy-server/releases).
376+
377+
# CLI documentation
378+
379+
If you want a complete list of the available commands, you can read the
380+
[cli-docs.md](./cli-docs.md) file.

cli-docs.md

+94
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Command-Line Help for `policy-server`
2+
3+
This document contains the help content for the `policy-server` command-line program.
4+
5+
**Command Overview:**
6+
7+
* [`policy-server`](#policy-server)
8+
* [`policy-server docs`](#policy-server-docs)
9+
10+
## `policy-server`
11+
12+
13+
14+
**Usage:** `policy-server [OPTIONS] [COMMAND]`
15+
16+
###### **Subcommands:**
17+
18+
* `docs` — Generates the markdown documentation for policy-server commands
19+
20+
###### **Options:**
21+
22+
* `--addr <BIND_ADDRESS>` — Bind against ADDRESS
23+
24+
Default value: `0.0.0.0`
25+
* `--always-accept-admission-reviews-on-namespace <NAMESPACE>` — Always accept AdmissionReviews that target the given namespace
26+
* `--cert-file <CERT_FILE>` — Path to an X.509 certificate file for HTTPS
27+
28+
Default value: ``
29+
* `--daemon` — If set, runs policy-server in detached mode as a daemon
30+
* `--daemon-pid-file <DAEMON-PID-FILE>` — Path to the PID file, used only when running in daemon mode
31+
32+
Default value: `policy-server.pid`
33+
* `--daemon-stderr-file <DAEMON-STDERR-FILE>` — Path to the file holding stderr, used only when running in daemon mode
34+
* `--daemon-stdout-file <DAEMON-STDOUT-FILE>` — Path to the file holding stdout, used only when running in daemon mode
35+
* `--disable-timeout-protection` — Disable policy timeout protection
36+
* `--docker-config-json-path <DOCKER_CONFIG>` — Path to a Docker config.json-like path. Can be used to indicate registry authentication details
37+
* `--enable-metrics` — Enable metrics
38+
* `--enable-pprof` — Enable pprof profiling
39+
* `--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.
40+
* `--key-file <KEY_FILE>` — Path to an X.509 private key file for HTTPS
41+
42+
Default value: ``
43+
* `--log-fmt <LOG_FMT>` — Log output format
44+
45+
Default value: `text`
46+
47+
Possible values: `text`, `json`, `otlp`
48+
49+
* `--log-level <LOG_LEVEL>` — Log level
50+
51+
Default value: `info`
52+
53+
Possible values: `trace`, `debug`, `info`, `warn`, `error`
54+
55+
* `--log-no-color` — Disable colored output for logs
56+
* `--policies <POLICIES_FILE>` — YAML file holding the policies to be loaded and their settings
57+
58+
Default value: `policies.yml`
59+
* `--policies-download-dir <POLICIES_DOWNLOAD_DIR>` — Download path for the policies
60+
61+
Default value: `.`
62+
* `--policy-timeout <MAXIMUM_EXECUTION_TIME_SECONDS>` — Interrupt policy evaluation after the given time
63+
64+
Default value: `2`
65+
* `--port <PORT>` — Listen on PORT
66+
67+
Default value: `3000`
68+
* `--sigstore-cache-dir <SIGSTORE_CACHE_DIR>` — Directory used to cache sigstore data
69+
70+
Default value: `sigstore-data`
71+
* `--sources-path <SOURCES_PATH>` — YAML file holding source information (https, registry insecure hosts, custom CA's...)
72+
* `--verification-path <VERIFICATION_CONFIG_PATH>` — YAML file holding verification information (URIs, keys, annotations...)
73+
* `--workers <WORKERS_NUMBER>` — Number of worker threads to create
74+
75+
76+
77+
## `policy-server docs`
78+
79+
Generates the markdown documentation for policy-server commands
80+
81+
**Usage:** `policy-server docs --output <FILE>`
82+
83+
###### **Options:**
84+
85+
* `-o`, `--output <FILE>` — path where the documentation file will be stored
86+
87+
88+
89+
<hr/>
90+
91+
<small><i>
92+
This document was generated automatically by
93+
<a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
94+
</i></small>

src/cli.rs

+12
Original file line numberDiff line numberDiff line change
@@ -204,4 +204,16 @@ pub(crate) fn build_cli() -> Command {
204204
.about(crate_description!())
205205
.long_version(VERSION_AND_BUILTINS.as_str())
206206
.args(args)
207+
.subcommand(
208+
Command::new("docs")
209+
.about("Generates the markdown documentation for policy-server commands")
210+
.arg(
211+
Arg::new("output")
212+
.long("output")
213+
.short('o')
214+
.required(true)
215+
.value_name("FILE")
216+
.help("path where the documentation file will be stored"),
217+
),
218+
)
207219
}

src/main.rs

+19
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
mod cli;
22

33
use std::fs;
4+
use std::io::prelude::*;
45

56
use ::tracing::info;
67
use anyhow::anyhow;
78
use anyhow::Result;
9+
use clap::ArgMatches;
810
use opentelemetry::global::shutdown_tracer_provider;
911
use policy_server::metrics::setup_metrics;
1012
use policy_server::tracing::setup_tracing;
@@ -19,6 +21,10 @@ async fn main() -> Result<()> {
1921
.expect("Failed to install crypto provider");
2022

2123
let matches = cli::build_cli().get_matches();
24+
if matches.subcommand_name() == Some("docs") {
25+
return run_docs_subcommand(matches.subcommand_matches("docs"));
26+
}
27+
2228
let config = policy_server::config::Config::from_args(&matches)?;
2329

2430
setup_tracing(&config.log_level, &config.log_fmt, config.log_no_color)?;
@@ -56,3 +62,16 @@ async fn main() -> Result<()> {
5662

5763
Ok(())
5864
}
65+
66+
/// Handle the docs subcommand and generates markdown documentation for the CLI
67+
fn run_docs_subcommand(matches: Option<&ArgMatches>) -> Result<()> {
68+
if let Some(matches) = matches {
69+
let output = matches.get_one::<String>("output").unwrap();
70+
let mut file = std::fs::File::create(output)
71+
.map_err(|e| anyhow!("cannot create file {}: {}", output, e))?;
72+
let docs_content = clap_markdown::help_markdown_command(&cli::build_cli());
73+
file.write_all(docs_content.as_bytes())
74+
.map_err(|e| anyhow!("cannot write to file {}: {}", output, e))?;
75+
}
76+
Ok(())
77+
}

0 commit comments

Comments
 (0)