polkadot-sdk-docs: Use command_macro!

[kianenigma]

to have a better docify version of commands. IN other words, find all instances of #[docify::export] process:Command, and replace with https://github.com/krdln/command-macros.

[programskillforverification]

What do you think of replacing with https://github.com/rust-shell-script/rust_cmd_lib? command_macro! hasn't been maintained for a long time.

[kianenigma]

If it delivers the same outcome, then yes it indeed seems better.

[iulianbarbu]

Adding some context from my investigations around testing commands that appear in crate-level docs, so that they also look similar to what one would run in a shell: #5954 (comment).

[bennethxyz]

Taking this one ☝️

[michalkucharczyk]

Taking this one ☝️

Great! This is a good reference entry point showing how to do it:

polkadot-sdk/substrate/bin/utils/chain-spec-builder/README.docify.md

Line 33 in 4df9433

<!-- docify::embed!("tests/test.rs", cmd_create_default) -->

[ndkazu]

to have a better docify version of commands. IN other words, find all instances of #[docify::export] process:Command, and replace with https://github.com/krdln/command-macros.

Let me re-frame this to see if I correctly understand the assignment:

• Within all tests using #[docify::export], select those using process:Command, and replace the use of process:Command by command_macro!.
  Is that right?
  See the corresponding PR: polkadot-sdk-docs: Use command_macro! #6624

[ndkazu]

I would like to add that I also tried using cmd_lib instead of command_macro!, but I also get a crate related error in this case 😞

Compiling chain-spec-guide-runtime v0.0.0 (/home/kazu/Polkadot/polkadot-sdk/docs/sdk/src/reference_docs/chain_spec_runtime)
  error[E0433]: failed to resolve: could not find `unix` in `os`
    --> /home/kazu/.cargo/registry/src/index.crates.io-6f17d22bba15001f/os_pipe-1.2.1/src/unix.rs:6:14
     |
  6  | use std::os::unix::prelude::*;
     |              ^^^^ could not find `unix` in `os`
     |

[iulianbarbu]

I would like to add that I also tried using cmd_lib instead of command_macro!, but I also get a crate related error in this case 😞

Compiling chain-spec-guide-runtime v0.0.0 (/home/kazu/Polkadot/polkadot-sdk/docs/sdk/src/reference_docs/chain_spec_runtime)
  error[E0433]: failed to resolve: could not find `unix` in `os`
    --> /home/kazu/.cargo/registry/src/index.crates.io-6f17d22bba15001f/os_pipe-1.2.1/src/unix.rs:6:14
     |
  6  | use std::os::unix::prelude::*;
     |              ^^^^ could not find `unix` in `os`
     |

Hey @ndkazu. Can you please give a sample of the cmd_lib code you're using? Can you confirm you're developing on Linux?

[ndkazu]

I would like to add that I also tried using cmd_lib instead of command_macro!, but I also get a crate related error in this case 😞

Compiling chain-spec-guide-runtime v0.0.0 (/home/kazu/Polkadot/polkadot-sdk/docs/sdk/src/reference_docs/chain_spec_runtime)
  error[E0433]: failed to resolve: could not find `unix` in `os`
    --> /home/kazu/.cargo/registry/src/index.crates.io-6f17d22bba15001f/os_pipe-1.2.1/src/unix.rs:6:14
     |
  6  | use std::os::unix::prelude::*;
     |              ^^^^ could not find `unix` in `os`
     |

Hey @ndkazu. Can you please give a sample of the cmd_lib code you're using? Can you confirm you're developing on Linux?

@iulianbarbu , I am using this example to use cmd_lib on native Linux/Ubuntu. I see that the library is also used in /home/kazu/Polkadot/polkadot-sdk/substrate/bin/utils/chain-spec-builder/tests/test.rs, but then I have the following questions:

1. I don't see #[cmd_lib::main]
2. Instead of using run_cmd!, spawn_with_output! is used.
3. there is also the fact that methods used on the output of Command::new(...) such as .output() or .stdout are not available when using run_cmd! or spawn_with_output!...I guess I will have to look deeper in the types being used for this one.
   I will rewrite the tests with cmd_lib and push the commit. But I'm sure you have some good hints for me based on the info I gave above 🥺 ?

[iulianbarbu]

I would like to add that I also tried using cmd_lib instead of command_macro!, but I also get a crate related error in this case 😞

Compiling chain-spec-guide-runtime v0.0.0 (/home/kazu/Polkadot/polkadot-sdk/docs/sdk/src/reference_docs/chain_spec_runtime)
  error[E0433]: failed to resolve: could not find `unix` in `os`
    --> /home/kazu/.cargo/registry/src/index.crates.io-6f17d22bba15001f/os_pipe-1.2.1/src/unix.rs:6:14
     |
  6  | use std::os::unix::prelude::*;
     |              ^^^^ could not find `unix` in `os`
     |

Hey @ndkazu. Can you please give a sample of the cmd_lib code you're using? Can you confirm you're developing on Linux?

@iulianbarbu , I am using this example to use cmd_lib on native Linux/Ubuntu. I see that the library is also used in /home/kazu/Polkadot/polkadot-sdk/substrate/bin/utils/chain-spec-builder/tests/test.rs, but then I have the following questions:

1. I don't see `#[cmd_lib::main]`

2. Instead of using `run_cmd!`, `spawn_with_output!` is used.

3. there is also the fact that methods used on the output of `Command::new(...)` such as .`output()` or `.stdout` are not available when using `run_cmd!` or `spawn_with_output!`...I guess I will have to look deeper in the types being used for this one.
   I will rewrite the tests with `cmd_lib` and push the commit. But I'm sure you have some good hints for me based on the info I gave above 🥺 ?

Oh, I see. The example you're using is fine, but lemme respond to your qs below:

1. No need to use #[cmd_lib::main] when using the rest of the macros like run_cmd! or spawn_with_output!. That macro is just used for convenience to log errors easily, but in our case we don't need it.
2. Yup, we use it because we redirect some commands output to /dev/stdout, and by using the macro we can get the output from stdout as a String and compare it to something we expect to get as a result (this is especially useful when you run doc tests, that ensure the documentation examples are up to date). This might not be useful for all the commands we want to replace in our docs, and sometimes we might just want to assert against success or failure, and run_cmd! is enough for it.
3. I think you are right, run_cmd! returns a simple CmdResult, which is a wrapper over std::io::Result<()>, so it should tell a few things about failures in case they happen. I think this should be enough though for most of the cases.

[ndkazu]

Issue can now be closed 😺

[iulianbarbu]

Thanks @ndkazu !