Switch documentation to a book format?

[ehuss]

I wanted to ask if you would be interested in moving the documentation for rustup to a book format? I personally find the single-page README a bit difficult to navigate. I would suggest mdbook hosted on gh-pages (https://rust-lang.github.io/rustup/ or maybe even just https://rustup.rust-lang.org/), with maybe a slightly different outline of chapters/sections. I'd be happy to work on this (and to maintain it), so let me know if you are interested.

A rough outline may be something like:

Introduction

• Installation
• Concepts (introduces "channels", "toolchains", "components", "profiles", and how it works)
• Basic usage
  • Updating toolchains
  • Keeping Rust up-to-date
  • Keeping rustup up-to-date
• Overrides
• Cross-compilation
• Working with distributions
• Custom toolchains
• Network settings ? "Networking"? "Network proxies"?
• Configuration
• Environment variables
• Examples
• Security
• FAQ

[kinnison]

I see no reason to say "no" to better organised documentation; however I do worry that people already know to link to the README. I suppose we can link from there to the mdbook. Would the content come from the rustup repo or from a different one, and can we use github-actions to publish the results easily?

[ehuss]

Yea, I would also be concerned about existing links to the README and the disruption to those that are already familiar with the existing docs. That is pretty hard to avoid. Of course the README would be changed to call out the new book (and would also probably contain a few small things like maybe the license?). Unfortunately there is no way to redirect links that I know of.

The content would live in the rustup repo, and publishing from github actions is pretty easy.

[kinnison]

Sounds good, If you can knock up an example on a fork then I'd love to see how you envisage it looking, both from an output PoV and also from the perspective of someone who has to edit the content.

[ehuss]

I have posted a preview at https://ehuss.github.io/rustup/ (source is at https://github.com/ehuss/rustup/tree/rustup-book/doc). Let me know what you think and if you are still interested.

[kinnison]

I really like the look / shape. I agree it communicates somewhat better than the current wall-of-text. However I'd really prefer that it were generated from the main rustup repo, so I guess the next step would be to translate that work into a fork of rustup so that you can PR it? It's not clear to me how that is then built and published, can you show how github actions would do that? We'd probably only want the main book re-published on stable releases, but perhaps if it's possible we could publish a book from mainline as well?

[ehuss]

Yea, I can work on the CI integration. I think in the short term it might be better to publish from master, just to deal with any updates that might be needed to fix before the next release. It can probably then be transitioned to publish from stable if it doesn't have much churn (and can probably set up some kind of manual publish if really necessary).