Direct contributors to try stage 0 rustdoc first #71645
Conversation
|
(rust_highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
CONTRIBUTING.md
Outdated
| In many cases, you don't need a full `./x.py doc`, which will build the entire | ||
| stage 2 compiler. When updating documentation for the standard library, first | ||
| try `./x.py doc --stage 0 src/libstd`. Results will should appear in | ||
| `build/$TARGET/crate-docs`. |
There was a problem hiding this comment.
We should definitely recommend stage 1 (which should always work) if this fails, which it could, as rustdoc doesn't run on stage 0 in CI, so some annotations may be missing or otherwise incompatible with stage 0. Lack of effective cfg(bootstrap) for docs makes that a particularly thorny problem.
|
Other than that nit, I also am hesitant to suggest use of something that isn't guaranteed to work in official docs, but maybe I'm overly cautious. We could also see how long this takes -- maybe we can run it in CI (on the mingw-check builder)? |
|
When it works, this saves around 15-30 minutes from a clean checkout, possibly more if you're not using the system LLVM. I think it's worth trying. Ideally, we would guarantee that this works via CI as you said. Just building stage0 artifacts and documenting them takes about a minute locally, so I don't think CI time will be an issue, although I don't know all the constraints. Would doing this make upgrading the bootstrap compiler more difficult or anything? |
|
Yeah, I definitely agree it is worth it, I'm just concerned whether instructions that might not work are more of a discouragement than very slow instructions. I'm inclined to agree we should do as you suggest though. Can you add a stage 0 doc build to the mingw-check builder? Should be in src/ci/docker/mingw-check/Dockerfile. Probably the last thing we want to do on that builder. We can definitely afford a few minutes of CI time there. |
|
Presumably the problem is not the CI time, but rather that we'd have to wait for rustdoc improvements to make their way into stage0 before we can take advantage of them, right? |
|
Also, if there are incompatibilities between stage0 and stage1/2 -- maybe changes to unstable features -- that is a thorny problem. |
|
I personally think this advice is ok. It's not ideal, but I think contributors can handle it. |
|
@nikomatsakis In some cases you will be able to hide those bits behind I'll submit a second PR that adds |
ecstatic-morse
force-pushed
the
readme-build-doc
branch
from
68d5291 to
5577b35
Compare
|
@Mark-Simulacrum Anything I need to do here? We're now ~2 weeks after the bootstrap version bump and |
|
📌 Commit 5577b35 has been approved by |
bors
added
S-waiting-on-bors
Rollup of 4 pull requests Successful merges: - rust-lang#71645 (Direct contributors to try stage 0 rustdoc first) - rust-lang#71801 (Correctly check comparison operator in MIR typeck) - rust-lang#71844 (List Clippy as a subtree, instead of a submodule) - rust-lang#71864 (Update link in contributing.md) Failed merges: r? @ghost
…Simulacrum Ensure that `./x.py doc --stage 0 src/libstd` works via CI This was split off from rust-lang#71645, which recommends that users first try building `libstd` docs with the bootstrap `rustdoc`. This should work in most cases, but will fail if we start using a very recent `rustdoc` feature outside a `#[cfg(not(bootstrap))]`. It would be very nice to guarantee that `./x.py doc --stage 0 src/libstd` works, since it allows documentation changes to be rendered locally without needing to build the compiler. However, it may put too big a burden on `rustdoc` developers who presumably want to dogfood new features.
After #71458,
./x.py doc --stage 0 src/libstdis (empirically) able to build the standard library docs using therustdocpackaged with the bootstrap compiler. This means that new contributors don't need to build the compiler to locally inspect small documentation fixes. This was a roadblock for me when I first started contributing to rust and something that still regularly annoys people. We should recommend that contributors give bootstraprustdoca try before building the whole compiler.