revamp doc-build chapter

[tshepang]

it's a tiny chapter, so made it lightweight by doing bullet points instead of section headers

[JohnTitor]

This seems a little too concise to me. I'd like to talk that this section is to document things on rust-lang/rust like std or submodule docs at first.

[tshepang]

should I remove this mention... I only kept it because I found it there, and I feel it's not worth a mention

[JohnTitor]

and I feel it's not worth a mention

Hmm, why? I think describing what this page talks about at first makes some sense as not all readers will read through the entire chapter.

[tshepang]

I meant only the part about rustdoc being able to be run on a single file

[JohnTitor]

I mean you removed the "You might want to build documentation of the various components available like the standard library." sentence but the introduction now sounds a little too concise.

[tshepang]

my latest commit is also concise, but it explains what the chapter is about... whatyouthink

[jyn514]

I agree with @JohnTitor, "toolchain components" seems like jargon that won't be familiar to most readers. I think "the various components available, like the standard library or compiler," would be more clear.

[jyn514]

hmm, this sentence is saying a lot of complicated things in very few words.

• rustdoc doesn't check that programs are valid, so you have to run rustc directly to make sure the program compiles
• rustdoc uses the built metadata to document the compiler (it's very unclear in this sentence whether "it" refers to rustdoc or bootstrap).

unless it's talking about stage1, in which case it's just completely wrong - the reason you have to build rustdoc is so you can run it, because it might be different from the beta rustdoc.

[jyn514]

(this is also one of the few cases where --keep-stage 0 is sound - if you've only modified documentation, it can't affect the build artifacts, so it's ok to only rebuild the documentation and not rustdoc itself.)

[tshepang]

not sure how much detail to provide, but please have a look at the small change I made

[jyn514]

This looks a lot better than before, thanks :)

[jyn514]

this is super nitpicky and you can ignore it if you like, but I still feel like "make sure rustdoc compiles" is ambiguous. We're not checking that it compiles, we're actually compiling it. I would be less worried about this if it weren't for the fact that check is a cargo/x.py subcommand 😅

Maybe it makes more sense to just say "first rustdoc is built," ?

[tshepang]

glad you are "nitpicky"... was not too happy with it, so thanks for this