fbb123d docs: add help for all subcommands and options — radicle-ci-broker

Radicle CI broker

docs: add help for all subcommands and options

Lars Wirzenius committed 1 year ago

commit fbb123d953753b75cc13940f5a064d7a5ba4df00
parent d421a6ef17874d999246f2fb9bd797c0ed55e6a7

3 files changed +88 -1

modified Cargo.lock

@@ -357,6 +357,7 @@ dependencies = [

  "anstyle",
  "clap_lex",
  "strsim",
  "terminal_size",
 ]
 [[package]]

@@ -2421,6 +2422,16 @@ dependencies = [

 ]
 [[package]]
 name = "terminal_size"
 version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "21bebf2b7c9e0a515f6e0f8c51dc0f8e4696391e6f1ff30379559f8365fb0df7"
 dependencies = [
  "rustix",
  "windows-sys 0.48.0",
 ]
 [[package]]
 name = "textwrap"
 version = "0.15.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"

modified Cargo.toml

@@ -12,7 +12,7 @@ categories = ["development-tools::build-utils"]

 [dependencies]
 anyhow = "1.0.82"
 clap = { version = "4.5.4", features = ["derive"] }
 clap = { version = "4.5.4", features = ["derive", "wrap_help"] }
 html-page = "0.2.0"
 log = "0.4.20"
 pretty_env_logger = "0.5.0"

modified src/bin/cibtool.rs

