Rendering documentation for your CLI apps

Documentation for CLIs usually consists ofa —help section in the commandand a manual (man) page.

Both can be automatically generatedwhen using clap v3 (in unreleased alpha,at time of writing), via the man backend.

#[derive(Clap)]
pub struct Head {
    /// file to load
    #[clap(parse(from_os_str))]
    pub file: PathBuf,
    /// how many lines to print
    #[clap(short = "n", default_value = "5")]
    pub count: usize,
}

Secondly, you need to use a build.rsto generate the manual file at compile timefrom the definition of your appin code.

There are a few things to keep in mind(such as how you want to package your binary)but for nowwe simply put the man filenext to our src folder.

use clap::IntoApp;
use clap_generate::gen_manuals;
#[path="src/cli.rs"]
mod cli;
fn main() {
    let app = cli::Head::into_app();
    for man in gen_manuals(&app) {
        let name = "head.1";
        let mut out = fs::File::create("head.1").unwrap();
        use std::io::Write;
        out.write_all(man.render().as_bytes()).unwrap();
    }
}

When you now compile your applicationthere will be a head.1 filein your project directory.

If you open that in manyou’ll be able to admire your free documentation.