https://github.com/connorgray/clap-markdown
Autogenerate Markdown documentation for clap command-line tools
https://github.com/connorgray/clap-markdown
Last synced: about 1 year ago
JSON representation
Autogenerate Markdown documentation for clap command-line tools
- Host: GitHub
- URL: https://github.com/connorgray/clap-markdown
- Owner: ConnorGray
- License: apache-2.0
- Created: 2022-12-13T11:33:20.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-06-15T21:45:35.000Z (almost 2 years ago)
- Last Synced: 2025-04-04T23:28:58.898Z (about 1 year ago)
- Language: Rust
- Size: 32.2 KB
- Stars: 64
- Watchers: 3
- Forks: 17
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# clap-markdown
[](https://crates.io/crates/clap-markdown)
[](https://docs.rs/clap-markdown)
#### [API Documentation](https://docs.rs/clap-markdown) | [Changelog](./docs/CHANGELOG.md) | [Contributing](#contributing)
Automatically generate Markdown documentation for
[`clap`](https://crates.io/crates/clap) command-line tools.
## Examples
Generate Markdown text for a basic `clap` app:
```rust
#[derive(clap::Parser)]
struct Cli {
#[arg()]
name: String,
}
let markdown: String = clap_markdown::help_markdown::();
```
**Generated Markdown Examples:**
See `clap` example programs and the corresponding Markdown generated by
`clap-markdown`:
| Program | Markdown |
|------------------------------------------------------|--------------------------------------------------|
| [`./complex_app.rs`](./docs/examples/complex_app.rs) | [complex-app.md](./docs/examples/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:
```rust
use clap::Parser;
#[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::print_help_markdown::();
}
}
```
2. Invoke `--markdown-help` to generate a `CommandLineHelp.md` file:
```shell
$ 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`](https://crates.io/crates/wolfram-app-discovery)
— [`CommandLineHelp.md`](https://github.com/WolframResearch/wolfram-app-discovery-rs/blob/master/docs/CommandLineHelp.md)
* [`wolfram-cli`](https://github.com/ConnorGray/wolfram-cli)
— [`CommandLineHelp.md`](https://github.com/ConnorGray/wolfram-cli/blob/main/docs/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:**
| `clap-markdown` | `clap` |
|-----------------|-----------|
| v0.0.1 – v0.1.4 | `"4.*.*"` |
## License
Licensed under either of
* Apache License, Version 2.0
([LICENSE-APACHE](./LICENSE-APACHE) or )
* MIT license
([LICENSE-MIT](./LICENSE-MIT) or )
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**](./docs/Development.md) for instructions on how to
perform common development tasks.
See [*Maintenance.md*](./docs/Maintenance.md) for instructions on how to
maintain this project.