Link to internal rustdocs

[Michael-F-Bryan]

When rust-lang/rust-central-station#40 lands we'll have a stable location which contains internal API documentation (i.e. the equivalent of ./x.py doc with crate-docs = true) 🎉

This means when referring to a particular struct or function we'll be able too link to its API docs instead of linking to the original source file and hoping for the best.

Once that PR is merged we'll need to:

• Update the code index to point at the API docs instead of source code
• Emphasise linking to API docs where possible when people are contributing new content
• Update the "contributing" section of the README appropriately (Update a few parts of the readme #208)
• Update the "How to build the compiler and run what you built" to mention building docs and where they can be found online?

[rajcspsg]

@Michael-F-Bryan - I'm new to rust. Since I see this is Easy tagged issue shall I take this issue?

[Michael-F-Bryan]

@rajcspsg if you'd like to give it a go that's fine with me, I'm also happy to mentor or answer any questions you encounter while trying to tick this issue off 😁

We'll need to wait for rust-lang/rust-central-station#40 to be fully merged, but after that it should be relatively straightforward. If you subscribe to that issue, GitHub should send you notifications when it is resolved and you can get started.

[rajcspsg]

@Michael-F-Bryan _ Thanks for mentoring me and I'm happy to take your guidance as I'm new to rust.
While we are waiting for related PR to be merged, could you please provide the file which needs to be updated with details.

[Michael-F-Bryan]

It should mainly be a case of looking for all links to source files in the rust-lang/rust repo and replacing them with links to the corresponding API docs.

The easiest way would be to use a tool like grep or ripgrep and search for anything with https:// and .rs in it.

$ rg -e "https?://[^\s]+\.rs"

src/rustc-driver.md
70:[`rustc_driver`]: https://github.com/rust-lang/rust/tree/master/src/librustc_driver
71:[`CompileState`]: https://github.com/rust-lang/rust/blob/master/src/librustc_driver/driver.rs

...

You can see that CompileState is a reference to some struct and the link goes to src/librustc_driver/driver.rs in the rust repo. I believe the internal crate docs will be at https://doc.rust-lang.org/nightly-rustc/, so you'd go there and look for the rustc_driver::CompileState docs, then update the link appropriately.

[mark-i-m]

To clarify, you are looking for links in this repo to the other repo :)

[rajcspsg]

Thanks for the suggestion @mark-i-m @Michael-F-Bryan.

When I searched for here for rustc_driver::CompileState, I end up at stable page documentation of rustc_driver version 1.1.0.

I should have get the nightly documentation link instead of 1.1.0 documentation, correct?

[Michael-F-Bryan]

@rajcspsg yes. That version of the docs looks quite outdated (TyCtxt is still called ctxt for example). I assume they manually uploaded internal docs early on and those old 1.1.0 docs are still on the Rust S3 bucket.

Now we've released 1.25 they'll be able to make progress on merging the rust-lang/rust-central-station#40 PR. We may have to wait a couple more days before the new docs are uploaded and we can link to them though.

EDIT: Looks like the PR was merged 🎉

[mark-i-m]

@rajcspsg IIUC, the new docs should be available tomorrow after the next nightly is released.

[rajcspsg]

Thanks @Michael-F-Bryan @mark-i-m.
I've 2 questions on searching the documentation.

1. I searched for DocContext mentioned in this link using keyword rustdoc::core in DuckDuckGo and get this result. But when I searched for hir::Crate, rustc::hir, rustc::hir::mod etc I didn't get any rust documentation. Are those going to updated with tomorrow documentation release?

2. All the links to chapter return 404 error. For example , the parser in page appendix-code-index.md returns url error. Is it need to be fixed?

[mark-i-m]

I searched for DocContext mentioned in this link using keyword rustdoc::core in DuckDuckGo and get this result. But when I searched for hir::Crate, rustc::hir, rustc::hir::mod etc I didn't get any rust documentation. Are those going to updated with tomorrow documentation release?

Hmm... that link looks pretty outdated too. rust 1.1 was a long time ago. Tomorrow all of the docs should be up (or so I am told). They should look like normal rustdocs and should be hosted at doc.rust-lang.org/nightly/nightly-rustc

So tomorrow (hopefully) you should be able to go to doc.rust-lang.org/nightly/nightly-rustc and just use the normal rustdoc search box to find everything (hopefully).

All the links to chapter return 404 error. For example , the parser in page appendix-code-index.md returns url error. Is it need to be fixed?

Ah, they're all relative links. If you use the hosted version here the links should work. Thanks for pointing this out though.

The intent is for people to view the guide as a book (via that host version). Do you think we should fix the links so that they work on github too? It would be a bit of a tedious piece of work, but it's possible...

[rajcspsg]

@mark-i-m - Sure. I will try to fix 404 errors in github as well. I will wait for a day till document release and will let you know if I need any help.

[mark-i-m]

@rajcspsg It looks like there was a bug, which should (hopefully) be fixed for tomorrow.