From 77b570f831c128278f3716f887f3d8e0efe6801e Mon Sep 17 00:00:00 2001 From: steveklabnik Date: Tue, 3 Apr 2018 12:38:53 -0400 Subject: [PATCH] Re-write the documentation index The docs team has decided that we're framing resources in three ways: "learning Rust," "using Rust," "mastering Rust." This is a more useful split than "beginner/intermediate/advanced." As we add more resources in the future, we expect "using Rust" to grow. "the bookshelf" as a concept is great, but isn't really organized along these lines. As such, this reorganizes the docs along these lines. --- src/doc/index.md | 109 +++++++++++++++++++++++++++-------------------- 1 file changed, 63 insertions(+), 46 deletions(-) diff --git a/src/doc/index.md b/src/doc/index.md index 3add2774105e0..2e36831d7e86f 100644 --- a/src/doc/index.md +++ b/src/doc/index.md @@ -6,55 +6,72 @@ nav { } -This page is an overview of the documentation included with your Rust install. -Other unofficial documentation may exist elsewhere; for example, the [Rust -Learning] project collects documentation from the community, and [Docs.rs] -builds documentation for individual Rust packages. +Welcome to an overview of the documentation provided by the Rust project. +All of these projects are managed by the Docs Team; there are other +unofficial documentation resources as well! -# API Documentation +Many of these resources take the form of "books"; we collectively call these +"The Rust Bookshelf." Some are large, some are small. -Rust provides a standard library with a number of features; [we host its -documentation here][api]. +## Learn Rust -# Extended Error Documentation +If you'd like to learn Rust, this is the spot for you! All of these resources +assume that you have programmed before, but not in any specific language: + +### The Rust Programming Language + +Affectionately nicknamed "the book," [The Rust Programming +Language](book/index.html) will give you an overview of the language from +first principles. You'll build a few projects along the way, and by the end, +you'll have a solid grasp of the language. + +### Rust By Example + +If reading multiple hundreds of pages about a language isn't your style, then +[Rust By Example](rust-by-example/index.html) has you covered. While the book talks about code with +a lot of words, RBE shows off a bunch of code, and keeps the talking to a +minimum. It also includes exercises! + +## Use Rust + +Once you've gotten familliar with the language, these resources can help you +when you're actually using it day-to-day. + +### The Standard Library + +Rust's standard library has [extensive API documentation](std/index.html), +with explanations of how to use various things, as well as example code for +accomplishing various tasks. + +### The Cargo Book + +[The Cargo Book](cargo/index.html) is a guide to Cargo, Rust's build tool and dependency manager. + +### The Rustdoc Book + +[The Rustdoc Book](rustdoc/index.html) describes our documentation tool, `rustdoc`. + +### Extended Error Listing Many of Rust's errors come with error codes, and you can request extended -diagnostics from the compiler on those errors. We also [have the text of those -extended errors on the web][err], if you prefer to read them that way. - -# The Rust Bookshelf - -Rust provides a number of book-length sets of documentation, collectively -nicknamed 'The Rust Bookshelf.' - -* [The Rust Programming Language][book] teaches you how to program in Rust. -* [Rust By Example][rbe] teaches you how to program in Rust using editable examples. -* [The Cargo Book][cargo-book] is a guide to Cargo, Rust's build tool and dependency manager. -* [The Unstable Book][unstable-book] has documentation for unstable features. -* [The Rustonomicon][nomicon] is your guidebook to the dark arts of unsafe Rust. -* [The Reference][ref] is not a formal spec, but is more detailed and comprehensive than the book. -* [The Rustdoc Book][rustdoc-book] describes our documentation tool, `rustdoc`. - -Initially, documentation lands in the Unstable Book, and then, as part of the -stabilization process, is moved into the Book, Nomicon, or Reference. - -Another few words about the reference: it is guaranteed to be accurate, but not -complete. We have a policy that features must have documentation to be stabilized, -but we did not always have this policy, and so there are some stable things that -are not yet in the reference. We're working on back-filling things that landed -before this policy was put into place. That work is being tracked -[here][refchecklist]. - -[Rust Learning]: https://github.com/ctjhoa/rust-learning -[Docs.rs]: https://docs.rs/ -[api]: std/index.html -[ref]: reference/index.html -[refchecklist]: https://github.com/rust-lang-nursery/reference/issues/9 -[err]: error-index.html -[book]: book/index.html -[rbe]: rust-by-example/index.html -[nomicon]: nomicon/index.html -[unstable-book]: unstable-book/index.html -[rustdoc-book]: rustdoc/index.html -[cargo-book]: cargo/index.html +diagnostics from the compiler on those errors. You can also [read them +here](error-index.html), if you prefer to read them that way. + +## Master Rust + +Once you're quite familiar with the language, you may find these advanced +resources useful. + +### The Reference + +[The Reference](reference/index.html) is not a formal spec, but is more detailed and +comprehensive than the book. + +### The Rustonomicon + +[The Rustonomicon](nomicon/index.html) is your guidebook to the dark arts of unsafe +Rust. It's also sometimes called "the 'nomicon." + +### The Unstable Book +[The Unstable Book](unstable-book/index.html) has documentation for unstable features.