Documentation, CLI help section polishing

rabbitmq · Dec 24, 2024 · 546d5e9 · 546d5e9
1 parent 1139590
commit 546d5e9
Show file tree

Hide file tree

Showing 2 changed files with 94 additions and 47 deletions.
diff --git a/README.md b/README.md
@@ -8,25 +8,13 @@ to learn about a few breaking change in the interface.
 
 ## Getting Started
 
-To download a binary build, see [Releases](https://github.com/rabbitmq/rabbitmqadmin-ng/releases).
-
-For usage documentation, see [Usage](#usage).
+### Releases
 
+To download a binary build, see [Releases](https://github.com/rabbitmq/rabbitmqadmin-ng/releases).
 
-## Project Goals Compared to `rabbitmqadmin` v1
+### Documentation
 
-This version of `rabbitmqadmin` has a few ideas in mind:
-
- * This is a major version bump. Therefore, reasonable breaking changes are OK. `rabbitmqadmin` hasn't seen a revision in fourteen years
- * `rabbitmqadmin` should be standalone binary. There are very few reasons not to build and distribute it that way
-* Standalone project, not an obscure feature: `rabbitmqadmin` should be a standalone tool, not a relatively unknown "feature" of
-  the RabbitMQ management plugin, and should be developed as such, not tied completely to the development
-  environment, practices and release schedule of RabbitMQ itself
- * v2 should be a distributed via GitHub releases and not a special `rabbitmq_management` endpoint
- * There is a lot of room to improve validation of flags and arguments, since breaking changes are OK for v2
- * This tool should strive to be as free as practically possible from CVEs in other projects that show up on security scans.
-   CVEs from older Python versions should not plague OCI images that choose to include `rabbitmqadmin` v2
- * Output should be revisited: what columns are output by default, whether columns should be selectable
+For usage documentation, see [Usage](#usage).
 
 ## Project Maturity
 
@@ -44,6 +32,74 @@ The following `rabbitmqadmin` v1 features are not currently implemented:
 
 ## Usage
 
+### Exploring Available Command Groups and Sub-commands
+
+To explore what command groups are available, use
+
+```shell
+rabbitmqadmin help
+```
+
+which will output a list of command groups:
+
+```
+Usage: rabbitmqadmin [OPTIONS] <command>
+
+Commands:
+  show          overview
+  list          lists objects by type
+  declare       creates or declares things
+  delete        deletes objects
+  purge         purges queues
+  health_check  runs health checks
+  close         closes connections
+  rebalance     rebalances queue leaders
+  definitions   operations on definitions
+  export        see 'definitions export'
+  import        see 'definitions import'
+  publish       publish a message
+  get           get message(s) from a queue
+  help          Print this message or the help of the given subcommand(s)
+```
+
+To explore commands in a specific group, use
+
+```shell
+rabbitmqadmin {group name} help
+```
+
+### Exploring the CLI with `help`, `--help`
+
+To learn about what command groups and specific commands are available, run
+
+``` shell
+rabbitmqadmin help
+```
+
+This flag can be appended to a command or subcommand to get command-specific documentation:
+
+```shell
+rabbitmqadmin declare queue --help
+# => creates or declares things
+# =>
+# => Usage: rabbitmqadmin declare [object]
+# => ...
+```
+
+Alternatively, the `help` subcommand can be given a command name. It's the equivalent
+of tagging on `--help` at the end of command name:
+
+```shell
+rabbitmqadmin declare help queue
+# => creates or declares things
+# =>
+# => Usage: rabbitmqadmin declare [object]
+# => ...
+```
+
+More specific examples are covered in the Examples section below.
+
+
 ### Interactive vs. Use in Scripts
 
 Like the original version, `rabbitmqadmin` v2 is first and foremost built for interactive use
@@ -95,34 +151,6 @@ as a result:
  Erlang details    Erlang/OTP 26 [erts-14.2.5.5] [source] [64-bit] [smp:10:10] [ds:10:10:10] [async-threads:1] [jit]
 ```
 
-### Exploring the CLI with --help
-
-To learn about what command groups and specific commands are available, run
-
-``` shell
-rabbitmqadmin --help
-```
-
-This flag can be appended to a command or subcommand to get command-specific documentation:
-
-```shell
-rabbitmqadmin declare queue --help
-# => creates or declares things
-# =>
-# => Usage: rabbitmqadmin declare [object]
-# => ...
-```
-
-And with a specific subcommand:
-
-```shell
-rabbitmqadmin declare queue --help
-# => declares a queue
-# =>
-# => Usage: rabbitmqadmin declare queue [OPTIONS] --name <name>
-# => ...
-```
-
 ### Retrieving Basic Node Information
 
 ``` shell
@@ -301,6 +329,21 @@ rabbitmqadmin --config $HOME/.configuration/rabbitmqadmin.conf --node staging sh
 ```
 
 
+## Project Goals Compared to `rabbitmqadmin` v1
+
+This version of `rabbitmqadmin` has a few ideas in mind:
+
+* This is a major version bump. Therefore, reasonable breaking changes are OK. `rabbitmqadmin` hasn't seen a revision in fourteen years
+* `rabbitmqadmin` should be standalone binary. There are very few reasons not to build and distribute it that way
+* Standalone project, not an obscure feature: `rabbitmqadmin` should be a standalone tool, not a relatively unknown "feature" of
+  the RabbitMQ management plugin, and should be developed as such, not tied completely to the development
+  environment, practices and release schedule of RabbitMQ itself
+* v2 should be a distributed via GitHub releases and not a special `rabbitmq_management` endpoint
+* There is a lot of room to improve validation of flags and arguments, since breaking changes are OK for v2
+* This tool should strive to be as free as practically possible from CVEs in other projects that show up on security scans.
+  CVEs from older Python versions should not plague OCI images that choose to include `rabbitmqadmin` v2
+
+
 ## Breaking or Potentially Breaking Changes
 
 ### --snake-case for Command Options

diff --git a/src/cli.rs b/src/cli.rs
@@ -246,7 +246,7 @@ pub fn parser() -> Command {
                 .subcommand_value_name("message")
                 .subcommands(publish_subcommands()),
             Command::new("get")
-                .about(color_print::cstr!("fetches message(s) from a queue or stream via <bold><red>polling, extremely inefficiently</red></bold>"))
+                .about(color_print::cstr!("fetches message(s) from a queue or stream via <bold><red>polling</red></bold>. <bold><red>Only suitable for development and test environments</red></bold>."))
                 .after_long_help(color_print::cformat!("<bold>Doc guide</bold>: {}", POLLING_CONSUMER_GUIDE_URL))
                 .subcommand_value_name("message")
                 .subcommands(get_subcommands()),
@@ -300,8 +300,12 @@ fn list_subcommands() -> [Command; 15] {
                 "<bold>Doc guide</bold>: {}",
                 QUEUE_GUIDE_URL
             )),
-        Command::new("exchanges").arg(vhost_arg.clone()),
-        Command::new("bindings").arg(vhost_arg.clone()),
+        Command::new("exchanges")
+            .arg(vhost_arg.clone())
+            .long_about("Lists exchanges"),
+        Command::new("bindings")
+            .arg(vhost_arg.clone())
+            .long_about("Lists bindings"),
         Command::new("consumers")
             .arg(vhost_arg.clone())
             .long_about("Lists consumers")