I am a big fan of cargo-readme which will let me convert the rustdoc comments of my crate into a README.md. This way the auto-generated docs at https://lib.rs can stay in sync with https://crates.io's README section.

But for command-line tools, I would very much like for the rustdoc and the README to contain auto-generated runs of cli --help, and cargo-readme isn't really for that.

I am wondering if any of you have thought about getting this --help output in sync with both rustdoc and README.md? Of course, this mostly makes sense when there's a CLI that has auto-generated --help, since one can extract the help section during build without actually running the CLI executable.

To properly embed cli --help into rustdoc I'd need to have some kind of marker in the rustdoc that a build script can latch onto and substitute below. Letting that kind of embed code work with arbitrary commands would open up for a lot of flexibility, but also arbitrary code execution during build stinks.

Does something like this exist already?

2 posts - 2 participants

Read full topic