diff --git a/src/doc/rustc-dev-guide/rust-version b/src/doc/rustc-dev-guide/rust-version index 8b48bd518bd6f..c8721bb36001f 100644 --- a/src/doc/rustc-dev-guide/rust-version +++ b/src/doc/rustc-dev-guide/rust-version @@ -1 +1 @@ -c68032fd4c442d275f4daa571ba19c076106b490 +c31cccb7b5cc098b1a8c1794ed38d7fdbec0ccb0 diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md index a7b76233d1978..cba8eac617d6e 100644 --- a/src/doc/rustc-dev-guide/src/SUMMARY.md +++ b/src/doc/rustc-dev-guide/src/SUMMARY.md @@ -63,10 +63,8 @@ - [Notification groups](notification-groups/about.md) - [Apple](notification-groups/apple.md) - [ARM](notification-groups/arm.md) - - [Cleanup Crew](notification-groups/cleanup-crew.md) - [Emscripten](notification-groups/emscripten.md) - [Fuchsia](notification-groups/fuchsia.md) - - [LLVM](notification-groups/llvm.md) - [RISC-V](notification-groups/risc-v.md) - [Rust for Linux](notification-groups/rust-for-linux.md) - [WASI](notification-groups/wasi.md) @@ -101,6 +99,8 @@ - [Rustdoc internals](./rustdoc-internals.md) - [Search](./rustdoc-internals/search.md) - [The `rustdoc` test suite](./rustdoc-internals/rustdoc-test-suite.md) + - [The `rustdoc-gui` test suite](./rustdoc-internals/rustdoc-gui-test-suite.md) + - [The `rustdoc-json` test suite](./rustdoc-internals/rustdoc-json-test-suite.md) - [Autodiff internals](./autodiff/internals.md) - [Installation](./autodiff/installation.md) - [How to debug](./autodiff/debugging.md) diff --git a/src/doc/rustc-dev-guide/src/building/bootstrapping/debugging-bootstrap.md b/src/doc/rustc-dev-guide/src/building/bootstrapping/debugging-bootstrap.md index 35d33ebdb0e7f..ed26785040147 100644 --- a/src/doc/rustc-dev-guide/src/building/bootstrapping/debugging-bootstrap.md +++ b/src/doc/rustc-dev-guide/src/building/bootstrapping/debugging-bootstrap.md @@ -55,7 +55,7 @@ Bootstrap will conditionally build `tracing` support and enable `tracing` output Example basic usage[^just-trace]: -[^just-trace]: It is not recommend to use *just* `BOOTSTRAP_TRACING=TRACE` because that will dump *everything* at `TRACE` level, including logs intentionally gated behind custom targets as they are too verbose even for `TRACE` level by default. +[^just-trace]: It is not recommended to use *just* `BOOTSTRAP_TRACING=TRACE` because that will dump *everything* at `TRACE` level, including logs intentionally gated behind custom targets as they are too verbose even for `TRACE` level by default. ```bash $ BOOTSTRAP_TRACING=bootstrap=TRACE ./x build library --stage 1 diff --git a/src/doc/rustc-dev-guide/src/getting-started.md b/src/doc/rustc-dev-guide/src/getting-started.md index 435202ca6c8e2..d6c5c3ac8521b 100644 --- a/src/doc/rustc-dev-guide/src/getting-started.md +++ b/src/doc/rustc-dev-guide/src/getting-started.md @@ -158,9 +158,6 @@ feel comfortable jumping straight into the large `rust-lang/rust` codebase. The following tasks are doable without much background knowledge but are incredibly helpful: -- [Cleanup crew][iceb]: find minimal reproductions of ICEs, bisect - regressions, etc. This is a way of helping that saves a ton of time for - others to fix an error later. - [Writing documentation][wd]: if you are feeling a bit more intrepid, you could try to read a part of the code and write doc comments for it. This will help you to learn some part of the compiler while also producing a useful artifact! @@ -179,7 +176,6 @@ incredibly helpful: [users]: https://users.rust-lang.org/ [so]: http://stackoverflow.com/questions/tagged/rust [community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library -[iceb]: ./notification-groups/cleanup-crew.md [wd]: ./contributing.md#writing-documentation [wg]: https://rust-lang.github.io/compiler-team/working-groups/ [triage]: ./contributing.md#issue-triage diff --git a/src/doc/rustc-dev-guide/src/notification-groups/about.md b/src/doc/rustc-dev-guide/src/notification-groups/about.md index af305f0103ae8..d75891ecf7b29 100644 --- a/src/doc/rustc-dev-guide/src/notification-groups/about.md +++ b/src/doc/rustc-dev-guide/src/notification-groups/about.md @@ -21,9 +21,7 @@ search for existing issues that haven't been claimed yet. Here's the list of the notification groups: - [Apple](./apple.md) - [ARM](./arm.md) -- [Cleanup Crew](./cleanup-crew.md) - [Emscripten](./emscripten.md) -- [LLVM Icebreakers](./llvm.md) - [RISC-V](./risc-v.md) - [WASI](./wasi.md) - [WebAssembly](./wasm.md) @@ -64,9 +62,7 @@ Example PRs: * [Example of adding yourself to the Apple group.](https://github.com/rust-lang/team/pull/1434) * [Example of adding yourself to the ARM group.](https://github.com/rust-lang/team/pull/358) -* [Example of adding yourself to the Cleanup Crew.](https://github.com/rust-lang/team/pull/221) * [Example of adding yourself to the Emscripten group.](https://github.com/rust-lang/team/pull/1579) -* [Example of adding yourself to the LLVM group.](https://github.com/rust-lang/team/pull/140) * [Example of adding yourself to the RISC-V group.](https://github.com/rust-lang/team/pull/394) * [Example of adding yourself to the WASI group.](https://github.com/rust-lang/team/pull/1580) * [Example of adding yourself to the WebAssembly group.](https://github.com/rust-lang/team/pull/1581) @@ -81,9 +77,7 @@ group. For example: ```text @rustbot ping apple @rustbot ping arm -@rustbot ping cleanup-crew @rustbot ping emscripten -@rustbot ping icebreakers-llvm @rustbot ping risc-v @rustbot ping wasi @rustbot ping wasm @@ -92,12 +86,12 @@ group. For example: To make some commands shorter and easier to remember, there are aliases, defined in the [`triagebot.toml`] file. For example, all of these commands -are equivalent and will ping the Cleanup Crew: +are equivalent and will ping the Apple group: ```text -@rustbot ping cleanup -@rustbot ping bisect -@rustbot ping reduce +@rustbot ping apple +@rustbot ping macos +@rustbot ping ios ``` Keep in mind that these aliases are meant to make humans' life easier. diff --git a/src/doc/rustc-dev-guide/src/notification-groups/cleanup-crew.md b/src/doc/rustc-dev-guide/src/notification-groups/cleanup-crew.md deleted file mode 100644 index 9cf4e512cbdf8..0000000000000 --- a/src/doc/rustc-dev-guide/src/notification-groups/cleanup-crew.md +++ /dev/null @@ -1,90 +0,0 @@ -# Cleanup Crew - -**Github Label:** [ICEBreaker-Cleanup-Crew]
-**Ping command:** `@rustbot ping cleanup-crew` - -[ICEBreaker-Cleanup-Crew]: https://github.com/rust-lang/rust/labels/ICEBreaker-Cleanup-Crew - -The "Cleanup Crew" are focused on improving bug reports. Specifically, -the goal is to try to ensure that every bug report has all the -information that will be needed for someone to fix it: - -* a minimal, standalone example that shows the problem -* links to duplicates or related bugs -* if the bug is a regression (something that used to work, but no longer does), - then a bisection to the PR or nightly that caused the regression - -This kind of cleanup is invaluable in getting bugs fixed. Better -still, it can be done by anybody who knows Rust, without any -particularly deep knowledge of the compiler. - -Let's look a bit at the workflow for doing "cleanup crew" actions. - -## Finding a minimal, standalone example - -Here the ultimate goal is to produce an example that reproduces the same -problem but without relying on any external crates. Such a test ought to contain -as little code as possible, as well. This will make it much easier to isolate the problem. - -However, even if the "ultimate minimal test" cannot be achieved, it's -still useful to post incremental minimizations. For example, if you -can eliminate some of the external dependencies, that is helpful, and -so forth. - -It's particularly useful to reduce to an example that works -in the [Rust playground](https://play.rust-lang.org/), rather than -requiring people to checkout a cargo build. - -There are many resources for how to produce minimized test cases. Here -are a few: - -* The [rust-reduce](https://github.com/jethrogb/rust-reduce) tool can try to reduce - code automatically. - * The [C-reduce](https://github.com/csmith-project/creduce) tool also works - on Rust code, though it requires that you start from a single - file. (A post explaining how to do it can be found [here](https://insaneinside.net/2017/09/12/whole-crate-bug-reduction-with-creduce.html).) -* pnkfelix's [Rust Bug Minimization Patterns] blog post - * This post focuses on "heavy bore" techniques, where you are - starting with a large, complex cargo project that you wish to - narrow down to something standalone. - -[Rust Bug Minimization Patterns]: http://blog.pnkfx.org/blog/2019/11/18/rust-bug-minimization-patterns/ - -## Links to duplicate or related bugs - -If you are on the "Cleanup Crew", you will sometimes see multiple bug -reports that seem very similar. You can link one to the other just by -mentioning the other bug number in a Github comment. Sometimes it is -useful to close duplicate bugs. But if you do so, you should always -copy any test case from the bug you are closing to the other bug that -remains open, as sometimes duplicate-looking bugs will expose -different facets of the same problem. - -## Bisecting regressions - -For regressions (something that used to work, but no longer does), it -is super useful if we can figure out precisely when the code stopped -working. The gold standard is to be able to identify the precise -**PR** that broke the code, so we can ping the author, but even -narrowing it down to a nightly build is helpful, especially as that -then gives us a range of PRs. (One other challenge is that we -sometimes land "rollup" PRs, which combine multiple PRs into one.) - -### cargo-bisect-rustc - -To help in figuring out the cause of a regression we have a tool -called [cargo-bisect-rustc]. It will automatically download and test -various builds of rustc. For recent regressions, it is even able to -use the builds from our CI to track down the regression to a specific -PR; for older regressions, it will simply identify a nightly. - -To learn to use [cargo-bisect-rustc], check out [this blog post][learn], which -gives a quick introduction to how it works. Additionally, there is a [Guide] -which goes into more detail on how to use it. You can also ask questions at -the Zulip stream [`#t-compiler/cargo-bisect-rustc`][zcbr], or help in -improving the tool. - -[cargo-bisect-rustc]: https://github.com/rust-lang/cargo-bisect-rustc/ -[learn]: https://blog.rust-lang.org/inside-rust/2019/12/18/bisecting-rust-compiler.html -[zcbr]: https://rust-lang.zulipchat.com/#narrow/stream/217417-t-compiler.2Fcargo-bisect-rustc -[Guide]: https://rust-lang.github.io/cargo-bisect-rustc/ diff --git a/src/doc/rustc-dev-guide/src/notification-groups/llvm.md b/src/doc/rustc-dev-guide/src/notification-groups/llvm.md deleted file mode 100644 index 9d0087285438d..0000000000000 --- a/src/doc/rustc-dev-guide/src/notification-groups/llvm.md +++ /dev/null @@ -1,38 +0,0 @@ -# LLVM Icebreakers Notification group - -**Github Label:** [A-LLVM]
-**Ping command:** `@rustbot ping icebreakers-llvm` - -[A-LLVM]: https://github.com/rust-lang/rust/labels/A-LLVM - -*Note*: this notification group is *not* the same as the LLVM working group -(WG-llvm). - -The "LLVM Icebreakers Notification Group" are focused on bugs that center around -LLVM. These bugs often arise because of LLVM optimizations gone awry, or as the -result of an LLVM upgrade. The goal here is: - -- to determine whether the bug is a result of us generating invalid LLVM IR, - or LLVM misoptimizing; -- if the former, to fix our IR; -- if the latter, to try and file a bug on LLVM (or identify an existing bug). - -The group may also be asked to weigh in on other sorts of LLVM-focused -questions. - -## Helpful tips and options - -The ["Debugging LLVM"][d] section of the -rustc-dev-guide gives a step-by-step process for how to help debug bugs -caused by LLVM. In particular, it discusses how to emit LLVM IR, run -the LLVM IR optimization pipelines, and so forth. You may also find -it useful to look at the various codegen options listed under `-C help` -and the internal options under `-Z help` -- there are a number that -pertain to LLVM (just search for LLVM). - -[d]: ../backend/debugging.md - -## If you do narrow to an LLVM bug - -The ["Debugging LLVM"][d] section also describes what to do once -you've identified the bug. diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals.md b/src/doc/rustc-dev-guide/src/rustdoc-internals.md index bc91c62d873b6..0234d4a920ed8 100644 --- a/src/doc/rustc-dev-guide/src/rustdoc-internals.md +++ b/src/doc/rustc-dev-guide/src/rustdoc-internals.md @@ -270,35 +270,6 @@ in `test.rs` is the function `make_test`, which is where hand-written 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 diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-gui-test-suite.md b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-gui-test-suite.md new file mode 100644 index 0000000000000..e155f960e3d6a --- /dev/null +++ b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-gui-test-suite.md @@ -0,0 +1,14 @@ +# The `rustdoc-gui` test suite + +> **FIXME**: This section is a stub. Please help us flesh it out! + +This page is about the test suite named `rustdoc-gui` used to test the "GUI" of `rustdoc` (i.e., the HTML/JS/CSS as rendered in a browser). +For other rustdoc-specific test suites, see [Rustdoc test suites]. + +These use a NodeJS-based tool called [`browser-UI-test`] that uses [puppeteer] to run tests in a headless browser and check rendering and interactivity. For information on how to write this form of test, see [`tests/rustdoc-gui/README.md`][rustdoc-gui-readme] as well as [the description of the `.goml` format][goml-script] + +[Rustdoc test suites]: ../tests/compiletest.md#rustdoc-test-suites +[`browser-UI-test`]: https://github.com/GuillaumeGomez/browser-UI-test/ +[puppeteer]: https://pptr.dev/ +[rustdoc-gui-readme]: https://github.com/rust-lang/rust/blob/master/tests/rustdoc-gui/README.md +[goml-script]: https://github.com/GuillaumeGomez/browser-UI-test/blob/master/goml-script.md diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-json-test-suite.md b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-json-test-suite.md new file mode 100644 index 0000000000000..e08f77095069b --- /dev/null +++ b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-json-test-suite.md @@ -0,0 +1,3 @@ +# The `rustdoc-json` test suite + +> **FIXME**: This section is a stub. It will be populated by [PR #2422](https://github.com/rust-lang/rustc-dev-guide/pull/2422/). diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md index bad7ac19da2cb..b05318ce9e6cf 100644 --- a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md +++ b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md @@ -1,112 +1,191 @@ # The `rustdoc` test suite -This page is specifically about the test suite named `rustdoc`. -For other test suites used for testing rustdoc, see [Rustdoc tests](../rustdoc.md#tests). +This page is about the test suite named `rustdoc` used to test the HTML output of `rustdoc`. +For other rustdoc-specific test suites, see [Rustdoc test suites]. -The `rustdoc` test suite is specifically used to test the HTML output of rustdoc. +Each test file in this test suite is simply a Rust source file `file.rs` sprinkled with +so-called *directives* located inside normal Rust code comments. +These come in two flavors: *Compiletest* and *HtmlDocCk*. -This is achieved by means of `htmldocck.py`, a custom checker script that leverages [XPath]. +To learn more about the former, read [Compiletest directives]. +For the latter, continue reading. -[XPath]: https://en.wikipedia.org/wiki/XPath +Internally, [`compiletest`] invokes the supplementary checker script [`htmldocck.py`]. -## Directives -Directives to htmldocck are similar to those given to `compiletest` in that they take the form of `//@` comments. +[Rustdoc test suites]: ../tests/compiletest.md#rustdoc-test-suites +[`compiletest`]: ../tests/compiletest.md +[`htmldocck.py`]: https://github.com/rust-lang/rust/blob/master/src/etc/htmldocck.py -In addition to the directives listed here, -`rustdoc` tests also support most -[compiletest directives](../tests/directives.html). +## HtmlDocCk Directives -All `PATH`s in directives are relative to the rustdoc output directory (`build/TARGET/test/rustdoc/TESTNAME`), -so it is conventional to use a `#![crate_name = "foo"]` attribute to avoid -having to write a long crate name multiple times. -To avoid repetition, `-` can be used in any `PATH` argument to re-use the previous `PATH` argument. +Directives to HtmlDocCk are assertions that place constraints on the generated HTML. +They look similar to those given to `compiletest` in that they take the form of `//@` comments +but ultimately, they are completey distinct and processed by different programs. -All arguments take the form of quoted strings -(both single and double quotes are supported), -with the exception of `COUNT` and the special `-` form of `PATH`. +[XPath] is used to query parts of the HTML document tree. + +**Introductory example**: + +```rust,ignore (illustrative) +//@ has file/type.Alias.html +//@ has - '//*[@class="rust item-decl"]//code' 'type Alias = Option;' +pub type Alias = Option; +``` + +Here, we check that documentation generated for crate `file` contains a page for the +public type alias `Alias` where the code block that is found at the top contains the +expected rendering of the item. The `//*[@class="rust item-decl"]//code` is an XPath +expression. -Directives are assertions that place constraints on the generated HTML. +Conventionally, you place these directives directly above the thing they are meant to test. +Technically speaking however, they don't need to be as HtmlDocCk only looks for the directives. -All directives (except `files`) can be negated by putting a `!` in front of their name. +All directives take a `PATH` argument. +To avoid repetition, `-` can be passed to it to re-use the previous `PATH` argument. +Since the path contains the name of the crate, it is conventional to add a +`#![crate_name = "foo"]` attribute to the crate root to shorten the resulting path. + +All arguments take the form of shell-style (single or double) quoted strings, +with the exception of `COUNT` and the special `-` form of `PATH`. + +All directives (except `files`) can be *negated* by putting a `!` in front of their name. +Before you add negated directives, please read about [their caveats](#caveats). Similar to shell commands, directives can extend across multiple lines if their last char is `\`. In this case, the start of the next line should be `//`, with no `@`. -For example, `//@ !has 'foo/struct.Bar.html'` checks that crate `foo` does not have a page for a struct named `Bar` in the crate root. +Use the special string `{{channel}}` in XPaths, `PATTERN` arguments and [snapshot files](#snapshot) +if you'd like to refer to the URL `https://doc.rust-lang.org/CHANNEL` where `CHANNEL` refers to the +current release channel (e.g, `stable` or `nightly`). + +Listed below are all possible directives: + +[XPath]: https://en.wikipedia.org/wiki/XPath ### `has` -Usage 1: `//@ has PATH` -Usage 2: `//@ has PATH XPATH PATTERN` +> Usage 1: `//@ has PATH` -In the first form, `has` checks that a given file exists. +Check that the file given by `PATH` exists. -In the second form, `has` is an alias for `matches`, -except `PATTERN` is a whitespace-normalized[^1] string instead of a regex. +> Usage 2: `//@ has PATH XPATH PATTERN` -### `matches` +Checks that the text of each element / attribute / text selected by `XPATH` in the +whitespace-normalized[^1] file given by `PATH` matches the +(also whitespace-normalized) string `PATTERN`. + +**Tip**: If you'd like to avoid whitespace normalization and/or if you'd like to match with a regex, +use `matches` instead. -Usage: `//@ matches PATH XPATH PATTERN` +### `hasraw` -Checks that the text of each element selected by `XPATH` in `PATH` matches the python-flavored regex `PATTERN`. +> Usage: `//@ hasraw PATH PATTERN` -### `matchesraw` +Checks that the contents of the whitespace-normalized[^1] file given by `PATH` +matches the (also whitespace-normalized) string `PATTERN`. -Usage: `//@ matchesraw PATH PATTERN` +**Tip**: If you'd like to avoid whitespace normalization and / or if you'd like to match with a +regex, use `matchesraw` instead. -Checks that the contents of the file `PATH` matches the regex `PATTERN`. +### `matches` -### `hasraw` +> Usage: `//@ matches PATH XPATH PATTERN` -Usage: `//@ hasraw PATH PATTERN` +Checks that the text of each element / attribute / text selected by `XPATH` in the +file given by `PATH` matches the Python-flavored[^2] regex `PATTERN`. -Same as `matchesraw`, except `PATTERN` is a whitespace-normalized[^1] string instead of a regex. +### `matchesraw` + +> Usage: `//@ matchesraw PATH PATTERN` + +Checks that the contents of the file given by `PATH` matches the +Python-flavored[^2] regex `PATTERN`. ### `count` -Usage: `//@ count PATH XPATH COUNT` +> Usage: `//@ count PATH XPATH COUNT` -Checks that there are exactly `COUNT` matches for `XPATH` within the file `PATH`. +Checks that there are exactly `COUNT` matches for `XPATH` within the file given by `PATH`. ### `snapshot` -Usage: `//@ snapshot NAME PATH XPATH` +> Usage: `//@ snapshot NAME PATH XPATH` -Creates a snapshot test named NAME. -A snapshot test captures a subtree of the DOM, at the location -determined by the XPath, and compares it to a pre-recorded value -in a file. The file's name is the test's name with the `.rs` extension -replaced with `.NAME.html`, where NAME is the snapshot's name. +Checks that the element / text selected by `XPATH` in the file given by `PATH` matches the +pre-recorded subtree or text (the "snapshot") in file `FILE_STEM.NAME.html` where `FILE_STEM` +is the file stem of the test file. -htmldocck supports the `--bless` option to accept the current subtree -as expected, saving it to the file determined by the snapshot's name. -compiletest's `--bless` flag is forwarded to htmldocck. +Pass the `--bless` option to `compiletest` to accept the current subtree/text as expected. +This will overwrite the aforementioned file (or create it if it doesn't exist). It will +automatically normalize the channel-dependent URL `https://doc.rust-lang.org/CHANNEL` to +the special string `{{channel}}`. ### `has-dir` -Usage: `//@ has-dir PATH` +> Usage: `//@ has-dir PATH` -Checks for the existence of directory `PATH`. +Checks for the existence of the directory given by `PATH`. ### `files` -Usage: `//@ files PATH ENTRIES` +> Usage: `//@ files PATH ENTRIES` + +Checks that the directory given by `PATH` contains exactly `ENTRIES`. +`ENTRIES` is a Python-like list of strings inside a quoted string. + +**Example**: `//@ files "foo/bar" '["index.html", "sidebar-items.js"]'` + +[^1]: Whitespace normalization means that all spans of consecutive whitespace are replaced with a single space. +[^2]: They are Unicode aware (flag `UNICODE` is set), match case-sensitively and in single-line mode. + +## Compiletest Directives (Brief) + +As mentioned in the introduction, you also have access to [compiletest directives]. +Most importantly, they allow you to register auxiliary crates and +to pass flags to the `rustdoc` binary under test. +It's *strongly recommended* to read that chapter if you don't know anything about them yet. + +Here are some details that are relevant to this test suite specifically: -Checks that the directory `PATH` contains exactly `ENTRIES`. -`ENTRIES` is a python list of strings inside a quoted string, -as if it were to be parsed by `eval`. -(note that the list is actually parsed by `shlex.split`, -so it cannot contain arbitrary python expressions). +* While you can use both `//@ compile-flags` and `//@ doc-flags` to pass flags to `rustdoc`, + prefer to user the latter to show intent. The former is meant for `rustc`. +* Add `//@ build-aux-docs` to the test file that has auxiliary crates to not only compile the + auxiliaries with `rustc` but to also document them with `rustdoc`. -Example: `//@ files "foo/bar" '["index.html", "sidebar-items.js"]'` +## Caveats -[^1]: Whitespace normalization means that all spans of consecutive whitespace are replaced with a single space. The files themselves are also whitespace-normalized. +Testing for the absence of an element or a piece of text is quite fragile and not very future proof. + +It's not unusual that the *shape* of the generated HTML document tree changes from time to time. +This includes for example renamings of CSS classes. + +Whenever that happens, *positive* checks will either continue to match the intended element / +attribute / text (if their XPath expression is general / loose enough) and +thus continue to test the correct thing or they won't in which case they would fail thereby +forcing the author of the change to look at them. + +Compare that to *negative* checks (e.g., `//@ !has PATH XPATH PATTERN`) which won't fail if their +XPath expression "no longer" matches. The author who changed "the shape" thus won't get notified and +as a result someone else can unintentionally reintroduce `PATTERN` into the generated docs without +the original negative check failing. + +**Note**: Please avoid the use of *negated* checks! + +**Tip**: If you can't avoid it, please **always** pair it with an analogous positive check in the +immediate vicinity, so people changing "the shape" have a chance to notice and to update the +negated check! ## Limitations -`htmldocck.py` uses the xpath implementation from the standard library. + +HtmlDocCk uses the XPath implementation from the Python standard library. This leads to several limitations: + * All `XPATH` arguments must start with `//` due to a flaw in the implementation. * Many XPath features (functions, axies, etc.) are not supported. * Only well-formed HTML can be parsed (hopefully rustdoc doesn't output mismatched tags). +Furthmore, compiletest [revisions] are not supported. + +[revisions]: ../tests/compiletest.md#revisions +[compiletest directives]: ../tests/directives.md diff --git a/src/doc/rustc-dev-guide/src/rustdoc.md b/src/doc/rustc-dev-guide/src/rustdoc.md index de70ba6382372..52ae48c3735c0 100644 --- a/src/doc/rustc-dev-guide/src/rustdoc.md +++ b/src/doc/rustc-dev-guide/src/rustdoc.md @@ -67,43 +67,29 @@ does is call the `main()` that's in this crate's `lib.rs`, though.) ## Code structure -* All paths in this section are relative to `src/librustdoc` in the rust-lang/rust repository. +All paths in this section are relative to `src/librustdoc/` in the rust-lang/rust repository. + * Most of the HTML printing code is in `html/format.rs` and `html/render/mod.rs`. - It's in a bunch of `fmt::Display` implementations and supplementary - functions. -* The types that got `Display` impls above are defined in `clean/mod.rs`, right - next to the custom `Clean` trait used to process them out of the rustc HIR. + It's in a bunch of functions returning `impl std::fmt::Display`. +* The data types that get rendered by the functions mentioned above are defined in `clean/types.rs`. + The functions responsible for creating them from the `HIR` and the `rustc_middle::ty` IR + live in `clean/mod.rs`. * The bits specific to using rustdoc as a test harness are in `doctest.rs`. * The Markdown renderer is loaded up in `html/markdown.rs`, including functions for extracting doctests from a given block of Markdown. * Frontend CSS and JavaScript are stored in `html/static/`. + * Re. JavaScript, type annotations are written using [TypeScript-flavored JSDoc] +comments and an external `.d.ts` file. + This way, the code itself remains plain, valid JavaScript. + We only use `tsc` as a linter. -## Tests +[TypeScript-flavored JSDoc]: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html -* Tests on search engine and index are located in `tests/rustdoc-js` and `tests/rustdoc-js-std`. - The format is specified - [in the search guide](rustdoc-internals/search.md#testing-the-search-engine). -* Tests on the "UI" of rustdoc (the terminal output it produces when run) are in - `tests/rustdoc-ui` -* Tests on the "GUI" of rustdoc (the HTML, JS, and CSS as rendered in a browser) - are in `tests/rustdoc-gui`. These use a [NodeJS tool called - browser-UI-test](https://github.com/GuillaumeGomez/browser-UI-test/) that uses - puppeteer to run tests in a headless browser and check rendering and - interactivity. For information on how to write this form of test, - see [`tests/rustdoc-gui/README.md`][rustdoc-gui-readme] - as well as [the description of the `.goml` format][goml-script] -* Tests on the structure of rustdoc HTML output are located in `tests/rustdoc`, - where they're handled by the test runner of bootstrap and - the supplementary script `src/etc/htmldocck.py`. - [These tests have several extra directives available to them](./rustdoc-internals/rustdoc-test-suite.md). -* Additionally, JavaScript type annotations are written using [TypeScript-flavored JSDoc] - comments and an external d.ts file. The code itself is plain, valid JavaScript; we only - use tsc as a linter. +## Tests -[TypeScript-flavored JSDoc]: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html -[rustdoc-gui-readme]: https://github.com/rust-lang/rust/blob/master/tests/rustdoc-gui/README.md -[goml-script]: https://github.com/GuillaumeGomez/browser-UI-test/blob/master/goml-script.md +`rustdoc`'s integration tests are split across several test suites. +See [Rustdoc tests suites](tests/compiletest.md#rustdoc-test-suites) for more details. ## Constraints diff --git a/src/doc/rustc-dev-guide/src/tests/compiletest.md b/src/doc/rustc-dev-guide/src/tests/compiletest.md index ee06ca3b69850..20dd16c81df61 100644 --- a/src/doc/rustc-dev-guide/src/tests/compiletest.md +++ b/src/doc/rustc-dev-guide/src/tests/compiletest.md @@ -56,6 +56,9 @@ incremental compilation. The various suites are defined in The following test suites are available, with links for more information: +[`tests`]: https://github.com/rust-lang/rust/blob/master/tests +[`src/tools/compiletest/src/common.rs`]: https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/common.rs + ### Compiler-specific test suites | Test suite | Purpose | @@ -71,6 +74,7 @@ The following test suites are available, with links for more information: | [`mir-opt`](#mir-opt-tests) | Check MIR generation and optimizations | | [`coverage`](#coverage-tests) | Check coverage instrumentation | | [`coverage-run-rustdoc`](#coverage-tests) | `coverage` tests that also run instrumented doctests | +| [`crashes`](#crashes-tests) | Check that the compiler ICEs/panics/crashes on certain inputs to catch accidental fixes | ### General purpose test suite @@ -78,19 +82,23 @@ The following test suites are available, with links for more information: ### Rustdoc test suites -See [Rustdoc tests](../rustdoc.md#tests) for more details. - -| Test suite | Purpose | -|------------------|--------------------------------------------------------------------------| -| `rustdoc` | Check `rustdoc` generated files contain the expected documentation | -| `rustdoc-gui` | Check `rustdoc`'s GUI using a web browser | -| `rustdoc-js` | Check `rustdoc` search is working as expected | -| `rustdoc-js-std` | Check rustdoc search is working as expected specifically on the std docs | -| `rustdoc-json` | Check JSON output of `rustdoc` | -| `rustdoc-ui` | Check terminal output of `rustdoc` | - -[`tests`]: https://github.com/rust-lang/rust/blob/master/tests -[`src/tools/compiletest/src/common.rs`]: https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/common.rs +| Test suite | Purpose | +|--------------------------------------|--------------------------------------------------------------------------| +| [`rustdoc`][rustdoc-html-tests] | Check HTML output of `rustdoc` | +| [`rustdoc-gui`][rustdoc-gui-tests] | Check `rustdoc`'s GUI using a web browser | +| [`rustdoc-js`][rustdoc-js-tests] | Check `rustdoc`'s search engine and index | +| [`rustdoc-js-std`][rustdoc-js-tests] | Check `rustdoc`'s search engine and index on the std library docs | +| [`rustdoc-json`][rustdoc-json-tests] | Check JSON output of `rustdoc` | +| `rustdoc-ui` | Check terminal output of `rustdoc` ([see also](ui.md)) | + +Some rustdoc-specific tests can also be found in `ui/rustdoc/`. +These check rustdoc-related or -specific lints that (also) run as part of `rustc`, not (only) `rustdoc`. +Run-make tests pertaining to rustdoc are typically named `run-make/rustdoc-*/`. + +[rustdoc-html-tests]: ../rustdoc-internals/rustdoc-test-suite.md +[rustdoc-gui-tests]: ../rustdoc-internals/rustdoc-gui-test-suite.md +[rustdoc-js-tests]: ../rustdoc-internals/search.md#testing-the-search-engine +[rustdoc-json-tests]: ../rustdoc-internals/rustdoc-json-test-suite.md ### Pretty-printer tests diff --git a/src/doc/rustc-dev-guide/src/tests/directives.md b/src/doc/rustc-dev-guide/src/tests/directives.md index 2dff21ed61c28..f73a2811d5adf 100644 --- a/src/doc/rustc-dev-guide/src/tests/directives.md +++ b/src/doc/rustc-dev-guide/src/tests/directives.md @@ -261,7 +261,7 @@ Consider writing the test as a proper incremental test instead. | Directive | Explanation | Supported test suites | Possible values | |-------------|--------------------------------------------------------------|------------------------------------------|---------------------------| -| `doc-flags` | Flags passed to `rustdoc` when building the test or aux file | `rustdoc`, `rustdoc-js`, `rustdoc-json` | Any valid `rustdoc` flags | +| `doc-flags` | Flags passed to `rustdoc` when building the test or aux file | `rustdoc`, `rustdoc-js`, `rustdoc-json` | Any valid `rustdoc` flags | +#### Test-suite-specific directives + +The test suites [`rustdoc`][rustdoc-html-tests], [`rustdoc-js`/`rustdoc-js-std`][rustdoc-js-tests] +and [`rustdoc-json`][rustdoc-json-tests] each feature an additional set of directives whose basic +syntax resembles the one of compiletest directives but which are ultimately read and checked by +separate tools. For more information, please read their respective chapters as linked above. + +[rustdoc-html-tests]: ../rustdoc-internals/rustdoc-test-suite.md +[rustdoc-js-tests]: ../rustdoc-internals/search.html#testing-the-search-engine +[rustdoc-json-tests]: ../rustdoc-internals/rustdoc-json-test-suite.md + ### Pretty printing See [Pretty-printer](compiletest.md#pretty-printer-tests). diff --git a/src/doc/rustc-dev-guide/src/tests/ui.md b/src/doc/rustc-dev-guide/src/tests/ui.md index 3402838da878b..25d3efdbb8260 100644 --- a/src/doc/rustc-dev-guide/src/tests/ui.md +++ b/src/doc/rustc-dev-guide/src/tests/ui.md @@ -220,8 +220,12 @@ negligible (i.e. there is no semantic difference between `//~ ERROR` and `//~ERROR` although the former is more common in the codebase). `~? ` (example being `~? ERROR`) -is used to match diagnostics without line information. -These can be placed on any line in the test file, but are conventionally placed at the end. +is used to match diagnostics _without_ line info at all, +or where the line info is outside the main test file[^main test file]. +These annotations can be placed on any line in the test file. + +[^main test file]: This is a file that has the `~?` annotations, +as distinct from aux files, or sources that we have no control over. ### Error annotation examples diff --git a/src/doc/rustc-dev-guide/triagebot.toml b/src/doc/rustc-dev-guide/triagebot.toml index 978802edf3f08..b3f4c2d281cd8 100644 --- a/src/doc/rustc-dev-guide/triagebot.toml +++ b/src/doc/rustc-dev-guide/triagebot.toml @@ -72,6 +72,23 @@ days-threshold = 7 # Documentation at: https://forge.rust-lang.org/triagebot/pr-assignment.html [assign] +# NOTE: do not add `[assign.owners]` if we still wish to keep the opt-in +# reviewer model, as `[assign.owners]` will cause triagebot auto-reviewer +# assignment to kick in. + +# Custom PR welcome message for when no auto reviewer assignment is performed +# and no explicit manual reviewer selection is made. +# Documentation at: https://forge.rust-lang.org/triagebot/pr-assignment.html#custom-welcome-messages +[assign.custom_welcome_messages] +welcome-message = "" +welcome-message-no-reviewer = """\ +Thanks for the PR. If you have write access, feel free to merge this PR if it \ +does not need reviews. You can request a review using `r? rustc-dev-guide` or \ +`r? `. +""" + +# Groups for `r? `. +# Documentation at: https://forge.rust-lang.org/triagebot/pr-assignment.html#usage # Keep members alphanumerically sorted. [assign.adhoc_groups] rustc-dev-guide = [