clap-markdown-dfir 0.2.0

Autogenerate Markdown documentation for clap command-line tools
Documentation

clap-markdown

Crates.io License Documentation

API Documentation | Changelog | Contributing

Automatically generate Markdown 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_markdown_dfir::help_markdown::<Cli>();

Generated Markdown Examples:

See clap example programs and the corresponding Markdown generated by clap-markdown:

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

Usage Convention: CommandLineHelp.md

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

  1. Add a hidden --markdown-help option to your clap application:
use clap::Parser;
use clap_markdown_dfir::MarkdownOptions;

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

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

    // Invoked as: `$ my-app --markdown-help`
    if args.markdown_help {
        clap_markdown_dfir::print_help_markdown::<Cli>(MarkdownOptions::default());
    }
}
  1. Invoke --markdown-help to generate a CommandLineHelp.md file:
$ cargo run -- --markdown-help > docs/CommandLineHelp.md
  1. Save CommandLineHelp.md in git, and link to it from the project's README.md or other relevant documentation.

For projects that have multiple associated executables, consider using the command name as a suffix. For example: CommandLineHelp-your-app.md, CommandLineHelp-other-app.md.

Comitting CommandLineHelp.md to version control makes it easy to track user-visible changes to the command-line interface.

Projects using clap-markdown

The following projects use clap-markdown to generate a CommandLineHelp.md reference document:

To request the addition of a project to this list, please file an issue.

Compatibility with clap

When this crate adds support for a new MAJOR version of clap, the MAJOR version number of clap-markdown will be changed.

Compability History:

clap-markdown clap
v0.0.1 – v0.1.3 "4.*.*"

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.

See Maintenance.md for instructions on how to maintain this project.