mirror of
https://github.com/clap-rs/clap
synced 2024-12-14 23:02:31 +00:00
d43f1dbf6f
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
2.4 KiB
2.4 KiB
This requires enabling the [derive feature flag][crate::_features].
Git is an example of several common subcommand patterns.
Help:
$ git-derive
? failed
git
A fictional versioning CLI
USAGE:
git-derive[EXE] <SUBCOMMAND>
OPTIONS:
-h, --help Print help information
SUBCOMMANDS:
add adds things
clone Clones repos
help Print this message or the help of the given subcommand(s)
push pushes things
stash
$ git-derive help
git
A fictional versioning CLI
USAGE:
git-derive[EXE] <SUBCOMMAND>
OPTIONS:
-h, --help Print help information
SUBCOMMANDS:
add adds things
clone Clones repos
help Print this message or the help of the given subcommand(s)
push pushes things
stash
$ git-derive help add
git-derive[EXE]-add
adds things
USAGE:
git-derive[EXE] add <PATH>...
ARGS:
<PATH>... Stuff to add
OPTIONS:
-h, --help Print help information
A basic argument:
$ git-derive add
? failed
git-derive[EXE]-add
adds things
USAGE:
git-derive[EXE] add <PATH>...
ARGS:
<PATH>... Stuff to add
OPTIONS:
-h, --help Print help information
$ git-derive add Cargo.toml Cargo.lock
Adding ["Cargo.toml", "Cargo.lock"]
Default subcommand:
$ git-derive stash -h
git-derive[EXE]-stash
USAGE:
git-derive[EXE] stash [OPTIONS]
git-derive[EXE] stash <SUBCOMMAND>
OPTIONS:
-h, --help Print help information
-m, --message <MESSAGE>
SUBCOMMANDS:
apply
help Print this message or the help of the given subcommand(s)
pop
push
$ git-derive stash push -h
git-derive[EXE]-stash-push
USAGE:
git-derive[EXE] stash push [OPTIONS]
OPTIONS:
-h, --help Print help information
-m, --message <MESSAGE>
$ git-derive stash pop -h
git-derive[EXE]-stash-pop
USAGE:
git-derive[EXE] stash pop [STASH]
ARGS:
<STASH>
OPTIONS:
-h, --help Print help information
$ git-derive stash -m "Prototype"
Pushing StashPush { message: Some("Prototype") }
$ git-derive stash pop
Popping None
$ git-derive stash push -m "Prototype"
Pushing StashPush { message: Some("Prototype") }
$ git-derive stash pop
Popping None
External subcommands:
$ git-derive custom-tool arg1 --foo bar
Calling out to "custom-tool" with ["arg1", "--foo", "bar"]