I am looking for some guidelines on how to document and test binaries provided by a crate.
I have a crate that produces several executables. I'd like to have a documentation page listing them all, along with command line flags and examples. What are possible approaches to that? Any good examples of such a documentation?
Also, I'd like to have integration tests for my executables. I need to run them with specific flags and input files and then to compare the output printed on the screen with the reference one. Is such a functionality already available?
Depending on how long and verbose your documentation for all binaries combined is, you could just list them all in the top-level documentation of your library. That's what I'd do if this doesn't result in an unreasonably long page. I also started to appreciate how clap added modules like _tutorial or _faq with the sole purpose of containing different parts of the documentation that go beyond API documentation.
Under the hood, all such tests depend on a particular feature of Cargo — it sets an environment variableCARGO_BIN_EXE_<name>, for every executable in your project, when running integration tests. So, you can then run the command however you like. trycmd specifically offers snapshot testing.