Document clippy on nightly-rustc

[xFrednet]

Adding Clippy's docs to nightly-rustc, based on commit 01cf0bd. This PR only adds clippy_utils to the documentation. I've decided to only document one crate for now, as clippy_lints etc. contain very specific and undocumented functions which aren't really reusable. I'm guessing that they would mostly clutter up the search results with little benefit.

./x.py --stage 1 doc src/tools/clippy if working fine now after the help that @jyn514 and @ehuss have provided. A big THANK YOU to them!

[jyn514]

@xFrednet doc --stage 0 doesn't work for the compiler or compiler tools, I expect the error is unrelated to your change. Try x.py doc --stage 1 src/tools/clippy.

[xFrednet]

@jyn514 Thanks, that did the trick, well got me a bit further. Now it's complaining, that it can't find std and core. (The same happens for rustfmt)

error[E0463]: can't find crate for `std`

For more information about this error, try `rustc --explain E0463`.
error: could not compile `serde_derive` due to previous error
warning: build failed, waiting for other jobs to finish...
error[E0463]: can't find crate for `core`

error: build failed


command did not execute successfully: ".../build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "doc" "--target" "x86_64-unknown-linux-gnu" "-Zbinary-dep-depinfo" "-j" "8" "--release" "--manifest-path" ".../src/tools/clippy/Cargo.toml" "-Zskip-rustdoc-fingerprint" "--no-deps" "-p" "clippy_lints" "-p" "clippy_utils"
expected success, got: exit status: 101

The executed command is already looking good IMO :)

[ehuss]

Looks like a bug in x.py. When documenting a single tool, you need to have compiler-docs = true in config.toml. Otherwise documenting rustc is skipped, and the tools generally require that step to be performed.

The was_invoked_explicitly call here should probably be removed.

[xFrednet]

Thank you @ehuss, that did the trick! Everything seems to be working now!

[jyn514]

compiler_docs has always seemed weird to me anyway - rather than a hard on or off switch, could we change it so it only affects the default? So compiler_docs = false means x.py doc won't document rustc, but x.py doc compiler/rustc will. That should fix the CI failure as well and let you remove explicitly_invoked altogether.

[Mark-Simulacrum]

Hm, so the PR discussion seems to indicate that the was_explicitly_invoked call should be removed, but I do not see that in the diff. Did it perhaps forget to get pushed?

FWIW, I don't think that's quite the right fix. The exact way we do defaults here is a bit iffy, as @jyn514 mentions, and we don't have a great story around it, but just dropping the was-explicitly-invoked will break compiler-docs=false builds. I think the appropriate fix is a little more expansive:

• Gate tool doc builds on compiler-docs = true by default (i.e., add a default_condition(run.builder.config.compiler_docs) to the should_run method generated by the macro). They are all generating what is essentially compiler-docs anyway, so this makes sense IMO.
• Modify the default_condition on doc::Rustc to use compiler_docs, not regular docs.
• Remove the gate in doc::Rustc which checks for compiler-docs being enabled as well as the was_explicitly_invoked call, it's no longer needed, as we shouldn't reach that code unless (a) we've enabled compiler-docs or (b) some tool or rustc were explicitly invoked.

[xFrednet]

Hm, so the PR discussion seems to indicate that the was_explicitly_invoked call should be removed, but I do not see that in the diff. Did it perhaps forget to get pushed?

My intention with this PR was only to add Clippy to the nightly-rustc docs. I was at first unable to test the doc building locally due to some missing knowledge, which lead to the PR discussion.

I haven't really looked at the inner workings of the bootstrapping and docs building process. Most of the things you mentioned is new territory for me. I can try my hand on it with some guidance if you'd like. @Mark-Simulacrum

[Mark-Simulacrum]

So this PR works as-is today?

[xFrednet]

Yes! I can locally build the documentation, and it includes the clippy_utils crate.

I only needed help to figure out the comment and changes to the config.toml to do so. The complexity of this process was the starter of the discussion about how this could be improved and what causes it :)

[Mark-Simulacrum]

@bors r+ rollup

Ok, seems good enough for now then.

[bors]

📌 Commit 01e441f has been approved by Mark-Simulacrum