src/doc/index.md

   1 % Rust Documentation
   2
   3 <style>
   4 nav {
   5     display: none;
   6 }
   7 h3 {
   8     font-size: 1.35rem;
   9 }
  10 h4 {
  11     font-size: 1.1rem;
  12 }
  13
  14 /* Formatting for docs search bar */
  15 #search-input {
  16     width: calc(100% - 58px);
  17 }
  18 #search-but {
  19     cursor: pointer;
  20 }
  21 #search-but, #search-input {
  22     padding: 4px;
  23     border: 1px solid #ccc;
  24     border-radius: 3px;
  25     outline: none;
  26     font-size: 0.7em;
  27     background-color: #fff;
  28 }
  29 #search-but:hover, #search-input:focus {
  30     border-color: #55a9ff;
  31 }
  32
  33 /* Formatting for external link icon */
  34 svg.external-link {
  35   display: inline-block;
  36   position: relative;
  37   vertical-align: super;
  38   width: 0.7rem;
  39   height: 0.7rem;
  40   padding-left: 2px;
  41   top: 3px;
  42 }
  43 </style>
  44
  45 Welcome to an overview of the documentation provided by the [Rust
  46 project]. This page contains links to various helpful references,
  47 most of which are available offline (if opened with `rustup doc`). Many of these
  48 resources take the form of "books"; we collectively call these "The Rust
  49 Bookshelf." Some are large, some are small.
  50
  51 All of these books are managed by the Rust Organization, but other unofficial
  52 documentation resources are included here as well!
  53
  54 If you're just looking for the standard library reference, here it is:
  55 [Rust API documentation](std/index.html)
  56
  57
  58 ## Learning Rust
  59
  60 If you'd like to learn Rust, this is the section for you! All of these resources
  61 assume that you have programmed before, but not in any specific language:
  62
  63 ### The Rust Programming Language
  64
  65 Affectionately nicknamed "the book," [The Rust Programming Language](book/index.html)
  66 will give you an overview of the language from first principles. You'll build a
  67 few projects along the way, and by the end, you'll have a solid grasp of how to
  68 use the language.
  69
  70 ### Rust By Example
  71
  72 If reading multiple hundreds of pages about a language isn't your style, then
  73 [Rust By Example](rust-by-example/index.html) has you covered. RBE shows off a
  74 bunch of code without using a lot of words. It also includes exercises!
  75
  76 ### Rustlings
  77
  78 [Rustlings](https://github.com/rust-lang/rustlings) guides you
  79 through downloading and setting up the Rust toolchain, then provides an
  80 interactive tool that teaches you how to solve coding challenges in Rust.
  81
  82 ### Rust Playground
  83
  84 The [Rust Playground](https://play.rust-lang.org) is a great place
  85 to try out and share small bits of code, or experiment with some of the most
  86 popular crates.
  87
  88
  89 ## Using Rust
  90
  91 Once you've gotten familiar with the language, these resources can help you put
  92 it to work.
  93
  94 ### The Standard Library
  95
  96 Rust's standard library has [extensive API documentation](std/index.html), with
  97 explanations of how to use various things, as well as example code for
  98 accomplishing various tasks. Code examples have a "Run" button on hover that
  99 opens the sample in the playground.
 100
 101 <div>
 102   <form action="std/index.html" method="get">
 103     <input id="search-input" type="search" name="search"
 104            placeholder="Search through the standard library"/>
 105     <button id="search-but">Search</button>
 106   </form>
 107 </div>
 108
 109 ### Your Personal Documentation
 110
 111 Whenever you are working in a crate, `cargo doc --open` will generate
 112 documentation for your project _and_ all its dependencies in their correct
 113 version, and open it in your browser. Add the flag `--document-private-items` to
 114 also show items not marked `pub`.
 115
 116 ### Rust Version History
 117
 118 [The Release Notes](releases.html) describes the change history of the Rust
 119 toolchain and language.
 120
 121 [The Edition Guide](edition-guide/index.html) describes the Rust editions and
 122 their differences. The latest version of the toolchain supports all
 123 historical editions.
 124
 125 ### The `rustc` Book
 126
 127 [The `rustc` Book](rustc/index.html) describes the Rust compiler, `rustc`.
 128
 129 ### The Cargo Book
 130
 131 [The Cargo Book](cargo/index.html) is a guide to Cargo, Rust's build tool and
 132 dependency manager.
 133
 134 ### The Rustdoc Book
 135
 136 [The Rustdoc Book](rustdoc/index.html) describes our documentation tool, `rustdoc`.
 137
 138 ### The Clippy Book
 139
 140 [The Clippy Book](clippy/index.html) describes our static analyzer, Clippy.
 141
 142 ### Extended Error Listing
 143
 144 Many of Rust's errors come with error codes, and you can request extended
 145 diagnostics from the compiler on those errors (with `rustc --explain`). You can
 146 also read them here if you prefer: [rustc error codes](error_codes/index.html)
 147
 148
 149 ## Mastering Rust
 150
 151 Once you're quite familiar with the language, you may find these advanced
 152 resources useful.
 153
 154 ### The Reference
 155
 156 [The Reference](reference/index.html) is not a formal spec, but is more detailed
 157 and comprehensive than the book.
 158
 159 ### The Style Guide
 160
 161 [The Rust Style Guide](style-guide/index.html) describes the standard formatting
 162 of Rust code. Most developers use `cargo fmt` to invoke `rustfmt` and format the
 163 code automatically (the result matches this style guide).
 164
 165 ### The Rustonomicon
 166
 167 [The Rustonomicon](nomicon/index.html) is your guidebook to the dark arts of
 168 unsafe Rust. It's also sometimes called "the 'nomicon."
 169
 170 ### The Unstable Book
 171
 172 [The Unstable Book](unstable-book/index.html) has documentation for unstable
 173 features.
 174
 175 ### The `rustc` Contribution Guide
 176
 177 [The `rustc` Guide](https://rustc-dev-guide.rust-lang.org/)
 178 documents how the compiler works and how to contribute to it. This is useful if
 179 you want to build or modify the Rust compiler from source (e.g. to target
 180 something non-standard).
 181
 182
 183 ## Specialized Rust
 184
 185 When using Rust in specific domains, consider using the following resources
 186 tailored to each area.
 187
 188 ### Embedded Systems
 189
 190 When developing for Bare Metal or Embedded Linux systems, you may find these
 191 resources maintained by the [Embedded Working Group] useful.
 192
 193 [Embedded Working Group]: https://github.com/rust-embedded
 194
 195 #### The Embedded Rust Book
 196
 197 [The Embedded Rust Book] is targeted at developers familiar with embedded
 198 development and familiar with Rust, but have not used Rust for embedded
 199 development.
 200
 201 [The Embedded Rust Book]: embedded-book/index.html
 202 [Rust project]: https://www.rust-lang.org
 203
 204 <script>
 205 // check if a given link is external
 206 function isExternalLink(url) {
 207   const tmp = document.createElement('a');
 208   tmp.href = url;
 209   return tmp.host !== window.location.host;
 210 }
 211
 212 // Add the `external` class to all <a> tags with external links and append the external link SVG
 213 function updateExternalAnchors() {
 214   /*
 215     External link SVG from Font-Awesome
 216     CC BY-SA 3.0 https://creativecommons.org/licenses/by-sa/3.0
 217     via Wikimedia Commons
 218   */
 219   const svgText = `<svg
 220      class='external-link'
 221      xmlns='http://www.w3.org/2000/svg'
 222      viewBox='0 -256 1850 1850'
 223      width='100%'
 224      height='100%'>
 225        <g transform='matrix(1,0,0,-1,30,1427)'>
 226          <path d='M 1408,608 V 288 Q 1408,169 1323.5,84.5 1239,0 1120,
 227            0 H 288 Q 169,0 84.5,84.5 0,169 0,288 v 832 Q 0,1239 84.5,1323.5 169,
 228            1408 288,1408 h 704 q 14,0 23,-9 9,-9 9,-23 v -64 q 0,-14 -9,-23 -9,
 229            -9 -23,-9 H 288 q -66,0 -113,-47 -47,-47 -47,-113 V 288 q 0,-66 47,
 230            -113 47,-47 113,-47 h 832 q 66,0 113,47 47,47 47,113 v 320 q 0,14 9,
 231            23 9,9 23,9 h 64 q 14,0 23,-9 9,-9 9,-23 z m 384,864 V 960 q 0,
 232            -26 -19,-45 -19,-19 -45,-19 -26,0 -45,19 L 1507,1091 855,439 q -10,
 233            -10 -23,-10 -13,0 -23,10 L 695,553 q -10,10 -10,23 0,13 10,23 l 652,
 234            652 -176,176 q -19,19 -19,45 0,26 19,45 19,19 45,19 h 512 q 26,0 45,
 235            -19 19,-19 19,-45 z' style='fill:currentColor' />
 236          </g>
 237      </svg>`;
 238   let allAnchors = document.getElementsByTagName("a");
 239
 240   for (var i = 0; i < allAnchors.length; ++i) {
 241     let anchor = allAnchors[i];
 242     if (isExternalLink(anchor.href)) {
 243       anchor.classList.add("external");
 244       anchor.innerHTML += svgText;
 245     }
 246   }
 247 }
 248
 249 // on page load, update external anchors
 250 document.addEventListener("DOMContentLoaded", updateExternalAnchors);
 251
 252 </script>