Updated docs to use mdbook

[UebelAndre]

This updates docs to be built using mdbook for improved readability and search-ability. Note that the raw markdown from stardoc is still committed to the repo and can be easily viewed at any commit to ensure users are able to get the correct docs for their current version of rules_rust.

[UebelAndre]

@scentini in order for this change to work an admin of the repo will need to update the following settings

[krasimirgg]

I can try doing the update. Which settings need to be updated and to what values?

[UebelAndre]

I can try doing the update. Which settings need to be updated and to what values?

Pages needs to be deployed from a branch and set to the gh-pages branch (which will appear after this change is merged). I followed https://github.com/rust-lang/mdBook/wiki/Automated-Deployment%3A-GitHub-Actions which describes a workflow for building the book and committing the html to a detached branch.

[UebelAndre]

@krasimirgg do you have the ability to retry specific jobs? There seems to be issues with the remote cache and I'm having no success running the entire suite over and over again praying for all green.

[krasimirgg]

Triggered retries.

[UebelAndre]

Triggered retries.

Thanks! But still seeing things like

(16:45:27) ERROR: /Users/buildkite/builds/bk-macos-pln3-xtd8/bazel/rules-rust-rustlang/test/unit/rustdoc/BUILD.bazel:3:19: Generating Rustdoc test runner for @//test/unit/rustdoc:rustdoc_proc_macro failed: Failed to fetch blobs because they do not exist remotely.: Missing digest: c9b2362b46e6dd30b5e01de814f2ce85ebecaf2637e7e35d2cde54513ac9e8a0/481368 for bazel-out/darwin_x86_64-fastbuild/bin/test/unit/rustdoc/librustdoc_proc_macro-2600278351.dylib

😞

[krasimirgg]

Wild guess: this mentions rustdoc and proc_macros, could it be that it's the same thing that #1952 addresses?

[UebelAndre]

Wild guess: this mentions rustdoc and proc_macros, could it be that it's the same thing that #1952 addresses?

I figured not due to Failed to fetch blobs because they do not exist remotely.: Missing digest: This sounds like a Bazel complaint and not a Rustdoc complaint.

[krasimirgg]

@tjgq : we're seeing Failed to fetch blobs because they do not exist remotely.: Missing digest: c9b2362b46e6dd30b5e01de814f2ce85ebecaf2637e7e35d2cde54513ac9e8a0/481368 errors recently on rules_rust : https://buildkite.com/bazel/rules-rust-rustlang/builds/11955#0191c2a1-aba8-4e61-8a84-85ab2ef5bf92/276-306
Looks suspiciously like an infrastructure issue?

[tjgq]

This can happen if remote cache entries are evicted while the build is in progress (any cache entry found during the build is assumed to remain available for the remainder of the build). You can try setting --experimental_remote_cache_eviction_retries which attempts to recover from evictions by automatically retrying the build. For an HTTP cache (which seems to be what you're using here?), it won't completely solve the problem, though. That's bazelbuild/bazel#18696.

[UebelAndre]

This can happen if remote cache entries are evicted while the build is in progress (any cache entry found during the build is assumed to remain available for the remainder of the build). You can try setting --experimental_remote_cache_eviction_retries which attempts to recover from evictions by automatically retrying the build. For an HTTP cache (which seems to be what you're using here?), it won't completely solve the problem, though. That's bazelbuild/bazel#18696.

Is there a way you can purge the cache?

[tjgq]

This can happen if remote cache entries are evicted while the build is in progress (any cache entry found during the build is assumed to remain available for the remainder of the build). You can try setting --experimental_remote_cache_eviction_retries which attempts to recover from evictions by automatically retrying the build. For an HTTP cache (which seems to be what you're using here?), it won't completely solve the problem, though. That's bazelbuild/bazel#18696.

Is there a way you can purge the cache?

Not from Bazel, but for a GCS bucket you should be able to do it through the Google Cloud UI.

[UebelAndre]

Not from Bazel, but for a GCS bucket you should be able to do it through the Google Cloud UI.

I'm not a Googler so I'd have to defer to you or @krasimirgg for your access there.

[tjgq]

Not from Bazel, but for a GCS bucket you should be able to do it through the Google Cloud UI.

I'm not a Googler so I'd have to defer to you or @krasimirgg for your access there.

Sorry, I didn't realize this was in the bazelbuild org 🤦 let me see what I can do about it (and also investigate whether we could replace the HTTP cache with RBE to solve it permanently).

[tjgq]

Not from Bazel, but for a GCS bucket you should be able to do it through the Google Cloud UI.

I'm not a Googler so I'd have to defer to you or @krasimirgg for your access there.

Sorry, I didn't realize this was in the bazelbuild org 🤦 let me see what I can do about it (and also investigate whether we could replace the HTTP cache with RBE to solve it permanently).

There are $REASONS why we can't switch to an RBE cache at the moment. For now, we've cleared the HTTP cache. Can you push a change to trigger a new run?

[UebelAndre]

@krasimirgg can you update the repo settings?

[krasimirgg]

done

[krasimirgg]

et voila! https://bazelbuild.github.io/rules_rust/index.html
Not sure if https://bazelbuild.github.io/rules_rust/ should be made to redirect to that. Initially I was confused at that landing page.

[hlopko]

Drive by - the docs look fantastic, thank you for working on it!