Track rustc-guide

[nikomatsakis]

rustc-guide has a number of links into the nightly docs. We have a "linkcheck" that checks that these links are valid (right @mark-i-m?). I would like it if we were notified when people do refactorings that break those links, so we can go and update the rustc-guide appropriately.

[mark-i-m]

We have a "linkcheck" that checks that these links are valid (right @mark-i-m?).

Yes, that is correct.

[mark-i-m]

This would be really useful. There have already been a couple of cases where refactorings/renamings in the code were only fixed because of conscientious contributors. Automating this would be great!

[kennytm]

Linkcheck isn't tracked by toolstate. If you add rustc-guide as a submodule in rust-lang/rust's src/doc then linkchecker will check it (and also block the PR unfortunately). Note that it can only recognize relative links.

[mark-i-m]

Note that it can only recognize relative links.

I'm pretty sure that mdbook-linkcheck does absolute links as well. Is that not the tool being used?

If you add rustc-guide as a submodule in rust-lang/rust's src/doc then linkchecker will check it (and also block the PR unfortunately).

Is there any way to get toolstate to check it?

@nikomatsakis Any thoughts about making rustc-guide a submodule or moving it to the rust repo altogether? Personally, I think submodules might be a viable option, but we would need to keep making PRs to update the submodule version... I would like to avoid outright moving the book to the rust repo because that would mean having to run the entire compiler CI sweet on PRs, which seems ... er... unpleasant...

[kennytm]

@mark-i-m No we have our own linkchecker... perhaps you could replace it with the mdbook one 🙃

If you could define an ./x.py test something action then toolstate can check it.

[mark-i-m]

Hmm... I'm currently a bit swamped, but this could be a good beginner issue... Perhaps we should advertise on twir?

[mark-i-m]

@kennytm @nikomatsakis Would the following be an acceptable course of action?

1. Make rustc-guide a submodule of rust-lang/rust
2. Add a dependency in rust-lang/rust on mdbook and mdbook-linkcheck (maybe replace our linkchecker with that one?)
3. Add a ./x.py test src/doc/rustc-guide build target, which is not run by default during a normal CI build
4. Make rust-toolstate check that mdbook build passes successfully.

If this sounds reasonable, I think we could make it a quest issue and advertise it on This Week in Rust. Thoughts?

[kennytm]

SGTM, but step 4 should be executed inside ./x.py (perhaps as part of ./x.py test src/doc/rustc-guide) to store the toolstates.

For mdbook-linkcheck to replace our own linkchecker it needs to be able to work with the libstd docs... Can mdbook-linkcheck work with that? (Our own linkchecker just parses the generated HTML.)

[mark-i-m]

Can mdbook-linkcheck work with that? (Our own linkchecker just parses the generated HTML.)

Perhaps @Michael-F-Bryan has thoughts about this?

[Michael-F-Bryan]

For mdbook-linkcheck to replace our own linkchecker it needs to be able to work with the libstd docs... Can mdbook-linkcheck work with that?

Are you talking about the file layout where you'll have the docs for std in a directory next to the rustc-guide? For example, the rustc-guide book might be in /docs/rustc-guide and then to link to /docs/std/index.html you'd write the link as ../std/index.html. If that's the case, I think mdbook-linkcheck would be suitable.

I added a flag (disabled by default) which will allow relative links to go outside of the book root and then check that the file exists. I haven't used it much in the past though, so we may need to tweak the link resolution logic.

Our own linkchecker just parses the generated HTML

mdbook-linkcheck works slightly differently. It's a mdbook plugin, so it'll receive a parsed "book" (tree structure containing strings with the contents of your original files) and then use pulldown-cmark to scan for any links. These then get fed into a validator which will check each link goes to either a valid chapter or file that exists on disk (for relative links), or a web page that returns a HTTP code in the 200's.

[kennytm]

Well I was replying to "(maybe replace our linkchecker with that one?)". Since mdbook-linkcheck is an mdbook plugin, we'll need to keep our own for link-checking the rustdoc-generated pages.

So, we'd use mdbook-linkcheck for rustc-guide and also all the books, and use src/tools/linkchecker for the libstd doc.

[mark-i-m]

Hmm... that seems feasible. Shall I create a tracking issue on rust-lang/rust or here?

[ehuss]

rustc-guide is now being tracked in toolstate, so I think this can be closed.