diff --git a/src/doc/index.md b/src/doc/index.md index bf08960f338..7c97c16c20b 100644 --- a/src/doc/index.md +++ b/src/doc/index.md @@ -4,6 +4,20 @@ nav { display: none; } +body { + font-family: serif; +} +h1, h2, h3, h4, h5, h6 { + font-family: sans-serif; +} +h3 { + font-size: 1.35rem; +} +h4 { + font-size: 1.1rem; +} + +/* Formatting for docs search bar */ #search-input { width: calc(100% - 58px); } @@ -21,53 +35,74 @@ nav { #search-but:hover, #search-input:focus { border-color: #55a9ff; } -h2 { - font-size: 18px; + +/* Formatting for external link icon */ +svg.external-link { + display: inline-block; + position: relative; + vertical-align: super; + width: 0.7rem; + height: 0.7rem; + padding-left: 2px; + top: 3px; } -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! +Welcome to an overview of the documentation provided by the [Rust +project]. This page contains links to various helpful references, +most of which are available offline (if opened with `rustup doc`). Many of these +resources take the form of "books"; we collectively call these "The Rust +Bookshelf." Some are large, some are small. -Many of these resources take the form of "books"; we collectively call these -"The Rust Bookshelf." Some are large, some are small. +All of these books are managed by the Rust Organization, but other unofficial +documentation resources are included here as well! -# Learn Rust +If you're just looking for the standard library reference, here it is: +[Rust API documentation](std/index.html) -If you'd like to learn Rust, this is the spot for you! All of these resources + +## Learning Rust + +If you'd like to learn Rust, this is the section for you! All of these resources assume that you have programmed before, but not in any specific language: -## The Rust Programming 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. +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 how to +use the language. -## Rust By Example +### 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! +[Rust By Example](rust-by-example/index.html) has you covered. RBE shows off a +bunch of code without using a lot of words. It also includes exercises! -## Rustlings +### Rustlings -[Rustlings](https://github.com/rust-lang/rustlings) guides you through downloading and setting up the Rust toolchain, -and teaches you the basics of reading and writing Rust syntax. It's an -alternative to Rust by Example that works with your own environment. +[Rustlings](https://github.com/rust-lang/rustlings) guides you +through downloading and setting up the Rust toolchain, then provides an +interactive tool that teaches you how to solve coding challenges in Rust. -# Use Rust +### Rust Playground -Once you've gotten familiar with the language, these resources can help you -when you're actually using it day-to-day. +The [Rust Playground](https://play.rust-lang.org) is a great place +to try out and share small bits of code, or experiment with some of the most +popular crates. -## 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. +## Using Rust + +Once you've gotten familiar with the language, these resources can help you put +it to work. + +### 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. Code examples have a "Run" button on hover that +opens the sample in the playground.
@@ -77,76 +112,143 @@ accomplishing various tasks.
-## The Edition Guide +### Your Personal Documentation -[The Edition Guide](edition-guide/index.html) describes the Rust editions. +Whenever you are working in a crate, `cargo doc --open` will generate +documentation for your project _and_ all its dependencies in their correct +version, and open it in your browser. Add the flag `--document-private-items` to +also show items not marked `pub`. -## The Rustc Book +### The Edition Guide -[The Rustc Book](rustc/index.html) describes the Rust compiler, `rustc`. +[The Edition Guide](edition-guide/index.html) describes the Rust editions and +their differences. -## The Cargo Book +### The `rustc` Book -[The Cargo Book](cargo/index.html) is a guide to Cargo, Rust's build tool and dependency manager. +[The `rustc` Book](rustc/index.html) describes the Rust compiler, `rustc`. -## The Rustdoc Book +### 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`. -## The Clippy Book +### The Clippy Book [The Clippy Book](clippy/index.html) describes our static analyzer, Clippy. -## Extended Error Listing +### Extended Error Listing Many of Rust's errors come with error codes, and you can request extended -diagnostics from the compiler on those errors. You can also [read them -here](error_codes/index.html), if you prefer to read them that way. +diagnostics from the compiler on those errors (with `rustc --explain`). You can +also read them here if you prefer: [rustc error codes](error_codes/index.html) -# Master Rust + +## Mastering Rust Once you're quite familiar with the language, you may find these advanced resources useful. -## The Reference +### The Reference -[The Reference](reference/index.html) is not a formal spec, but is more detailed and -comprehensive than the book. +[The Reference](reference/index.html) is not a formal spec, but is more detailed +and comprehensive than the book. -## The Style Guide +### The Style Guide -[The Rust Style Guide](style-guide/index.html) describes the standard formatting of Rust -code. Most developers use rustfmt to format their code, and rustfmt's default -formatting matches this style guide. +[The Rust Style Guide](style-guide/index.html) describes the standard formatting +of Rust code. Most developers use `cargo fmt` to invoke `rustfmt` and format the +code automatically (the result matches this style guide). -## The Rustonomicon +### 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 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 -[The Unstable Book](unstable-book/index.html) has documentation for unstable features. +[The Unstable Book](unstable-book/index.html) has documentation for unstable +features. -## The `rustc` Contribution Guide +### The `rustc` Contribution Guide -[The `rustc` Guide](https://rustc-dev-guide.rust-lang.org/) documents how -the compiler works and how to contribute to it. This is useful if you want to build -or modify the Rust compiler from source (e.g. to target something non-standard). +[The `rustc` Guide](https://rustc-dev-guide.rust-lang.org/) +documents how the compiler works and how to contribute to it. This is useful if +you want to build or modify the Rust compiler from source (e.g. to target +something non-standard). -# Specialize Rust -When using Rust in specific domain areas, consider using the following resources tailored to each domain. +## Specialized Rust -## Embedded Systems +When using Rust in specific domains, consider using the following resources +tailored to each area. -When developing for Bare Metal or Embedded Linux systems, you may find these resources maintained by the [Embedded Working Group] useful. +### Embedded Systems + +When developing for Bare Metal or Embedded Linux systems, you may find these +resources maintained by the [Embedded Working Group] useful. [Embedded Working Group]: https://github.com/rust-embedded -### The Embedded Rust Book +#### The Embedded Rust Book -[The Embedded Rust Book] is targeted at developers familiar with embedded development and familiar with Rust, but have not used Rust for embedded development. +[The Embedded Rust Book] is targeted at developers familiar with embedded +development and familiar with Rust, but have not used Rust for embedded +development. [The Embedded Rust Book]: embedded-book/index.html [Rust project]: https://www.rust-lang.org + +