Add examples to cli --help

forc-plugins/forc-crypto/Cargo.toml

@@ -13,6 +13,7 @@ anyhow = "1.0.75"
 async-trait = "0.1.58"
 atty = "0.2.14"
 clap = { version = "3", features = ["derive", "env"] }
+forc = { version = "0.48.1", path = "../../forc" }
 forc-tracing = { version = "0.48.1", path = "../../forc-tracing" }
 fuel-core-types = { workspace = true }
 fuel-crypto = { workspace = true, features = ["random"] }

forc-plugins/forc-crypto/src/address.rs

@@ -4,11 +4,16 @@ use fuels_core::types::bech32::Bech32Address;
 use serde_json::json;
 use std::str::{from_utf8, FromStr};
 
+forc::cli_examples! {
+    [ Convert any valid address to all other supported formats => crypto "address" "fuel12e0xwx34nfp7jrzvn9mp5qkac3yvp7h8fx37ghl7klf82vv2wkys6wd523" ]
+}
+
 #[derive(Debug, clap::Args)]
 #[clap(
     author,
     version,
-    about = "Converts any valid address to all supported formats"
+    about = "Converts any valid address to all supported formats",
+    after_long_help = help(),
 )]
 pub struct Args {
     /// The address to convert. It can be either a valid address in any format

forc-plugins/forc-crypto/src/args.rs

@@ -6,8 +6,20 @@ use std::{
     path::Path,
 };
 
+forc::cli_examples! {
+    [ Hashes data passing as an argument with SHA256 => crypto "sha256" "test" ]
+    [ Hashes data passing as an argument with Keccak256 => crypto "keccak256" "test" ]
+    [ Hashes a file path as an argument with Sha256 => crypto "sha256" "src/args.rs" ]
+    [ Hashes a file path as an argument with Keccak256 => crypto "keccak256" "src/args.rs" ]
+}
+
 #[derive(Debug, Clone, clap::Args)]
-#[clap(author, version, about = "Hashes the argument or file with this hash")]
+#[clap(
+    author,
+    version,
+    about = "Hashes the argument or file with this hash",
+    after_long_help = help(),
+)]
 pub struct HashArgs {
     /// This argument is optional, it can be either:
     ///

forc-plugins/forc-crypto/src/keygen/new_key.rs

@@ -13,9 +13,17 @@ use libp2p_identity::{secp256k1, Keypair, PeerId};
 use serde_json::json;
 use std::ops::Deref;
 
+const ABOUT: &str = "Creates a new key for use with fuel-core";
+
+forc::cli_examples! {
+    [ Creates a new key for block production by default => crypto "new-key" ]
+    [ Creates a new key for peering => crypto "new-key" "-k" "peering" ]
+    [ Creates a new key for block production => crypto "new-key" "-k" "peering" ]
+}
+
 /// Generate a random new secret & public key in the format expected by fuel-core
 #[derive(Debug, clap::Args)]
-#[clap(author, version, about = "Creates a new key for use with fuel-core")]
+#[clap(author, version, about = ABOUT, after_long_help = help())]
 pub struct Arg {
     /// Key type to generate. It can either be `block-production` or `peering`.
     #[clap(

forc-plugins/forc-crypto/src/keygen/parse_secret.rs

@@ -7,12 +7,24 @@ use libp2p_identity::{secp256k1, Keypair, PeerId};
 use serde_json::json;
 use std::{ops::Deref, str::FromStr};
 
+const ABOUT: &str = "Parses a private key to view the associated public key";
+
+#[cfg(test)]
+#[allow(non_upper_case_globals)]
+const PrivateKey: &str = "f5204427d0ab9a311266c96a377f7c329cb8a41b9088225b6fcf40eefb423e28";
+
+forc::cli_examples! {
+    [ Parses the secret of a block production  => crypto "parse-secret" PrivateKey ]
+    [ Parses the secret of a peering  => crypto "parse-secret" "-k" "peering" PrivateKey ]
+}
+
 /// Parse a secret key to view the associated public key
 #[derive(Debug, clap::Args)]
 #[clap(
     author,
     version,
-    about = "Parses a private key to view the associated public key"
+    about = ABOUT,
+    after_long_help = help(),
 )]
 pub struct Arg {
     /// A private key in hex format

forc-plugins/forc-crypto/src/main.rs

@@ -16,10 +16,26 @@ mod keccak256;
 mod keygen;
 mod sha256;
 
+const ABOUT: &str = "Forc plugin for hashing arbitrary data.";
+
+fn after_long_help() -> &'static str {
+    Box::leak(
+        format!(
+            "EXAMPLES:\n{}{}{}{}",
+            args::examples(),
+            address::examples(),
+            keygen::new_key::examples(),
+            keygen::parse_secret::examples(),
+        )
+        .into_boxed_str(),
+    )
+}
+
 #[derive(Debug, Parser)]
 #[clap(
     name = "forc-crypto",
