Consolidate bootstrap documentation

[jyn514]

Right now, there are docs for x.py in a bunch of different places:

• https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html#building-the-compiler
• https://rustc-dev-guide.rust-lang.org/building/bootstrapping.html
• https://github.com/rust-lang/rust/blob/master/src/bootstrap/README.md
• https://github.com/rust-lang/rust/blob/master/src/bootstrap/lib.rs

It would be nice to consolidate these some; e.g. lib.rs can probably just point to the README, and lots of the information in the readme is duplicated in the dev-guide and can be deleted and replaced with a link.

cc @Mark-Simulacrum - do you have strong opinions on this?

[Mark-Simulacrum]

No, seems good to consolidate. I personally think we might get something out of ending up with two guides, one of which discusses the content from an internal perspective (e.g., Step, how to add new targets) and another from an external perspective, focusing on what users need to know.

I think most of the existing documentation is sort of in the second of those, but also (potentially correctly, hard for me to say) treats things as a very leaky abstraction and documents a lot of the internals too. I think some of this is our audience, but I do wonder if a much simpler message is possible with just a few standard commands depending on what they want to build, and documenting specific outputs rather than the whole layout. I think right now we're trying to explain things by teaching everything, but perhaps we can get away with not teaching the internals of the abstraction.

Anyway, mostly musing, no strong opinions here.

[jyn514]

We should also document that we support suffixes instead of full paths (e.g. miri instead of src/tools/miri): rust-lang/miri#2698 (comment)

[albertlarsan68]

Hello,

Should I start working on adding doc-comments in bootstrap ?

[jyn514]

@albertlarsan68 more doc-comments are always welcome :) but when I wrote the issue I was imagining coming up for a plan for how to organize the standalone documentation. maybe we can put the internal documentation in src/bootstrap/README and the user facing documentation in the guide?

[onur-ozkan]

@rustbot claim

[onur-ozkan]

Maybe we can put the internal documentation in src/bootstrap/README and the user facing documentation in the guide?

I like the idea and I think this standard should be applied in general since this seperation reduces cost of the maintaince and makes dev-guide more understandable and simple for users.

I will follow that idea in the refactoring.