feat(rust): add examples and about sections to markdown generated docs

implementations/rust/ockam/ockam_command/Cargo.toml

@@ -95,6 +95,7 @@ rustls = "0.20.8"
 rustls-native-certs = "0.6.2"
 pem-rfc7468 = { version = "0.7.0", features = ["std"]}
 termimad = "0.23"
+termcolor = "1.2.0"
 once_cell = "1.17"
 ockam = { path = "../ockam", version = "^0.82.0", features = ["software_vault"] }
 ockam_abac = { path = "../ockam_abac", version = "0.16.0", features = ["std"] }

implementations/rust/ockam/ockam_command/src/admin/mod.rs

@@ -1,14 +1,14 @@
 use clap::{Args, Subcommand};
 
 use crate::util::api::CloudOpts;
-use crate::{help, CommandGlobalOpts};
+use crate::{docs, CommandGlobalOpts};
 
 mod subscription;
 
 const HELP_DETAIL: &str = "";
 
 #[derive(Clone, Debug, Args)]
-#[command(hide = help::hide(), after_long_help = help::template(HELP_DETAIL))]
+#[command(hide = docs::hide(), after_long_help = docs::after_help(HELP_DETAIL))]
 pub struct AdminCommand {
     #[command(subcommand)]
     pub subcommand: AdminSubCommand,

implementations/rust/ockam/ockam_command/src/admin/subscription.rs

@@ -14,12 +14,12 @@ use crate::node::util::delete_embedded_node;
 use crate::subscription::utils;
 use crate::util::api::CloudOpts;
 use crate::util::{node_rpc, Rpc};
-use crate::{help, CommandGlobalOpts};
+use crate::{docs, CommandGlobalOpts};
 
 const HELP_DETAIL: &str = "";
 
 #[derive(Clone, Debug, Args)]
-#[command(hide = help::hide(), after_long_help = help::template(HELP_DETAIL))]
+#[command(hide = docs::hide(), after_long_help = docs::after_help(HELP_DETAIL))]
 pub struct SubscriptionCommand {
     #[command(subcommand)]
     subcommand: SubscriptionSubcommand,

implementations/rust/ockam/ockam_command/src/authenticated.rs

@@ -1,4 +1,4 @@
-use crate::help;
+use crate::docs;
 use crate::util::embedded_node;
 use crate::Result;
 use anyhow::{anyhow, Context as _};
@@ -29,7 +29,7 @@ ${identity
 "#;
 
 #[derive(Clone, Debug, Args)]
-#[command(hide = help::hide(), after_long_help = help::template(HELP_DETAIL))]
+#[command(hide = docs::hide(), after_long_help = docs::after_help(HELP_DETAIL))]
 pub struct AuthenticatedCommand {
     #[command(subcommand)]
     subcommand: AuthenticatedSubcommand,

implementations/rust/ockam/ockam_command/src/authority/create.rs

@@ -1,10 +1,9 @@
 use crate::authority::HELP_DETAIL;
-use crate::help;
 use crate::node::util::init_node_state;
 use crate::node::util::run_ockam;
 use crate::util::node_rpc;
 use crate::util::{embedded_node_that_is_not_stopped, exitcode};
-use crate::{identity, CommandGlobalOpts, Result};
+use crate::{docs, identity, CommandGlobalOpts, Result};
 use anyhow::anyhow;
 use clap::{ArgGroup, Args};
 use ockam::AsyncTryClone;
@@ -25,7 +24,7 @@ use tracing::error;
 
 /// Create a node
 #[derive(Clone, Debug, Args)]
-#[command(after_long_help = help::template(HELP_DETAIL))]
+#[command(after_long_help = docs::after_help(HELP_DETAIL))]
 #[clap(group(ArgGroup::new("okta").args(&["tenant_base_url", "certificate", "attributes"])))]
 #[clap(group(ArgGroup::new("trusted").required(true).args(&["trusted_identities", "reload_from_trusted_identities_file"])))]
 pub struct CreateCommand {

implementations/rust/ockam/ockam_command/src/authority/mod.rs

@@ -1,5 +1,5 @@
 use crate::authority::create::CreateCommand;
-use crate::{help, CommandGlobalOpts};
+use crate::{docs, CommandGlobalOpts};
 use clap::Args;
 use clap::Subcommand;
 mod create;
@@ -9,9 +9,9 @@ const HELP_DETAIL: &str = include_str!("../constants/authority/help_detail.txt")
 /// Create an Authority node
 #[derive(Clone, Debug, Args)]
 #[command(
-arg_required_else_help = true,
-subcommand_required = true,
-after_long_help = help::template(HELP_DETAIL)
+    arg_required_else_help = true,
+    subcommand_required = true,
+    after_long_help = docs::after_help(HELP_DETAIL)
 )]
 pub struct AuthorityCommand {
     #[command(subcommand)]

implementations/rust/ockam/ockam_command/src/completion/mod.rs

@@ -1,13 +1,18 @@
-use crate::{help, OckamCommand};
+use crate::{docs, OckamCommand};
 use clap::{Args, CommandFactory};
 use clap_complete::{generate, Shell};
 use std::io;
 
-const HELP_DETAIL: &str = include_str!("../constants/completion/help_detail.txt");
+const LONG_ABOUT: &str = include_str!("../static/long_about.txt");
+const AFTER_LONG_HELP: &str = include_str!("../static/after_long_help.txt");
 
 /// Generate Shell Completion Scripts
 #[derive(Clone, Debug, Args)]
-#[command(arg_required_else_help = true, after_long_help = help::template(HELP_DETAIL))]
+#[command(
+    arg_required_else_help = true,
+    long_about = docs::about(LONG_ABOUT),
+    after_long_help = docs::after_help(AFTER_LONG_HELP)
+)]
 pub struct CompletionCommand {
     /// The type of shell (bash, zsh, fish)
     #[arg(display_order = 900, long, short)]

implementations/rust/ockam/ockam_command/src/completion/static/after_long_help.txt

@@ -0,0 +1,10 @@
+```sh
+# BASH
+$ ockam completion --shell bash > /usr/share/bash-completion/completions/ockam.bash
+
+# ZSH
+$ ockam completion --shell zsh > /usr/local/share/zsh/site-functions/_ockam
+
+# FISH
+$ ockam completion --shell fish > ~/.config/fish/completions/ockam.fish
+```

implementations/rust/ockam/ockam_command/src/completion/static/long_about.txt

@@ -0,0 +1,8 @@
+Generate shell completion scripts for Ockam commands.
+
+If you’ve installed `ockam` command using a package manager, you likely
+don't need to do any additional shell configuration to gain completion support.
+
+If you need to set up completions manually, follow the instructions below.
+The exact configuration file locations might vary based on your system. Remember
+to restart your shell before testing whether completions are working.

implementations/rust/ockam/ockam_command/src/configuration/mod.rs

@@ -8,14 +8,14 @@ use get_default_node::GetDefaultNodeCommand;
 use list::ListCommand;
 use set_default_node::SetDefaultNodeCommand;
 
-use crate::help;
+use crate::docs;
 use crate::CommandGlobalOpts;
 use clap::{Args, Subcommand};
 
 const HELP_DETAIL: &str = "";
 
 #[derive(Clone, Debug, Args)]
-#[command(hide = help::hide(), after_long_help = help::template(HELP_DETAIL))]
+#[command(hide = docs::hide(), after_long_help = docs::after_help(HELP_DETAIL))]
 pub struct ConfigurationCommand {
     #[command(subcommand)]
     subcommand: ConfigurationSubcommand,