clap-documentation 0.1.0

Autogenerate Markdown or Asciidoc documentation for clap command-line tools
Documentation

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>();
    }
}
  1. Invoke the option to generate a documentation file:
$ cargo run -- --markdown-help > docs/CommandLineHelp.md
$ cargo run -- --asciidoc-help > docs/CommandLineHelp.adoc
  1. Save the file in git, and link to it from the project's README.md or other relevant documentation.

License

Licensed under either of

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.