Testing Rustdoc and Local Testing

be run on a standalone Markdown file, or it can run `doctest`s on Rust code or standalone Markdown files. For the former, it shortcuts straight to `html/markdown.rs`, optionally including a mode which inserts a Table of Contents to the output `HTML`. For the latter, `rustdoc` runs a similar partial-compilation to get relevant documentation in `test.rs`, but instead of going through the full clean and render process, it runs a much simpler crate walk to grab *just* the hand-written documentation. Combined with the aforementioned "`find_testable_code`" in `html/markdown.rs`, it builds up a collection of tests to run before handing them off to the test runner. One notable location in `test.rs` is the function `make_test`, which is where hand-written `doctest`s get transformed into something that can be executed. Some extra reading about `make_test` can be found [here](https://quietmisdreavus.net/code/2018/02/23/how-the-doctests-get-made/). ## Dotting i's And Crossing t's So that's `rustdoc`'s code in a nutshell, but there's more things in the compiler that deal with it. Since we have the full `compiletest` suite at hand, there's a set of tests in `tests/rustdoc` that make sure the final `HTML` is what we expect in various situations. These tests also use a supplementary script, `src/etc/htmldocck.py`, that allows it to look through the final `HTML` using `XPath` notation to get a precise look at the output. The full description of all the commands available to `rustdoc` tests (e.g. [`@has`] and [`@matches`]) is in [`htmldocck.py`]. To use multiple crates in a `rustdoc` test, add `//@ aux-build:filename.rs` to the top of the test file. `filename.rs` should be placed in an `auxiliary` directory relative to the test file with the comment. If you need to build docs for the auxiliary file, use `//@ build-aux-docs`. In addition, there are separate tests for the search index and `rustdoc`'s ability to query it. The files in `tests/rustdoc-js` each contain a different search query and the expected results, broken out by search tab. These files are processed by a script in `src/tools/rustdoc-js` and the `Node.js` runtime. These tests don't have as thorough of a writeup, but a broad example that features results in all tabs can be found in `basic.js`. The basic idea is that you match a given `QUERY` with a set of `EXPECTED` results, complete with the full item path of each item. [`@has`]: https://github.com/rust-lang/rust/blob/master/src/etc/htmldocck.py#L39 [`@matches`]: https://github.com/rust-lang/rust/blob/master/src/etc/htmldocck.py#L44 [`htmldocck.py`]: https://github.com/rust-lang/rust/blob/master/src/etc/htmldocck.py ## Testing Locally Some features of the generated `HTML` documentation might require local storage to be used across pages, which doesn't work well without an `HTTP` server. To test these features locally, you can run a local `HTTP` server, like this: ```bash $ ./x doc library # The documentation has been generated into `build/[YOUR ARCH]/doc`. $ python3 -m http.server -d build/[YOUR ARCH]/doc ``` Now you can browse your documentation just like you would if it was hosted on the internet. For example, the url for `std` will be `rust/std/`. ## See Also - The [`rustdoc` api docs] - [An overview of `rustdoc`](./rustdoc.md) - [The rustdoc user guide]

The compiler includes tests in `tests/rustdoc` to verify the generated HTML output, using the `htmldocck.py` script for precise HTML analysis via XPath. Auxiliary crates can be used in tests with `//@ aux-build:filename.rs`, and their docs can be built with `//@ build-aux-docs`. Separate tests in `tests/rustdoc-js` check the search index functionality using Node.js and a script in `src/tools/rustdoc-js`. To test features requiring local storage across pages, a local HTTP server can be used to serve the generated documentation. Additional resources include the rustdoc API docs, an overview of rustdoc, and the rustdoc user guide.