auto merge of #16827 : steveklabnik/rust/fix_doc_index, r=brson

Fixes #14972

Author: bors

src/doc/index.md

@@ -1,18 +1,55 @@
 % Rust Documentation
 
-<!-- Completely hide the TOC and the section numbers -->
-<style type="text/css">
-#TOC { display: none; }
-.header-section-number { display: none; }
-li {list-style-type: none; }
-</style>
+Welcome to the Rust documentation! You can use the section headings above
+to jump to any particular section.
+
+# Getting Started
+
+If you haven't seen Rust at all yet, the first thing you should read is the [30
+minute intro](intro.html). It will give you an overview of the basic ideas of Rust
+at a high level.
+
+Once you know you really want to learn Rust, the next step is reading [the
+guide](guide.html). It is a lengthy explanation of Rust, its syntax, and its
+concepts. Upon completing the guide, you'll be an intermediate Rust developer,
+and will have a good grasp of the fundamental ideas behind Rust.
+
+# Community & Getting Help
+
+If you need help with something, or just want to talk about Rust with others,
+there's a few places you can do that:
+
+The Rust IRC channels on [irc.mozilla.org](http://irc.mozilla.org/) are the
+fastest way to get help.
+[`#rust`](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust) is
+the general discussion channel, and you'll find people willing to help you with
+any questions you may have.
+
+There are also three specialty channels:
+[`#rust-gamedev`](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-gamedev)
+and
+[`#rust-osdev`](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-osdev)
+are for game development and operating system development, respectively.
+There's also
+[`#rust-internals`](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals), which is for discussion of the development of Rust itself.
+
+You can also get help on [Stack
+Overflow](http://stackoverflow.com/questions/tagged/rust). Searching for your
+problem might reveal someone who has asked it before!
+
+There is an active [subreddit](http://reddit.com/r/rust) with lots of
+discussion about Rust.
+
+There is also a [developer forum](http://discuss.rust-lang.org/), where the
+development of Rust itself is discussed.
 
-* [A 30-minute Intro to Rust](intro.html)
-* [The Rust tutorial](tutorial.html)  (* [PDF](tutorial.pdf))
-* [The Rust reference manual](rust.html) (* [PDF](rust.pdf))
 
 # Guides
 
+Rust Guides are in-depth looks at a particular topic that's relevant to Rust
+development. If you're trying to figure out how to do something, there may be
+a guide that can help you out:
+
 * [Strings](guide-strings.html)
 * [Pointers](guide-pointers.html)
 * [References and Lifetimes](guide-lifetimes.html)
@@ -24,70 +61,43 @@ li {list-style-type: none; }
 * [Testing](guide-testing.html)
 * [Rust's Runtime](guide-runtime.html)
 
+# Tools
+
+Rust's still a young language, so there isn't a ton of tooling yet, but the
+tools we have are really nice.
+
+[Cargo](http://crates.io) is Rust's package manager, and its website contains
+lots of good documentation.
+
+[The `rustdoc` manual](rustdoc.html) contains information about Rust's
+documentation tool.
+
 # FAQs
 
+There are questions that are asked quite often, and so we've made FAQs for them:
+
 * [Language Design FAQ](complement-design-faq.html)
 * [Language FAQ](complement-lang-faq.html)
 * [Project FAQ](complement-project-faq.html)
 * [How to submit a bug report](complement-bugreport.html)
 
-# Libraries
-
-* [The standard library, `std`](std/index.html)
-
-<!-- force the two lists to be separate -->
-
-* [The `arena` allocation library](arena/index.html)
-* [The `collections` library](collections/index.html)
-* [The `flate` compression library](flate/index.html)
-* [The `fourcc` four-character code library](fourcc/index.html)
-* [The `getopts` argument parsing library](getopts/index.html)
-* [The `glob` file path matching library](glob/index.html)
-* [The `green` M:N runtime library](green/index.html)
-* [The `hexfloat` library for hexadecimal floating-point literals](hexfloat/index.html)
-* [The `libc` bindings](libc/index.html)
-* [The `native` 1:1 threading runtime](native/index.html)
-* [The `num` arbitrary precision numerics library](num/index.html)
-* [The `rand` library for random numbers and distributions](rand/index.html)
-* [The `regex` library for regular expressions](regex/index.html)
-* [The `rustc` compiler](rustc/index.html)
-* [The `rustuv` M:N I/O library](rustuv/index.html)
-* [The `semver` version collation library](semver/index.html)
-* [The `serialize` value encoding/decoding library](serialize/index.html)
-* [The `sync` library for concurrency-enabled mechanisms and primitives](sync/index.html)
-* [The `syntax` library, the Rust parser](syntax/index.html)
-* [The `term` terminal-handling library](term/index.html)
-* [The `test` library containing the unit-testing & micro-benchmark framework](test/index.html)
-* [The `time` library](time/index.html)
-* [The `uuid` 128-bit universally unique identifier library](uuid/index.html)
-* [The `url` library](url/index.html)
-* [The `log` library](log/index.html)
-
-# Tooling
-
-* [The `rustdoc` manual](rustdoc.html)
+# The standard library
+
+You can find function-level documentation for the entire standard library
+[here](std/index.html). There's a list of crates on the left with more specific
+sections, or you can use the search bar at the top to search for something if
+you know its name.
 
 # External documentation
 
-*Note: While these are great resources for learning Rust, they may
-track a particular version of Rust that is likely not exactly the same
-as that for which this documentation was generated.*
+*Note: While these are great resources for learning Rust, they may track a
+particular version of Rust that is likely not exactly the same as that for
+which this documentation was generated.*
 
-* [Rust for Rubyists] - An excellent introduction for Rust; not just for Rubyists (tracks the most recent release).
-* [Rust by Example] - Short examples of common tasks in Rust (tracks the master branch).
-* [The Rust wiki](http://github.com/rust-lang/rust/wiki)
+* [Rust by Example] - Short examples of common tasks in Rust (tracks the master
+  branch).
+* [Rust for Rubyists] - The first community tutorial for Rust. Tracks the last
+  stable release. Not just for Ruby programmers.
 
-[Rust for Rubyists]: http://www.rustforrubyists.com/
 [Rust by Example]: http://rustbyexample.com/
-
-# Community
-
-* [Reddit](http://reddit.com/r/rust)
-* [Stack Overflow](http://stackoverflow.com/questions/tagged/rust)
-* [Developer Forum](http://discuss.rust-lang.org/)
-* The Rust IRC channels on [irc.mozilla.org](http://irc.mozilla.org/):
-    * [`#rust`](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust) - general discussion
-    * [`#rust-gamedev`](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-gamedev) - game development
-    * [`#rust-internals`](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals) - compiler and libraries
-    * [`#rust-osdev`](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-osdev) - operating system development
-
+[Rust for Rubyists]: http://www.rustforrubyists.com/