docs (teaching)
Create a "Rust Bookshelf" of learning resources for Rust.
rust-lang/book, which holds the second
edition, currently.This is largely about how doc.rust-lang.org is organized; today, it points to the book, the reference, the nomicon, the error index, and the standard library docs. This suggests unifying the first three into one thing.
There are a few independent motivations for this RFC.
These will be discussed further in the detailed design.
Several new repositories will be made, one for each of:
These would live under the rust-lang organization.
They will all use mdBook to build. They will have their existing text re-worked into the format; at first a simple conversion, then more major improvements. Their current text will be removed from the main tree.
The first edition of the book lives in-tree, but the second edition lives in
rust-lang/book. We'll remove the existing text from the tree and move it
into rust-lang/book.
A new book will be created from the "Nightly Rust" section of the book. It will be called "The Nightly Book," and will contain unstable documentation for both rustc and Cargo, as well as material that will end up in the reference. This came up when trying to document RFC 1623. We don't have a unified way of handling unstable documentation. This will give it a place to develop, and part of the stabilization process will be moving documentation from this book into the other parts of the documentation.
The nightly book will be organized around #![feature]s, so that you can look
up the documentation for each feature, as well as seeing which features
currently exist.
The nightly book is in-tree so that it runs more often, as part of people's
normal test suite. This doesn't mean that the book won't run on every commit;
just that the out-of-tree books will run mostly in CI, whereas the nightly
book will run when developers do x.py check. This is similar to how, today,
Traivs runs a subset of the tests, but buildbot runs all of them.
The landing page on doc.rust-lang.org will show off the full bookshelf, to let people find the documenation they need. It will also link to their respective repositories.
Finally, this creates a path for more books in the future: "the FFI Book" would be one example of a possibility for this kind of thing. The docs team will develop critera for accepting a book as part of the official project.
The landing page on doc.rust-lang.org will show off the full bookshelf, to let people find the documenation they need. It will also link to their respective repositories.
A ton of smaller repos can make it harder to find what goes where.
Removing work from rust-lang/rust means people aren't credited in release
notes any more. I will be opening a separate RFC to address this issue, it's
also an issue without this RFC being accepted.
Operations are harder, but they have to change to support this use-case for other reasons, so this does not add any extra burden.
Do nothing.
Do only one part of this, instead of the whole thing.
Move all of the "bookshelf" into one repository, rather than individual ones. This would require a lot more label-wrangling, but might be easier.
How should the first and second editions of the book live in the same repository?
What criteria should we use to accept new books?
Should we adopt "learning Rust with too many Linked Lists"?