Commits on Jul 19, 2022

1. 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 clap-rs#3189

   

   epage committed Jul 19, 2022
   Configuration menu

   • View commit details
   • Copy full SHA for d43f1db
   • Browse repository at this point

   Copy the full SHA

   d43f1db View commit details

   Browse the repository at this point in the history