Automatically generate Markdown documentation for
clap
command-line tools.
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 |
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.
- Add a hidden
--markdown-help
option to yourclap
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());
}
}
- Invoke
--markdown-help
to generate aCommandLineHelp.md
file:
$ cargo run -- --markdown-help > docs/CommandLineHelp.md
- 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.
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.
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.*.*" |
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.
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.