Host compiler documentation

[davidtwco]

This is the second half of rust-lang/rust#29893. The matching rust PR is rust-lang/rust#49193.

[davidtwco]

I've marked this as WIP as it hasn't been tested yet, until the matching Rust PR is merged and that produces tarballs, I'm not sure if it can.

[alexcrichton]

This tentatively looks good, thanks! I'll take a closer look at rust-lang/rust#49193 now

[davidtwco]

Renamed this to remove the WIP since rust-lang/rust#49193 has landed and this can now be properly tested.

[alexcrichton]

Ok great! One thing I actually realized though is that we'll want to gracefully handle the lack of a rustc-docs tarball as not all the stable/beta/nightly channels are currently producing one?

[davidtwco]

@alexcrichton I've pushed a commit that adds a check for this.

[Michael-F-Bryan]

@davidtwco, does this mean we'll have a place to view the API docs for rustc internals once this PR lands? At the moment I'm using a rustc-internal-docs "script" to run ./x.py doc every night and upload the crate docs to GitHub Pages, but that's a pretty hacky solution and it looks like changes in x.py have broken it again (it no longer creates docs for librustc_driver and other internals).

@nikomatsakis, @mark-i-m, once this PR merges I believe rustc-guide should be able to link to the actual docs for various compiler internals (@davidtwco, feel free to correct me on this). It'd be much more useful to link to the rustdoc for structs/functions instead of the source code, and hopefully my mdbook-linkcheck will be able to detect broken links as things change.

[davidtwco]

@Michael-F-Bryan If I'm not mistaken, they will be available at doc.rust-lang.org/nightly-rustc/<crate_name> (or something along those lines). I don't see any reason why you wouldn't be able to link to it.

[mark-i-m]

@Michael-F-Bryan could you open an issue on rustc-guide to change the links?

[nikomatsakis]

So excited for this. =)

[alexcrichton]

Thanks @davidtwco! This looks great to me now. We've got a release in a few days so I'm gonna hold off on merging this until that's done, but I'll merge and test after that.

[Manishearth]

(we've released!)

[Michael-F-Bryan]

Awesome work @davidtwco and @alexcrichton!

Will the new internal API docs be available when the next nightly is released?

[alexcrichton]

I've just now deployed this change to production, and yes hopefully after the next nightly we'll have shiny new docs!

[mark-i-m]

Where will they be hosted? doc.rust-lang.org/nightly-rustc?

[alexcrichton]

I believe it'll be doc.rust-lang.org/nightly/nightly-rustc

[mark-i-m]

I'm guessing #43 means we will get this for tomorrow's nightly instead?

[davidtwco]

@mark-i-m Yeah, sorry about that, it should work for tomorrow's nightly.

[alexcrichton]

Documentation is now live!

[mark-i-m]

Hmm... there appear to be some items missing. For example: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir/interpret/index.html?search=mk_eval_cx which should show https://github.com/rust-lang/rust/blob/fb44b4c0eb1d344f84f7bb2c90f28e31a8a180be/src/librustc_mir/interpret/const_eval.rs#L40

Is this expected?

[Manishearth]

That's a private module

[mark-i-m]

Oh, are they not documented? (EDIT: I guess this makes sense as a default, but still...) Would it be possible to generate documentation for them? It would be nice to be able to link to them from the rustc-guide, and they are actually useful for devs...

[Manishearth]

Documenting private items for internals docs is being discussed here

[mark-i-m]

Ah, great! Thanks @Manishearth :)