clap-documentation

Automatically generate Markdown or AsciiDoc documentation for clap command-line tools.

Examples

Generate Markdown text for a basic clap app:

#[derive(clap::Parser)]
struct Cli {
    #[arg()]
    name: String,
}

let markdown: String = clap_documentation::help_markdown::<Cli>();

Generate AsciiDoc text for a basic clap app:

#[derive(clap::Parser)]
struct Cli {
    #[arg()]
    name: String,
}

let asciidoc: String = clap_documentation::help_asciidoc::<Cli>();

Generated Examples:

See clap example programs and the corresponding documentation generated by clap-documentation:

Program	Markdown	AsciiDoc
./complex_app.rs	complex-app.md	complex-app.adoc

Usage Convention

This section describes a suggested convention for using clap-documentation to generate a CommandLineHelp.md or CommandLineHelp.adoc file, which can be committed to source control and viewed as online documentation.

1. Add hidden --markdown-help and/or --asciidoc-help options to your clap application:

use clap::Parser;

#[derive(Parser)]
struct Cli {
    #[arg(long, hide = true)]
    markdown_help: bool,

    #[arg(long, hide = true)]
    asciidoc_help: bool,
}

fn main() {
    let args = Cli::parse();

    if args.markdown_help {
        clap_documentation::print_help_markdown::<Cli>();
    }
    if args.asciidoc_help {
        clap_documentation::print_help_asciidoc::<Cli>();
    }
}

2. Invoke the option to generate a documentation file:

$ cargo run -- --markdown-help > docs/CommandLineHelp.md
$ cargo run -- --asciidoc-help > docs/CommandLineHelp.adoc

3. Save the file in git, and link to it from the project's README.md or other relevant documentation.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See Development.md for instructions on how to perform common development tasks.