-    about = "Forc plugin for hashing arbitrary data.",
+    about = ABOUT,
+    after_long_help = after_long_help(),
     version
 )]
 pub enum Command {

forc-plugins/forc-doc/Cargo.toml

@@ -13,6 +13,7 @@ anyhow = "1.0.65"
 clap = { version = "4.0.18", features = ["derive"] }
 colored = "2.0.0"
 comrak = "0.16"
+forc = { version = "0.48.1", path = "../../forc" }
 forc-pkg = { version = "0.48.1", path = "../../forc-pkg" }
 forc-util = { version = "0.48.1", path = "../../forc-util" }
 horrorshow = "0.8.4"

forc-plugins/forc-doc/src/cli.rs

@@ -2,10 +2,21 @@
 use clap::Parser;
 use forc_pkg::source::IPFSNode;
 
+const ABOUT: &str = "Forc plugin for building a Sway package's documentation";
+
+forc::cli_examples! {
+    [ Build the docs for a project in the current path => doc ]
+    [ Build the docs for a project in the current path and open it in the browser => doc "--open" ]
+    [ Build the docs for a project located in another path => doc "--manifest-path" "../tests_project2" ]
+    [ Build the docs for the current project exportings private types => doc "--document-private-items" ]
+    [ Build the docs offline without downloading any dependency from the network => doc "--offline" ]
+}
+
 #[derive(Debug, Parser, Default)]
 #[clap(
     name = "forc-doc",
-    about = "Forc plugin for building a Sway package's documentation",
+    about = ABOUT,
+    after_long_help = help(),
     version
 )]
 pub struct Command {

forc-plugins/forc-doc/tests/.gitignore

@@ -0,0 +1,2 @@
+out
+target

forc-plugins/forc-doc/tests/Forc.toml

@@ -0,0 +1,7 @@
+[project]
+authors = ["Fuel Labs <contact@fuel.sh>"]
+entry = "main.sw"
+license = "Apache-2.0"
+name = "tests"
+
+[dependencies]

forc-plugins/forc-doc/tests/src/main.sw

@@ -0,0 +1,11 @@
+contract;
+
+abi MyContract {
+    fn test_function() -> bool;
+}
+
+impl MyContract for Contract {
+    fn test_function() -> bool {
+        true
+    }
+}

forc-plugins/forc-doc/tests_project2/.gitignore

@@ -0,0 +1,2 @@
+out
+target

forc-plugins/forc-doc/tests_project2/Forc.toml

@@ -0,0 +1,7 @@
+[project]
+authors = ["Fuel Labs <contact@fuel.sh>"]
+entry = "main.sw"
+license = "Apache-2.0"
+name = "inner"
+
+[dependencies]

forc-plugins/forc-doc/tests_project2/src/main.sw

@@ -0,0 +1,11 @@
+contract;
+
+abi MyContract {
+    fn test_function() -> bool;
+}
+
+impl MyContract for Contract {
+    fn test_function() -> bool {
+        true
+    }
+}

forc/Cargo.toml

@@ -29,8 +29,10 @@ forc-util = { version = "0.48.1", path = "../forc-util" }
 fs_extra = "1.2"
 fuel-asm = { workspace = true }
 hex = "0.4.3"
+paste = "1.0.14"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0.73"
+serial_test = "2.0.0"
 sway-core = { version = "0.48.1", path = "../sway-core" }
 sway-error = { version = "0.48.1", path = "../sway-error" }
 sway-types = { version = "0.48.1", path = "../sway-types" }

forc/src/cli/help.rs

@@ -0,0 +1,45 @@
+#[macro_export]
+macro_rules! cli_examples {
+    ($( [ $($description:ident)* => $command:tt $($arg:expr)* ] )*) => {
+            #[cfg(test)]
+            use $crate::serial_test;
+            $(
+            $crate::paste::paste! {
+                #[cfg(test)]
+                #[test]
+                #[serial_test::serial]
+                fn [<$($description:lower _)*:snake example>] () {
+                    let mut proc = std::process::Command::new("cargo");
+                    proc.arg("run");
+                    proc.arg("--bin");
+                    proc.arg(format!("forc-{}", stringify!($command)));
+                    proc.arg("--");
+                    $(
+                        proc.arg($arg);
+                    )*
+
+                    let path = std::path::Path::new("tests");
+                    if path.is_dir() {
+                        proc.current_dir(path);
+                    }
+                    let output = proc.output().expect(stringify!($command));
+                    assert!(output.status.success(), "{}: {:?}", stringify!($($description)*), output);
+                }
+            }
+            )*
+
+        fn help() -> &'static str {
+            Box::leak(format!("EXAMPLES:\n{}", examples()).into_boxed_str())
+        }
+
+        pub fn examples() -> &'static str {
+            Box::leak( [
+            $(
+            $crate::paste::paste! {
+                    format!("\t#{}\n\tforc {} {}\n\n", stringify!($($description)*), stringify!($command), stringify!($($arg)*) )
+            },
+            )*
+            ].concat().into_boxed_str())
+        }
+    };
+}

forc/src/cli/mod.rs

@@ -24,6 +24,8 @@ pub use test::Command as TestCommand;
 use tracing::metadata::LevelFilter;
 pub use update::Command as UpdateCommand;
 
+#[macro_use]
+pub mod help;
 mod commands;
 mod plugin;
 pub mod shared;

forc/src/lib.rs

@@ -12,3 +12,6 @@ pub mod test {
 pub mod util {
     pub use sway_utils::constants;
 }
+
+pub extern crate paste;
+pub use serial_test;