Add support for building and hosting mdBook content

[shepmaster]

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!

[GuillaumeGomez]

How do we handle different themes between rustdoc and mdBook?

• Don't worry about it, allow them to differ

This is actually my biggest worry: it's very important to keep a unified UX. I guess it can be simply fixed by adding "rustdoc dark theme" and "rustdoc light theme" in mdbook and then allow enable rustdoc dark, ayu and rustdoc light themes when generating the mdbook.

[Nemo157]

My first thought on the URL would be to have it like https://docs.rs/crate-name/x.y.z/book-name (I'm not sure if mdBook has some kind of book-name, that could be the subdir name if not). That allows for compatibility with multiple-books, but does bring up questions about what to do if the book-name conflicts with one of the targets [in both the "target crate" sense and "target platform" sense 😁] (especially if we start building documentation for binary and example targets too).

[jyn514]

Do we support multiple books per crate?

Handling multiple books sounds hard and I think hosting your own site where you can control the styles makes sense at that point.

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?

This should hook in to the rest of the themes I think, the same way rustdoc themes work now. If mdbook has a theme docs.rs doesn't recognize, make no change.

Do we support mdBook plugins?

I think for an MVP we can just have no plugins and add them later if people want them.

[steveklabnik]

See also rust-lang/rust#66249

[syphar]

draft PR in rustdoc: rust-lang/rust#139769

( also there was some discussion at the rust all-hands)