Rust bookshelf

[steveklabnik]

rendered

Create a "Rust Bookshelf" of learning resources for Rust.

• Pull the book out of tree into rust-lang/book, which holds the second edition, currently.
• Pull the nomicon and the reference out of tree and convert them to mdBook.
• Pull the cargo docs out of tree and convert them to mdBook.
• Create a new "Nightly Book" in-tree.
• Provide a path forward for more long-form documentation to be maintained by the project.

/cc @rust-lang/core, @rust-lang/docs , @brson

[XAMPPRocky]

How should the first and second editions of the book live in the same repository?

I think this should depend on what happens to the first edition when the second one is released? Does the first edition stay as it is warts and all? Then it should probably be a git tag, something that easy to reference, but hidden a bit away so new people don't accidentally get linked it. However if the first edition will still see stuff like correcting typos, then it should exist on a seperate branch.

[steveklabnik]

@Aaronepower this is a good point. I think my inclination is to let both of them stay visible, and while not doing any work on the first edition, accept PRs for minor things like that. I'm open to suggestions, though.

[valarauca]

If one could add The Little Book of Macros ref to the list?

I'm aware it is out of tree, and not official but it is a solid reference for intermediate to advanced Rust Programmers. It seems any book shelf of Rust reference material would be wanting without that.

(Or maybe Rust Book 2.0 covers that subject sufficiently?)

[ticki]

What about a list of Rust-related blogs as well? There are plenty of those too (recent example: 24 days of Rust).

[steveklabnik]

@valarauca if @DanielKeep is interested; I am: macros documentation has always been very weak.

@ticki blog posts are too contemporary usually; 24 days of Rust is amazing, but not really suitable as official documentation; we try not to play favorites with the ecosystem, and so don't link to any external crates not in the rust-lang org in official docs. (With the small exception of rand because when we made the decision, we thought it would be out of the nursery by now, but that's an exception and it will make it there eventually.)

That is, this is not attempt to just link to every useful bit of thing to learn Rust; it's about making other long-form docs than the book more prominent, as well as reorganizing their repositories.

[hoodie]

Yet a planet.rust-lang.org would be appreciated

[XAMPPRocky]

A ton of smaller repos can make it harder to find what goes where.

This sort of moves the problem up, what about a seperate GitHub org? eg. rust-lang-bookshelf which contains all the resources for learning rust. This might add more administrative work though.

I was also wondering about translations of these books, and how they might fit into this?

[steveklabnik]

This might add more administrative work though.

Yes, I'm not 100% sure what a separate org buys us. Other "related" orgs are usually because they're not quite "official" yet, but all of this stuff is considered hosted by the project.

I was also wondering about translations of these books, and how they might fit into this?

https://github.com/azerupi/mdBook/issues/5

[sgrif]

Has pulling them out into a single "bookshelf" repo been considered, rather than one repo per book?

[steveklabnik]

@sgrif I'll add that as an alternative soon. I prefer per-repo as it's easier to track issues individually, but this would work with tags too.

[steveklabnik]

I left something out of the RFC that I forgot, since it was a holiday, so I'll write a simple version here to remind myself to add it later:

the nightly book has to be in-tree because it will be run as tests more often, and is more likely to break. The out-of-repo stuff will be run on travis per commit to rust-lang/rust. So this is kinda like how we run the most common tests on travis + buildbot, but the full test suite on only buildbot today: nightly book will run as part of the compiler's tests, but the full bookshelf will be tested when trying to land PRs.

[burdges]

It's wonderful the Rust Book, Standard Library Reference, and Nomicon are installed with the compiler so that people can refer to them while offline. This should be preserved.

If anything, more should be installed locally, like documentation for nursery crates, links to documentation for crates built locally, and the playpen, at least until Rust gets a REPL. All this is a property of rustup.sh, etc. though, not the repository layout.

[steveklabnik]

