Add support for building and hosting mdBook content

Motivation

One of the best aspects of docs.rs is that it encourages developers to create high-quality API-focused documentation by removing roadblocks around building and hosting the generated content.

I think it would be wonderful to extend this concept to building and hosting longer-form documentation produced by mdBook. This will encourage developers to produce this style of content as a complement to the rustdoc-generated documentation.

Guide-level explanation

1. Add this to your Cargo.toml:

   [package.metadata.docs.rs]
   mdbook = "some-subdir"
   

2. Push your code to crates.io

3. After a bit, visit https://docs.rs/book/crate-name/x.y.z

Drawbacks

• Increased load on the build machines.
  • May be negligible compared to building dependencies
• Increased crate sizes
  • Text content isn't that big, but books may include media like images.

Unresolved questions

• How do we make access to the book "obvious"?
  • Suggestion: Make it another tab in the top bar
  • Suggestion: Make it another button next to 'Documentation'
• How do we handle different themes between rustdoc and mdBook?
  • Suggestion: Don't worry about it, allow them to differ
  • Suggestion: Add "rustdoc dark theme" and "rustdoc light theme" to mdBook, only enable those themes + ayu (the common themes) when generating the book
• How frequently can books be built?
  • Suggestion: Only when crates are pushed
• How does a user access the book content?
  • Suggestion: https://docs.rs/book/crate-name/x.y.z
  • Suggestion: https://docs.rs/crate-name/book/x.y.z
  • Suggestion: https://docs.rs/crate-name/x.y.z/book-name (where book-name is the name of the book, not a hard-coded string)
• How does the builder access the book source?
  • Suggestion: The book source code is packaged with the crate uploaded to crates.io
• Do we support multiple versions of mdBook?
  • Suggestion: Only support the latest version
• Do we support mdBook plugins?
  • Suggestion: None to start with
• Do we support multiple books per crate?
  • Suggestion: Only support one book. Books can have sections, multiple crates can be uploaded, or people can perform their own hosting.
• How do we bind the JS events for the theme change? Should we limit it to the book or apply it to the rest of docs.rs too?

Future possibilities

• Improve the UX on docs.rs to make the integration better

Please feel free to edit this summary comment!

Start by reviewing the proposed Cargo.toml metadata and the docs.rs/crates.io build and hosting flow described in the issue. Resolve the open questions around URLs, themes, versions, plugins, and multiple books before implementation. Done means a crate can declare an mdBook source, have it built, and expose the resulting book at a defined docs.rs location.