[WIP] rustdoc testing: Further improve chapters and sections #2298
Conversation
fmease
added
S-waiting-on-author
| ## Htmldocck-Specific Directives | ||
|
|
||
| In addition to the directives listed here, | ||
| `rustdoc` tests also support most | ||
| [compiletest directives](../tests/directives.html). | ||
| Directives to htmldocck are similar to those given to `compiletest` in that they take the form of `//@` comments. |
There was a problem hiding this comment.
Suggestion: even though it's an implementation detail, I think it's worth hammering in the distinction that htmldocck directives are handled by htmldocck and not compiletest.
| @@ -34,33 +32,41 @@ 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. | |||
|
|
|||
| <!-- FIXME(fmease): Mention that the regexes match case-sensitively and in single-line mode? --> | |||
There was a problem hiding this comment.
Discussion: may also be worth mentioning if the regexes have any string and/or regex escape rules. For instance, I know some compiletest regex directives don't handle this very well.
| htmldocck supports the `--bless` option to accept the current subtree | ||
| Htmldocck supports the `--bless` option to accept the current subtree |
There was a problem hiding this comment.
Question: IIRC the --bless flow requires html-tidy to be installed and available somewhere. Not sure if this is mentioned already. Maybe worth explicitly remarking or linking to that?
| <!-- FIXME(fmease): | ||
| Should definitely also mention `//@ aux-crate` and `//@ proc-macro` | ||
| UNLESS we nuke this paragraph entirely and refer to the compiletest section(s)? | ||
| --> |
There was a problem hiding this comment.
Remark (not-a-review-comment): I think this is where I would like compiletest to support some kind of directive handling "plugin" and allow htmldocck to register plugins. Then we could phrase this as "htmldocck registers additional directive handling to compiletest" either here, or even put this bit under main compiletest chapter.
There was a problem hiding this comment.
Suggestion: may or may not be helpful for someone looking to adjust how tests/rustdoc works / change htmldocck/compiletest for tests/rustdoc purposes... but here's a very coarse TL;DR on the test infra bits involved on running tests/rustdoc:
Test infra setup
The test infra setup for tests/rustdoc involves the following bits:
- Bootstrap (the build system) and its test step that builds:
- A suitably-staged sysroot (including the compiler and standard library).
- A rustdoc built with the sysroot.
compiletestitself, and running it with the suitable configuration under therustdoctest mode.- The implementation can be traced back from https://github.com/rust-lang/rust/blob/4e2b096ed6c8a1400624a54f6c4fd0c0ce48a579/src/bootstrap/src/core/build_steps/test.rs#L1349-L1355.
compiletesthandles the test discovery, compiletest directive parsing/handling (not to be confused with htmldocck directives) and test running via libtest. Seesrc/tools/compiletest/src/runtest/rustdoc.rs.compiletestinvokessrc/etc/htmldocck.pyagainst the test file.
Follow-up to #2295 (applies my remaining review comments).
This is WIP / a draft because I g2g. Will impl all FIXME(fmease)s when I come back.
cc @lolbinarycat @jieyouxu @notriddle