@@ -55,8 +55,17 @@ fn fallible_main() -> Result<(), CibToolError> {

     Ok(())
 }
 /// Radicle CI broker management tool for node operators.
 ///
 /// Query and update the CI broker database file: the queue of events
 /// waiting to be processed, the list of CI runs. Also, generate HTML
 /// report pages from the database.
 ///
 /// This tool can be used whether the CI broker is running or not.
 #[derive(Parser)]
 struct Args {
     /// Name of the SQLite database file. The file will be created if
     /// it does not already exist. Locking is handled automatically.
     #[clap(long)]
     db: PathBuf,

@@ -84,9 +93,19 @@ impl Args {

 #[derive(Parser)]
 enum Cmd {
     /// Manage a counter in the database. This is meant to be used
     /// only by the CI broker test suite, not by people.
     #[clap(hide = true)]
     Counter(CounterCmd),
     /// Manage the event queue. The events are for Git refs having
     /// changed.
     Event(EventCmd),
     /// Manage the list of CI runs.
     Run(RunCmd),
     /// Produce HTML reports based on database contents.
     Report(ReportCmd),
 }

@@ -109,7 +128,10 @@ impl CounterCmd {

 #[derive(Parser)]
 enum CounterSubCmd {
     /// Show the current value of the counter.
     Show(ShowCounter),
     /// Count until the counter reaches a minimum value.
     Count(CountCounter),
 }

@@ -128,6 +150,7 @@ impl ShowCounter {

 #[derive(Parser)]
 struct CountCounter {
     /// The minimum value which counting aims at.
     #[clap(long)]
     goal: i64,
 }

@@ -200,16 +223,30 @@ impl EventCmd {

 #[derive(Parser)]
 enum EventSubCmd {
     /// List events in the queue, waiting to be processed.
     List(ListEvents),
     /// Show the number of events in the queue.
     Count(CountEvents),
     /// Add an event to the queue.
     Add(AddEvent),
     /// Add a shutdown event to the queue.
     ///
     /// The shutdown event causes the CI broker to terminate.
     Shutdown(Shutdown),
     /// Show an event in the queue.
     Show(ShowEvent),
     /// Remove an event from the queue.
     Remove(RemoveEvent),
 }
 #[derive(Parser)]
 struct ListEvents {
     /// Show more details about the event.
     #[clap(long)]
     verbose: bool,
 }

@@ -247,21 +284,33 @@ impl CountEvents {

 #[derive(Parser)]
 struct AddEvent {
     /// Set the repository the event refers to. Can be a RID, or the
     /// repository name.
     #[clap(long)]
     repo: String,
     /// Set the name of the ref the event refers to.
     #[clap(long, alias = "ref")]
     name: String,
     /// Set the commit the event refers to. Can be the SHA1 commit id,
     /// or a symbolic Git revision, as understood by `git rev-parse`.
     /// For example, `HEAD`.
     #[clap(long)]
     commit: String,
     /// The base commit referred to by the event. Optional, but must
     /// be a SHA commit id.
     #[clap(long)]
     base: Option<Oid>,
     /// Write the event to this file, as JSON, instead of adding it to
     /// the queue.
     #[clap(long)]
     output: Option<PathBuf>,
     /// Write the event ID to this file, after adding the event to the
     /// queue.
     #[clap(long)]
     id_file: Option<PathBuf>,
 }

@@ -361,15 +410,20 @@ impl AddEvent {

 #[derive(Parser)]
 struct ShowEvent {
     /// ID of event to show.
     #[clap(long, required_unless_present = "id_file")]
     id: Option<QueueId>,
     /// Show event as JSON? Default is a debugging format useful for
     /// programmers.
     #[clap(long)]
     json: bool,
     /// Write output to this file.
     #[clap(long)]
     output: Option<PathBuf>,
     /// Read ID of event to show from this file.
     #[clap(long)]
     id_file: Option<PathBuf>,
 }

@@ -409,9 +463,11 @@ impl ShowEvent {

 #[derive(Parser)]
 struct RemoveEvent {
     /// ID of event to remove.
     #[clap(long, required_unless_present = "id_file")]
     id: Option<QueueId>,
     /// Read ID of event to remove from this file.
     #[clap(long)]
     id_file: Option<PathBuf>,
 }

@@ -438,6 +494,8 @@ impl RemoveEvent {

 #[derive(Parser)]
 struct Shutdown {
     /// Write ID of the event to this file, after adding the event to
     /// the queue.
     #[clap(long)]
     id_file: Option<PathBuf>,
 }

@@ -475,49 +533,65 @@ impl RunCmd {

 #[derive(Parser)]
 enum RunSubCmd {
     /// Add information about a CI run to the database.
     Add(AddRun),
     /// List known CI runs on this node to the database.
     List(ListRuns),
 }
 #[derive(Parser)]
 struct AddRun {
     /// Set the run ID.
     #[clap(long)]
     id: RunId,
     /// Set alias of node that performed the CI run.
     #[clap(long)]
     alias: String,
     /// Set optional URL to information about the CI run.
     #[clap(long)]
     url: Option<String>,
     /// Set the repository ID that the CI run for.
     #[clap(long)]
     repo: RepoId,
     /// Set timestamp of the CI run.
     #[clap(long)]
     timestamp: String,
     /// Set the Git branch used by the CI run.
     #[clap(long)]
     branch: String,
     /// Set the commit SHA ID used by the CI run.
     #[clap(long)]
     commit: Oid,
     /// Set the author of the commit used by the CI run.
     #[clap(long)]
     who: Option<String>,
     /// Set the state of the CI run to "triggered".
     #[clap(long, required_unless_present_any = ["running", "finished"])]
     triggered: bool,
     /// Set the state of the CI run to "running".
     #[clap(long)]
     #[clap(long, required_unless_present_any = ["triggered", "finished"])]
     running: bool,
     /// Set the state of the CI run to "finished".
     #[clap(long)]
     #[clap(long, required_unless_present_any = ["triggered", "running"])]
     finished: bool,
     /// Mark the finished CI run as successful.
     #[clap(long, required_unless_present = "failure")]
     success: bool,
     /// Mark the finished CI run as having failed.
     #[clap(long, required_unless_present = "success")]
     failure: bool,

@@ -569,6 +643,8 @@ impl ListRuns {

 #[derive(Parser)]
 struct ReportCmd {
     /// Write HTML files to this directory. The directory must exist:
     /// it is not created automatically.
     #[clap(long)]
     output_dir: PathBuf,
 }