clap-documentation 0.1.0

Autogenerate Markdown or Asciidoc documentation for clap command-line tools
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

# clap-documentation

Automatically generate Markdown or AsciiDoc 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_documentation::help_markdown::<Cli>();
```

Generate AsciiDoc text for a basic `clap` app:

```rust
#[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`](./docs/examples/complex_app.rs) | [complex-app.md](./docs/examples/complex-app.md) | [complex-app.adoc](./docs/examples/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:

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

2. Invoke the option to generate a documentation file:

  ```shell
  $ cargo run -- --markdown-help > docs/CommandLineHelp.md
  $ cargo run -- --asciidoc-help > docs/CommandLineHelp.adoc
  ```

3. Save the file in git, and link to it from the project's README.md
   or other relevant documentation.

## License

Licensed under either of

  * Apache License, Version 2.0
    ([LICENSE-APACHE](./LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
  * MIT license
    ([LICENSE-MIT](./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**](./docs/Development.md) for instructions on how to
perform common development tasks.