803c3e2ee8
Some history: While getting Rust to 1.0, it was a struggle to keep the book in a working state. I had always wanted a certain kind of TOC, but couldn't quite get it there. At the 11th hour, I wrote up "Rust inside other langauges" and "Dining Philosophers" in an attempt to get the book in the direction I wanted to go. They were fine, but not my best work. I wanted to further expand this section, but it's just never going to end up happening. We're doing the second draft of the book now, and these sections are basically gone already. Here's the issues with these two sections, and removing them just fixes it all: // Philosophers There was always controversy over which ones were chosen, and why. This is kind of a perpetual bikeshed, but it comes up every once in a while. The implementation was originally supposed to show off channels, but never did, due to time constraints. Months later, I still haven't re-written it to use them. People get different results and assume that means they're wrong, rather than the non-determinism inherent in concurrency. Platform differences aggrivate this, as does the exact amount of sleeping and printing. // Rust Inside Other Languages This section is wonderful, and shows off a strength of Rust. However, it's not clear what qualifies a language to be in this section. And I'm not sure how tracking a ton of other languages is gonna work, into the future; we can't test _anything_ in this section, so it's prone to bitrot. By removing this section, and making the Guessing Game an initial tutorial, we will move this version of the book closer to the future version, and just eliminate all of these questions. In addition, this also solves the 'split-brained'-ness of having two paths, which has endlessly confused people in the past. I'm sad to see these sections go, but I think it's for the best. Fixes #30471 Fixes #30163 Fixes #30162 Fixes #25488 Fixes #30345 Fixes #29590 Fixes #28713 Fixes #28915 And probably others. This lengthy list alone is enough to show that these should have been removed. RIP. |
||
|---|---|---|
| .. | ||
| book | ||
| nomicon | ||
| style | ||
| complement-design-faq.md | ||
| complement-lang-faq.md | ||
| complement-project-faq.md | ||
| favicon.inc | ||
| footer.inc | ||
| full-toc.inc | ||
| grammar.md | ||
| guide-crates.md | ||
| guide-error-handling.md | ||
| guide-ffi.md | ||
| guide-macros.md | ||
| guide-ownership.md | ||
| guide-plugins.md | ||
| guide-pointers.md | ||
| guide-strings.md | ||
| guide-tasks.md | ||
| guide-testing.md | ||
| guide-unsafe.md | ||
| guide.md | ||
| index.md | ||
| intro.md | ||
| not_found.md | ||
| README.md | ||
| reference.md | ||
| rust.css | ||
| rust.md | ||
| rustc-ux-guidelines.md | ||
| rustdoc.md | ||
| tutorial.md | ||
| uptack.tex | ||
| version_info.html.template | ||
Rust documentations
Building
To generate all the docs, follow the "Building Documentation" instructions in the README in the root of the repository. This will convert the distributed Markdown docs to HTML and generate HTML doc for the books, 'std' and 'extra' libraries.
To generate HTML documentation from one source file/crate, do something like:
rustdoc --output html-doc/ --output-format html ../src/libstd/path.rs
(This, of course, requires a working build of the rustdoc tool.)
Additional notes
To generate an HTML version of a doc from Markdown manually, you can do something like:
rustdoc reference.md
(reference.md being the Rust Reference Manual.)
An overview of how to use the rustdoc command is available in the docs.
Further details are available from the command line by with rustdoc --help.