aeb85a9533
Add a link validator to rustbuild This commit was originally targeted at just adding a link checking script to the rustbuild system. This ended up snowballing a bit to extend rustbuild to be amenable to various tools we have as part of the build system in general. There's a new `src/tools` directory which has a number of scripts/programs that are purely intended to be used as part of the build system and CI of this repository. This is currently inhabited by rustbook, the error index generator, and a new linkchecker script added as part of this PR. I suspect that more tools like compiletest, tidy scripts, snapshot scripts, etc will migrate their way into this directory over time. The commit which adds the error index generator shows the steps necessary to add new tools to the build system, namely: 1. New steps are defined for building the tool and running the tool 2. The dependencies are configured 3. The steps are implemented In terms of the link checker, these commits do a few things: * A new `src/tools/linkchecker` script is added. This will read an entire documentation tree looking for broken relative links (HTTP links aren't followed yet). * A large number of broken links throughout the documentation were fixed. Many of these were just broken when viewed from core as opposed to std, but were easily fixed. * A few rustdoc bugs here and there were fixed
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.