2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-14 23:02:31 +00:00
clap/examples/git-derive.md

173 lines
3.2 KiB
Markdown
Raw Normal View History

docs: Move everything to docs.rs A couple of things happened when preparing to release 3.0 - We needed derive documentation - I had liked how serde handled theres - I had bad experiences finding things in structopt's documentation - The examples were broken and we needed tests - The examples seemed to follow a pattern of having tutorial content and cookbook content - We had been getting bug reports from people looking at master and thinking they were looking at what is currently released - We had gotten feedback to keep down the number of places that documentation was located From this, we went with a mix of docs.rs and github - We kept the number of content locations at 2 rather than 3 by not having an external site like serde - We rewrote the examples into explicit tutorials and cookbooks to align with the 4 styles of documentation - We could test our examples by running `console` code blocks with trycmd - Documentation was versioned and the README pointed to the last release This had downsides - The tutorials didn't have the code inlined - Users still had a hard time finding and navigating between the different forms of documentation - In practice, we were less likely to cross-link between the different types of documentation Moving to docs.rs would offer a lot of benefits, even if it is only designed for Rust-reference documentation and isn't good for Rust derive reference documentation, tutorials, cookbooks, etc. The big problem was keeping the examples tested to keep maintenance costs down. Maybe its just me but its easy to overlook - You can pull documentation from a file using `#[doc = "path"]` - Repeated doc attributes get concatenated rather than first or last writer winning Remember these when specifically thinking about Rust documentation made me realize that we could get everything into docs.rs. When doing this - Tutorial code got brought in as was one of the aims - We needed to split the lib documentation and the README to have all of the linking work. This allowed us to specialize them according to their rule (user vs contributor) - We needed to avoid users getting caught up in making a decision between Derive and Builder APIs so we put the focus on the derive API with links to the FAQ to help users decide when to use one or the other. - Improved cross-referencing between different parts of the documentation - Limited inline comments were added to example code - Introductory example code intentionally does not have teaching comments in it as its meant to give a flavor or sense of things and not meant to teach on its own. This is a first attempt. There will be a lot of room for further improvement. Current know downsides: - Content source is more split up for the tutorials This hopefully addresses #3189
2022-07-19 18:29:31 +00:00
**This requires enabling the [`derive` feature flag][crate::_features].**
Git is an example of several common subcommand patterns.
Help:
```console
$ git-derive
? failed
A fictional versioning CLI
Usage: git-derive[EXE] <COMMAND>
Commands:
clone Clones repos
diff Compare two commits
push pushes things
add adds things
stash
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
$ git-derive help
A fictional versioning CLI
Usage: git-derive[EXE] <COMMAND>
Commands:
clone Clones repos
diff Compare two commits
push pushes things
add adds things
stash
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
$ git-derive help add
adds things
Usage: git-derive[EXE] add <PATH>...
Arguments:
<PATH>... Stuff to add
Options:
-h, --help Print help
```
A basic argument:
```console
$ git-derive add
? failed
adds things
Usage: git-derive[EXE] add <PATH>...
Arguments:
<PATH>... Stuff to add
Options:
-h, --help Print help
$ git-derive add Cargo.toml Cargo.lock
Adding ["Cargo.toml", "Cargo.lock"]
```
Default subcommand:
```console
$ git-derive stash -h
Usage: git-derive[EXE] stash [OPTIONS]
2023-11-09 18:46:16 +00:00
git-derive[EXE] stash push [OPTIONS]
git-derive[EXE] stash pop [STASH]
git-derive[EXE] stash apply [STASH]
git-derive[EXE] stash help [COMMAND]...
Options:
-m, --message <MESSAGE>
-h, --help Print help
2023-11-09 19:22:08 +00:00
git-derive[EXE] stash push:
-m, --message <MESSAGE>
-h, --help Print help
git-derive[EXE] stash pop:
-h, --help Print help
[STASH]
git-derive[EXE] stash apply:
-h, --help Print help
[STASH]
git-derive[EXE] stash help:
Print this message or the help of the given subcommand(s)
2023-11-09 19:22:08 +00:00
[COMMAND]... Print help for the subcommand(s)
$ git-derive stash push -h
Usage: git-derive[EXE] stash push [OPTIONS]
Options:
-m, --message <MESSAGE>
-h, --help Print help
$ git-derive stash pop -h
Usage: git-derive[EXE] stash pop [STASH]
Arguments:
[STASH]
Options:
-h, --help Print help
$ git-derive stash -m "Prototype"
Pushing StashPushArgs { message: Some("Prototype") }
$ git-derive stash pop
Popping None
$ git-derive stash push -m "Prototype"
Pushing StashPushArgs { message: Some("Prototype") }
$ git-derive stash pop
Popping None
```
External subcommands:
```console
$ git-derive custom-tool arg1 --foo bar
Calling out to "custom-tool" with ["arg1", "--foo", "bar"]
```
Last argument:
```console
$ git-derive diff --help
Compare two commits
Usage: git-derive[EXE] diff [OPTIONS] [COMMIT] [COMMIT] [-- <PATH>]
Arguments:
[COMMIT]
[COMMIT]
[PATH]
Options:
--color[=<WHEN>] [default: auto] [possible values: always, auto, never]
-h, --help Print help
$ git-derive diff
Diffing stage..worktree (color=auto)
$ git-derive diff ./src
Diffing stage..worktree ./src (color=auto)
$ git-derive diff HEAD ./src
Diffing HEAD..worktree ./src (color=auto)
$ git-derive diff HEAD~~ -- HEAD
Diffing HEAD~~..worktree HEAD (color=auto)
$ git-derive diff --color
Diffing stage..worktree (color=always)
$ git-derive diff --color=never
Diffing stage..worktree (color=never)
```