From acd84c2f82e303fbc135e69f0d4e2c68d7218f1d Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Mon, 6 Feb 2017 15:05:37 -0500 Subject: [PATCH] Re-write the doc index page Clarify and reorganize. Add the section for the bookshelf. More to come here in the near future! Part of #39588 --- src/doc/index.md | 52 +++++++++++++++++++++++++++++------------------- 1 file changed, 32 insertions(+), 20 deletions(-) diff --git a/src/doc/index.md b/src/doc/index.md index 71dfcf0b067..0533f8d7518 100644 --- a/src/doc/index.md +++ b/src/doc/index.md @@ -6,32 +6,44 @@ nav { } -This is an index of the documentation included with the Rust -compiler. For more comprehensive documentation see [the -website](https://www.rust-lang.org). +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. -[**The Rust Programming Language**][book]. Also known as "The Book", -The Rust Programming Language is the most comprehensive resource for -all topics related to Rust, and is the primary official document of -the language. +## API Documentation -[**The Rust Reference**][ref]. While Rust does not have a -specification, the reference tries to describe its working in -detail. It is accurate, but not necessarily complete. +Rust provides a standard library with a number of features; you can browse +its documentation [here][api]. -[**Standard Library API Reference**][api]. Documentation for the -standard library. +## Reference Documentation -[**The Rustonomicon**][nomicon]. An entire book dedicated to -explaining how to write unsafe Rust code. It is for advanced Rust -programmers. +Rust does not yet have a formal specification, but we have a reference document +[ref][ref]. It is guaranteed to be accurate, but not complete. We now have a +policy that all new features must be included in the reference before +stabilization; however, we are still back-filling things that landed before +then. That work is being tracked [here][38643]. -[**Compiler Error Index**][err]. Extended explanations of -the errors produced by the Rust compiler. +## Extended Error Documentation -[book]: book/index.html -[ref]: reference.html +All of Rust's errors code with error codes, and you can request extended +diagnostics from the compiler on those errors. We also produce those +diagnostics on the web [here][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. +* [The Rustinomicon][nomicon] is your guidebook to the dark arts of unsafe Rust. + +[Rust Learning]: https://github.com/ctjhoa/rust-learning +[Docs.rs]: https://docs.rs/ [api]: std/index.html -[nomicon]: nomicon/index.html +[ref]: reference.html +[38643]: https://github.com/rust-lang/rust/issues/38643 [err]: error-index.html +[book]: book/index.html +[nomicon]: nomicon/index.html