Commit graph

13 commits

Author SHA1 Message Date
Ed Page
65b5b5f7bf fix(help): Remove name/version/author from help
This is to help shorten it and polish it by removing redundant
information.

This is a part of #4132
2022-08-31 15:06:15 -05:00
Ed Page
9b23a09f7a fix(help): Don't rely on ALL CAPS for headers
I see them fulfilling two roles
- A form of bolding
- As a callback to their placeholder in usage

However, it is a bit of an unpolished look and no other CLI seems to do
it.  This looks a bit more proefessional.  We have colored help for
formatting and I think the sections relation to usage will be clear
enough.
2022-08-26 10:21:18 -05:00
Ed Page
11076a5c70 fix(help)!: Make DeriveDisplayOrder the default, removing it
Force sorting with `next_display_order(None)`

Fixes #2808
2022-07-22 15:52:03 -05:00
Ed Page
d43f1dbf6f 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 13:30:38 -05:00
Hugo Osvaldo Barrera
7110401595 docs: Fix messed up highlighting
This just affects how it's rendered; rather than attempting to highlight
these blocks as a shell script, they'll get highlighted as console
output.

See the rendered versions for a better comparison.
2022-01-05 11:53:06 -06:00
Ed Page
9e64387ef0 revert(help): Partial revert of 3c049b4
The extra whitespace was targeted at machine processing for a subset of
users for a subset of runs of CLIs.  On the other hand, there is a lot
of concern over the extra verbose output.

A user can set the help template for man, if desired.  They can even do
something (env? feature flag?) to make it only run when doing man
generation.  We also have #3174 in the works.

So let's focus on the end-user reading `--help`.  People wanting to use
`help2man` have workarounds to do what they need.

Fixes #3096
2021-12-15 10:36:59 -06:00
Ed Page
32b5520ff1 docs: Call out features used in root examples
mitsuhiko immediately jumped into the examples and got tripped up by the
lack of documentation on feature flags needed.

I limited this to just the root ones because the rest are in a more
proper tutorial that steps through it all.
2021-12-08 16:46:49 -06:00
Ed Page
92750c6aa5 docs: Simplify demo 2021-12-07 17:45:57 -06:00
Ed Page
b2836c07a7 fix: Gracefully handle empty authors 2021-12-06 11:30:26 -06:00
Ed Page
f517c0ede1 docs: Remove author fields 2021-12-06 11:24:23 -06:00
Ed Page
7f8b1990bb docs: Iterate on examples from writing ref docs 2021-12-01 14:30:51 -06:00
Ed Page
befee6667b docs: Re-work examples
This creates distinct tutorial examples from complex feature examples
(more how-tos).  Both sets are getting builder / derive versions (at
least the critical ones).
2021-11-30 21:33:52 -06:00
Ed Page
f890bfa93b docs: Focus top-level README 2021-11-30 09:53:25 -06:00