New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rustbuild: neither `./x.py doc --stage 0` nor `./x.py doc --stage 1 --keep-stage 0` regenerate api docs if only rustdoc changed #42686

Open
QuietMisdreavus opened this Issue Jun 15, 2017 · 1 comment

Comments

Projects
None yet
3 participants
@QuietMisdreavus
Member

QuietMisdreavus commented Jun 15, 2017

If i want to test a change to rustdoc by re-rendering the std docs, i could combine the "rebuild rustdoc" and "render api docs" steps into an ./x.py doc command. If i wanted to avoid rebuilding all of stage1, then i could try ./x.py doc --stage 0, but that doesn't actually re-render the documentation! It gets to that step, sees that the documentation output is newer than the source files for libstd, then skips it. (The same problem occurs with ./x.py doc --stage 1 --keep-stage 0, on a related note.) This requires a rustdoc contributor to rebuild an entire stage to be able to test their change on a rendering of std. (Testing it by rendering a separate crate is still possible, i suppose, but also requires the additional step of linking the toolchain in rustup or using the test rustdoc/rustc by a different means.)

@QuietMisdreavus

This comment has been minimized.

Member

QuietMisdreavus commented Jun 15, 2017

This is kinda related to #38318, but not precisely. I'd made a comment in there explaining my findings when i first saw this behavior. However, looking back at that issue, that seems to be more about how --keep-stage isn't enabled by default, rather than not considering generated docs to need regeneration after a rustdoc change.

bors added a commit that referenced this issue Jul 27, 2017

Auto merge of #43482 - Mark-Simulacrum:single-rustdoc, r=alexcrichton
Compile rustdoc on-demand

Fixes #43284, fixes #38318, and fixes #39505.

Doesn't directly help with #42686, since we need to rebuild just as much. In fact, this hurts it, since `./x.py doc --stage 0` will now fail. I'm not sure if it did before, but with these changes it runs into the problem where we attempt to use artifacts from bootstrap rustc with a non-bootstrap rustdoc, running into version conflicts. I believe this is solvable, but leaving for a future PR.

This means that rustdoc will no longer be compiled when compiling rustc, by default. However, it is still built from `./x.py build` (for hosts, but not targets, since we don't produce compiler toolchains for them) and will be built for doc tests and crate tests.

After this, the recommended workflow if you want a rustdoc is: `./x.py build --stage 1 src/tools/rustdoc` which will give you a working rustdoc in `build/triple/stage1/bin/rustdoc`. Note that you can add `src/libstd` onto the command to compile libstd as well so that the rustdoc can easily compile crates in the wild. `./x.py doc --stage 1 src/libstd` will document `libstd` with a freshly built rustdoc (if necessary), and will not rebuild rustc on modifications to rustdoc.

r? @alexcrichton

bors added a commit that referenced this issue Jul 27, 2017

Auto merge of #43482 - Mark-Simulacrum:single-rustdoc, r=alexcrichton
Compile rustdoc on-demand

Fixes #43284, fixes #38318, and fixes #39505.

Doesn't directly help with #42686, since we need to rebuild just as much. In fact, this hurts it, since `./x.py doc --stage 0` will now fail. I'm not sure if it did before, but with these changes it runs into the problem where we attempt to use artifacts from bootstrap rustc with a non-bootstrap rustdoc, running into version conflicts. I believe this is solvable, but leaving for a future PR.

This means that rustdoc will no longer be compiled when compiling rustc, by default. However, it is still built from `./x.py build` (for hosts, but not targets, since we don't produce compiler toolchains for them) and will be built for doc tests and crate tests.

After this, the recommended workflow if you want a rustdoc is: `./x.py build --stage 1 src/tools/rustdoc` which will give you a working rustdoc in `build/triple/stage1/bin/rustdoc`. Note that you can add `src/libstd` onto the command to compile libstd as well so that the rustdoc can easily compile crates in the wild. `./x.py doc --stage 1 src/libstd` will document `libstd` with a freshly built rustdoc (if necessary), and will not rebuild rustc on modifications to rustdoc.

r? @alexcrichton

@Mark-Simulacrum Mark-Simulacrum added this to the impl period milestone Sep 15, 2017

@aturon aturon removed this from the impl period milestone Sep 15, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment