clap-markdown

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:

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());
    }
}

2. Invoke --markdown-help to generate a CommandLineHelp.md file:

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

3. 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:

• wolfram-app-discovery — CommandLineHelp.md
• wolfram-cli — CommandLineHelp.md

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:

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.

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