doc: cleanup of doc/index.md
- Add quick link to API docs - Add marker for external links, to help offline users - Add information about using 'cargo doc' and the playground - Clean up some of the wording - Update body & header style to match rustdoc defaults
This commit is contained in:
Trevor Gross
parent
07c993eba8
commit
4ecf14372f
228
src/doc/index.md
228
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;
|
||||
}
|
||||
</style>
|
||||
|
||||
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.
|
||||
|
||||
<div>
|
||||
<form action="std/index.html" method="get">
|
||||
@ -77,76 +112,143 @@ accomplishing various tasks.
|
||||
</form>
|
||||
</div>
|
||||
|
||||
## 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
|
||||
|
||||
<script>
|
||||
// check if a given link is external
|
||||
function isExternalLink(url) {
|
||||
const tmp = document.createElement('a');
|
||||
tmp.href = url;
|
||||
return tmp.host !== window.location.host;
|
||||
}
|
||||
|
||||
// Add the `external` class to all <a> tags with external links and append the external link SVG
|
||||
function updateExternalAnchors() {
|
||||
/*
|
||||
External link SVG from Font-Awesome
|
||||
CC BY-SA 3.0 https://creativecommons.org/licenses/by-sa/3.0
|
||||
via Wikimedia Commons
|
||||
*/
|
||||
const svgText = `<svg
|
||||
class='external-link'
|
||||
xmlns='http://www.w3.org/2000/svg'
|
||||
viewBox='0 -256 1850 1850'
|
||||
width='100%'
|
||||
height='100%'>
|
||||
<g transform='matrix(1,0,0,-1,30,1427)'>
|
||||
<path d='M 1408,608 V 288 Q 1408,169 1323.5,84.5 1239,0 1120,
|
||||
0 H 288 Q 169,0 84.5,84.5 0,169 0,288 v 832 Q 0,1239 84.5,1323.5 169,
|
||||
1408 288,1408 h 704 q 14,0 23,-9 9,-9 9,-23 v -64 q 0,-14 -9,-23 -9,
|
||||
-9 -23,-9 H 288 q -66,0 -113,-47 -47,-47 -47,-113 V 288 q 0,-66 47,
|
||||
-113 47,-47 113,-47 h 832 q 66,0 113,47 47,47 47,113 v 320 q 0,14 9,
|
||||
23 9,9 23,9 h 64 q 14,0 23,-9 9,-9 9,-23 z m 384,864 V 960 q 0,
|
||||
-26 -19,-45 -19,-19 -45,-19 -26,0 -45,19 L 1507,1091 855,439 q -10,
|
||||
-10 -23,-10 -13,0 -23,10 L 695,553 q -10,10 -10,23 0,13 10,23 l 652,
|
||||
652 -176,176 q -19,19 -19,45 0,26 19,45 19,19 45,19 h 512 q 26,0 45,
|
||||
-19 19,-19 19,-45 z' style='fill:currentColor' />
|
||||
</g>
|
||||
</svg>`;
|
||||
let allAnchors = document.getElementsByTagName("a");
|
||||
|
||||
for (var i = 0; i < allAnchors.length; ++i) {
|
||||
let anchor = allAnchors[i];
|
||||
if (isExternalLink(anchor.href)) {
|
||||
anchor.classList.add("external");
|
||||
anchor.innerHTML += svgText;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// on page load, update external anchors
|
||||
document.addEventListener("DOMContentLoaded", updateExternalAnchors);
|
||||
|
||||
</script>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user