Add examples to cli --help

[crodas]

Description

Fixes #5398, #5374. This PR depends on #5433

Add examples to our --help cli. The examples are defined through the a macro forc::cli_examples { } and each of these examples is part of the the test suite of the crate. This is done to ensure the documentation is always up to date or updated whenever the tests are not passing.

All the CLI examples should be provided with the forc::cli_examples! macro.

forc::cli_examples! {
    [ Do something and expect the exit to be 0 => bin-name " arg1 arg 2"  ],
    [ Do something and check stdout or stderr => bin-name " arg1 arg 2" => r#"Expected output with regex"# ],
}

The above example will create two unit tests that will be run as part of the cargo test inside the project. The unit test will be done with an external invocation, meaning it can be treated like an end-to-end test instead of a unit test. If the binary interface changes, the tests should fail, forcing the developer to either update the tests (which is the documentation) or keep them backward compatible. The ultimate goal is to have documentation that is up to date, enforced by the github actions/unit test.

Last bit not least the macro will create a help() function which is local to the file, this file does the printing with --help is invoked. It should be used as follows:

#[clap(bin_name = "forc name", version, after_help = help())]
pub struct Command {
   ...
}

Checklist

• I have linked to any relevant issues.
• I have commented my code, particularly in hard-to-understand areas.
• I have updated the documentation where relevant (API docs, the reference, and the Sway book).
• I have added tests that prove my fix is effective or that my feature works.
• I have added (or requested a maintainer to add) the necessary Breaking* or New Feature labels where relevant.
• I have done my best to ensure that my PR adheres to the Fuel Labs Code Review Standards.
• I have requested a review from the relevant team or maintainers.

[crodas]

Screen.Recording.2023-12-15.at.14.50.30.mov

[kayagokalp]

This is going to be really nice! Thanks for the testing infra for examples as well. It seems like we are touching forc-crypto, forc-doc and forc itself in this PR, are we planning to touch to forc-client, forc-submit as well? If so let's mark this as a draft if you want to break it into couple of ones we should probably update the title and description.

[crodas]

This is going to be really nice! Thanks for the testing infra for examples as well. It seems like we are touching forc-crypto, forc-doc and forc itself in this PR, are we planning to touch to forc-client, forc-submit as well? If so let's mark this as a draft if you want to break it into couple of ones we should probably update the title and description.

I am adding more examples now

[kayagokalp]

I think examples look comprehensive enough! Nice work, I can approve again after josh's comments

[crodas]

Todo:

• Move the macro definition to the for utils
• forc-test
• forc-tx
• forc-doc
• forc-deploy
• forc-submit

[JoshuaBatty]

Nice work

[sdankel]