I’ve been working on a tool written in Rust for the past few months, and getting very close to putting it into production at Mozilla. After that milestone I’m planning on doing some work to make it usable for developers in general. One thing I haven’t found a good answer for is writing useful documentation for a command-line tool. rustdoc is great for library crates, but it doesn’t seem very useful for a tool, where you want to document the command-line options and other features.
Obviously I could just hand-write some documentation in markdown or HTML, but it would be nice if I could also have the documentation for command-line options generated from the data structures I’m passing to clap that define the allowed set of options.
I did a little brief searching and didn’t find anything relevant to this problem, although there is a semi-related issue in the Rust tracker for providing HTML versions of the man pages for
cargo et. al. Those man pages appear to just be committed to the rust and cargo repositories as-is. It might be nice if it was possible to generate them from the source as well, so that as much of the documentation could live near the code that declares it as possible.
If anyone knows of any efforts in this area I’d love to hear about them!