Writing or generating documentation for command-line tools?

luser · November 17, 2016, 3:58pm

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 rustc 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!

skade · November 17, 2016, 4:25pm

Well, it’s not quite what you are searching for, but clap already does a lot with this info to generate completions.

So, maybe you can write a similar thing to extract the data and write them to a format you can use in your documentation.

github.com

kbknapp/clap-rs/blob/master/src/completions/mod.rs

#[macro_use]
mod macros;
mod bash;
mod fish;
mod zsh;
mod powershell;
mod shell;

// Std
use std::io::Write;

// Internal
use app::parser::Parser;
use self::bash::BashGen;
use self::fish::FishGen;
use self::zsh::ZshGen;
use self::powershell::PowerShellGen;
pub use self::shell::Shell;

pub struct ComplGen<'a, 'b>

This file has been truncated. show original

luser · November 18, 2016, 5:18pm

This looks useful, thanks! I was hoping that someone had already done some work in this space so I wouldn’t have to write something myself, but I appreciate that the Rust community always generally has something helpful to work from. I’ll make some noise if I find time to build something to make this better.

luser · February 7, 2018, 5:39pm

Replying to my own old thread seems gauche, but @BurntSushi tweeted about how he’s now generating the man page for ripgrep from the clap definitions:

musicmatze · February 7, 2018, 8:11pm

Holy crap, this is a hell of a setup. I would love if this would be less complicated. Best idea would be a clap->manpage functionality where one is able to attach own text to the output…