This would definitely still be true after these changes.

…

On Sun, Dec 25, 2016 at 2:43 PM, Jeff Burdges ***@***.***> wrote: It's wonderful the Rust Book, Standard Library Reference, and Nomicon are installed with the compiler so that people can refer to them while offline. This should be preserved. If anything, more should be installed locally, like documentation for nursery crates, links to documentation for crates built locally, and the playpen, at least until Rust gets a REPL. All this is a property of rustup.sh, etc. though, not the repository layout. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#1828 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABsimBAvIcMs6YvhIYFVs3JeKBeAxaTks5rLsdJgaJpZM4LVbkR> .

[brson]

This looks good to me. Thanks for taking action on this.

It might be worth considering putting all the docs into one repository, instead of multiple. It could make Rust docs a more cohesive project, a single repo for Rust doc enthusiasts to rally around. One build system and issue tracker for the entire bookshelf. One place to go to improve the Rust documentation.

The RFC could make it more clean what "the bookshelf" is. It sounds like a product, but the RFC is mostly talking about how the documentation source is organized. "A landing page on doc.rust-lang.org will show the full bookshelf". So that landing page seems to be how the bookshelf is manifested, but that page already exists, so what's different?

One way to clarify what the bookshelf is is to clarify how it is defined. I might expect the bookshelf to be an independent product with its own build system, at rust-lang/rust-bookshelf. Perhaps what it outputs is what's ultimately presented at doc.rust-lang.org. Then the rust build system can build the bookshelf and package it as rust-docs.

There would be some questions about how to integrate nightly docs and std docs into the rust-bookshelf build and/or the rust-docs package.

[briansmith]

Pull the nomicon and the reference out of tree

Maybe I'm misunderstanding, but this doesn't sound like a good idea to me. The Rust Reference should be updated by every RFC PR and/or implementation PR that changes the language. Pulling it out of the tree would create friction and make it more likely that the reference isn't updated in sync with the code.

Similarly, my understanding is that the nomicon is basically a sketch of the memory model and it should be updated by code change PRs that make assumptions about and/or define the memory model.

[eminence]

I wonder if having everything in one repo would makes it easier for separate books to reference/hyperlink to each other?

To add a follow-up to @briansmith 's question : rust-lang.org describes the reference manual as "It tends to be out of date". Is there anything we can do to improve this book to a point where we'd feel comfortable removing the "tends to be out of date" disclaimer?

[mcpherrinm]

There was a recent RFC requiring documentation updates for other changes to the Rust language though I admit that I didn't read it.

I think it makes a lot of sense to keep the reference in-tree and require any semantic changes merged into Rust also have the reference updated to match.

Otherwise you run into a problem of keeping docs in sync with rust versions. This RFC should probably propose how to do that, if the reference is kept out of tree.

[steveklabnik]

@briansmith @eminence @mcpherrinm

So, to be clear about the process here again:

1. We now have an RFC that says that documentation must be updated before a feature becomes stable.
2. This RFC proposes that this documentation should land in the Unstable Book.
3. That book is in-tree, so that examples run as part of the regular test suite, so breakage should be caught early.
4. Part of the stabilization process is moving those docs out of the unstable book and into the reference.
5. Once it's stable, it should not have incompatible changes, and so it's really about catching bugs. That's why it's still run by CI for every commit.

Does that make sense? This is why I think it's fine for the reference to be out of tree: it should not be updated "when things change", because that means it's too early for it to be in the reference.

@brson

One place to go to improve the Rust documentation.

This is still not true; Rust by Example and the standard library API docs wouldn't be in this repository, for example. That's one reason why I favor independent repos; it lets them grow independently. I don't like two repositories with multiple things in them very much; of course, the tricky bit is how you define "thing"...

[azerupi]

The notion of "Nightly book" is relatively vague in the RFC, it may be worth detailing a bit?

Is it supposed to be an in-tree copy of the TRPL with extra chapters for unstable features, or is it a completely separate book which only covers unstable features? I assume it's the latter one.

[steveklabnik]

I assume it's the latter one.

Yes, your assumption is correct. I'll try to clarify.

[steveklabnik]

Oh, @eminence , sorry, I forgot this:

I wonder if having everything in one repo would makes it easier for separate books to reference/hyperlink to each other?

It does not make anything easier or harder, given that they both end up in the same place for the final artifact, regardless of the situation with the repositories.

[killercup]

I think the notion of a nightly book that lives in-tree is an interesting idea. That sounds like the reference should not contain any notion of nightly features, though, which is debatable. There is probably still a RFC to be written about refactoring the reference in a unified style anyway (with structured and concise descriptions, and tested grammar code examples).

---

Where do these new repos live? Did I miss this? Directly in the rust-lang orga? Do they move through the orgas like other crates, i.e., start out in rust-lang-nursery? How about creating a new Github organization rust-bookshelf where all community-written books can have a place?

---

As an aside, I'm looking at mdBook every now and then and always think to myself, "I should help out and do something to make the rendered HTML nicer", or "maybe I can add a subcommand to make it output markdown that is easy for pandoc to parse and convert to {HTML, PDF, EPUB}". There are a lot of opportunities there, and everything from @azerupi I've seen so far has been quite good! I think with a bit of concentrated effort we can make this into a really powerful tool. Sadly, I don't think I have any time to help out any time soon unless someone actually hires me to do this. :(

[steveklabnik]

That sounds like the reference should not contain any notion of nightly features, though, which is debatable.

Yes, this is proposing that it should not. Or at least, it should explain the concept of nightly, but not any of the actual nightly stuff.

Where do these new repos live? Did I miss this?

I didn't spell it out, but I should have. The answer is rust-lang, in my estimation. They're already in the org.

The idea of a unified repo or organization was mentioned upthread; I could maybe see what a unified repo would get us, but I don't see what a separate organization would.

[tshepang]

I prefer the reference be left in-tree, and get updated every time a language change stabilises. Separating the two will cause friction... having to update a reference on one repository and then stabilising a feature on another.

[tshepang]

The nomicon can be pulled out given that it's long-form, relaxed writing, akin to a (long) blog post. Maybe it's core parts should be used in the language reference, and presented in a cold and terse style I expect a reference should be.

[Ericson2314]

If there is a "nightly book" in tree for rust, I feel there should be something similar in tree for Cargo, especially with Cargo getting unstable features (as is/was the tentative plan for std-aware Cargo).

[XAMPPRocky]

@steveklabnik I wouldn't know. When people say they have a meeting about something it usually comes with changes. 😂

[steveklabnik]

I hear you! It was mostly just a check-in: did everyone see this RFC, did you read it, etc.

[steveklabnik]

@rfcbot fcp merge

@dikaiosune says I should do this again 😄

[rfcbot]

Team member @steveklabnik has proposed to merge this. The next step is review by the rest of the tagged teams:

• @GuillaumeGomez
• @frewsxcv
• @jonathandturner
• @peschkaj
• @steveklabnik

No concerns currently listed.

Once these reviewers reach consensus, this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[steveklabnik]

@peschkaj is taking some time off from the docs team, so I've checked their box.

[frewsxcv]

• @frewsxcv

;)

[steveklabnik]

@frewsxcv already working on fixing that ❤️

[sophiajt]

I don't know how to use rfcbot, but 👍 from me.

[steveklabnik]

@jonathandturner you can either check the box or say "@rfcbot: reviewed" in a comment

@frewsxcv i have confirmed with @dikaiosune that this is fixed, and you'll be in for the next one 😄

[GuillaumeGomez]

@rfcbot: reviewed

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period is now complete.

[steveklabnik]

Hooray! this RFC has been accepted.

Tracking issue: rust-lang/rust#39588