spirv-builder: try to get docs to build on docs.rs, and improve them slightly.

.github/workflows/ci.yaml

@@ -149,6 +149,10 @@ jobs:
         run: rustfmt --check tests/ui/**/*.rs
       - name: Check docs are valid
         run: RUSTDOCFLAGS=-Dwarnings cargo doc --no-deps
+      - name: Check docs for `spirv-std` and `spirv-builder` on stable (for docs.rs)
+        run: |
+          RUSTDOCFLAGS=-Dwarnings cargo +stable doc --no-deps -p spirv-std
+          RUSTDOCFLAGS=-Dwarnings cargo +stable doc --no-deps -p spirv-builder --no-default-features
       - name: Clippy & custom lints
         run: .github/workflows/lint.sh
 

crates/rustc_codegen_spirv/build.rs

@@ -8,7 +8,7 @@ use std::process::{Command, ExitCode};
 /// Current `rust-toolchain.toml` file
 /// Unfortunately, directly including the actual workspace `rust-toolchain.toml` doesn't work together with
 /// `cargo publish`. We need to figure out a way to do this properly, but let's hardcode it for now :/
-//const REQUIRED_RUST_TOOLCHAIN: &str = include_str!("../../rust-toolchain");
+//const REQUIRED_RUST_TOOLCHAIN: &str = include_str!("../../rust-toolchain.toml");
 const REQUIRED_RUST_TOOLCHAIN: &str = r#"[toolchain]
 channel = "nightly-2023-05-27"
 components = ["rust-src", "rustc-dev", "llvm-tools-preview"]
@@ -65,7 +65,7 @@ fn check_toolchain_version() -> Result<(), Box<dyn Error>> {
 
             return Err(Box::<dyn Error>::from(format!(
                 r#"error: wrong toolchain detected (found commit hash `{current_hash}`, expected `{required_hash}`).
-Make sure your `rust-toolchain` file contains the following:
+Make sure your `rust-toolchain.toml` file contains the following:
 -------------
 {stripped_toolchain}
 -------------"#

crates/spirv-builder/Cargo.toml

@@ -1,26 +1,39 @@
 [package]
 name = "spirv-builder"
 description = "Helper for building shaders with rust-gpu"
-# Documentation currently fails on docs.rs, but it doesn't have to. See https://github.com/EmbarkStudios/rust-gpu/issues/970
-documentation = "https://embarkstudios.github.io/rust-gpu/api/spirv_builder/index.html"
 version.workspace = true
 authors.workspace = true
 edition.workspace = true
 license.workspace = true
 repository.workspace = true
 
-# See rustc_codegen_spirv/Cargo.toml for details on these features
+# HACK(eddyb) allow `docs.rs` to build this crate by making `rustc_codegen_spirv`
+# dependency optional in a way that will always result in it being enabled
+# during normal builds (as `use-{installed,compiled}-tools` both require it),
+# and produces a compile-time error if it's missing and `cfg(doc)` isn't set.
+[package.metadata.docs.rs]
+no-default-features = true
+
+# NOTE(eddyb) the `dep:` prefixes used here prevents a feature with the name as
+# that optional dependency, from being automatically created by Cargo, see:
+# https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies
 [features]
+# See `rustc_codegen_spirv/Cargo.toml` for details on these features.
 default = ["use-compiled-tools"]
-use-installed-tools = ["rustc_codegen_spirv/use-installed-tools"]
-use-compiled-tools = ["rustc_codegen_spirv/use-compiled-tools"]
-skip-toolchain-check = ["rustc_codegen_spirv/skip-toolchain-check"]
-watch = ["notify"]
+use-installed-tools = ["dep:rustc_codegen_spirv", "rustc_codegen_spirv?/use-installed-tools"]
+use-compiled-tools = ["dep:rustc_codegen_spirv", "rustc_codegen_spirv?/use-compiled-tools"]
+skip-toolchain-check = ["rustc_codegen_spirv?/skip-toolchain-check"]
+
+watch = ["dep:notify"]
 
 [dependencies]
-rustc_codegen_spirv-types.workspace = true
-# See comment in lib.rs invoke_rustc for why this is here
+# See comment in `src/lib.rs` `invoke_rustc` regarding `rustc_codegen_spirv` dep.
 rustc_codegen_spirv.workspace = true
+# HACK(eddyb) see `docs.rs`-related comment above for why this is optional.
+rustc_codegen_spirv.optional = true
+
+rustc_codegen_spirv-types.workspace = true
+
 memchr = "2.4"
 raw-string = "0.3.5"
 serde = { version = "1.0", features = ["derive"] }

crates/spirv-builder/README.md

@@ -29,23 +29,26 @@ const SHADER: &[u8] = include_bytes!(env!("my_shaders.spv"));
 
 ## Building with `spirv-builder`
 
-Because of its nature, `rustc_codegen_spirv`, and therefore `spirv-builder` by extension, require the use of a very specific nightly toolchain of Rust.
+As `spirv-builder` relies on `rustc_codegen_spirv` being built for it (by Cargo, as a direct dependency), and due to the special nature of the latter (as a `rustc` codegen backend "plugin"), both end up sharing the requirement for a very specific nightly toolchain version of Rust.
 
-**The current toolchain is: `nightly-2023-05-27`.**
+**The current Rust toolchain version is: `nightly-2023-05-27`.**
 
-Toolchains for previous versions of `spirv-builder`:
+Rust toolchain version history across [rust-gpu releases](https://github.com/EmbarkStudios/rust-gpu/releases) (since `0.4`):
 
-|Version|Toolchain|
-|-:|-|
-|`0.8.0`|`nightly-2023-04-15`|
-|`0.7.0`|`nightly-2023-03-04`|
-|`0.6.*`|`nightly-2023-01-21`|
-|`0.5.0`|`nightly-2022-12-18`|
-|`0.4.0`|`nightly-2022-10-29`|
-|`0.4.0-alpha.16` - `0.4.0-alpha.17`|`nightly-2022-10-01`|
-|`0.4.0-alpha.15`|`nightly-2022-08-29`|
-|`0.4.0-alpha.13` - `0.4.0-alpha.14`|`nightly-2022-04-11`|
+|`spirv-builder`<br>version|Rust toolchain<br>version|
+|:-:|:-:|
+|`0.8`|`nightly-2023-04-15`|
+|`0.7`|`nightly-2023-03-04`|
+|`0.6`|`nightly-2023-01-21`|
+|`0.5`|`nightly-2022-12-18`|
+|`0.4`|`nightly-2022-10-29`|
 
-The nightly toolchain has to match *exactly*. Starting with `0.4.0-alpha.15`, the commit hash of your local toolchain is checked and you'll get a build error when building `rustc_codegen_spirv` with the wrong toolchain. If you want to experiment with different versions, this check can be omitted by defining the environment variable `RUSTGPU_SKIP_TOOLCHAIN_CHECK`<sup>since `0.4.0-alpha.16`</sup>. Keep in mind that, as `rustc_codegen_spirv` is heavily dependent on `rustc`'s internal API, diverging too much from the required toolchain will quickly result in compile errors.
+<sup>*As patch versions must be semver-compatible, they will always require the  
+same toolchain (for example, `0.6.0` and `0.6.1` both use `nightly-2023-01-21`).*</sup>
+
+Only that *exact* Rust nightly toolchain version is **supported**. Since `0.4`, the commit hash of your current Rust toolchain is checked and you'll get a build error when building `rustc_codegen_spirv` with the wrong toolchain.  
+Notably, the error will also show what the `rust-toolchain.toml` file *should* contain (to get the expected toolchain), which you can rely on when updating to a new release.
+
+If you want to experiment with _different, **unsupported**_, Rust toolchain versions, this check can be omitted by defining the environment variable `RUSTGPU_SKIP_TOOLCHAIN_CHECK`. Keep in mind that, as `rustc_codegen_spirv` is *heavily* dependent on `rustc`'s internal APIs, diverging too much from the supported toolchain version will quickly result in compile errors (or worse, e.g. spurious errors and/or incorrect behavior, when compiling shaders with it).
 
 [rustgpu]: https://github.com/EmbarkStudios/rust-gpu/

crates/spirv-builder/src/lib.rs

@@ -71,6 +71,31 @@
 // #![allow()]
 #![doc = include_str!("../README.md")]
 
+// HACK(eddyb) try to catch misuse of Cargo package features very early on
+// (see `spirv-builder/Cargo.toml` for why we go through all of this).
+#[cfg(all(
+    not(any(feature = "use-compiled-tools", feature = "use-installed-tools")),
+    not(doc)
+))]
+compile_error!(
+    "at least one of `use-compiled-tools` or `use-installed-tools` features must be enabled
+(outside of documentation builds, which require disabling both to build on stable)"
+);
+
+#[cfg(doc)]
+fn _ensure_cfg_doc_means_rustdoc() {
+    // HACK(eddyb) this relies on specific `rustdoc` behavior (i.e. it skips
+    // type-checking function bodies, so we trigger a compile-time `panic! from
+    // a type) to check that we're in fact under `rustdoc`, not just `--cfg doc`.
+    #[rustfmt::skip]
+    let _: [(); panic!("
+
+            `--cfg doc` was set outside of `rustdoc`
+            (if you are running `rustdoc` or `cargo doc`, please file an issue)
+
+")];
+}
+
 mod depfile;
 #[cfg(feature = "watch")]
 mod watch;

crates/spirv-std/README.md

@@ -4,10 +4,6 @@ Core functions, traits, and more that make up a “standard library” for SPIR-
 
 This crate gives a `rust-gpu` shader access to the required `#![spirv(..)]` attribute, as well as povide all kinds of APIs that allows a shader to access GPU resources such as textures and buffers. Optionally, through the use of the `"glam"` feature, it includes some boilerplate trait implementations to make `glam` vector types compatible with these APIs.
 
-## 🚨 BREAKING 🚨
-
-As of `0.4.0-alpha.16`, your shaders will require a different preamble. See [this migration guide][migration] for more information.
-
 ## Example
 
 ![Sky shader](https://github.com/EmbarkStudios/rust-gpu/raw/b12a2f3f6a54bc841d05a9224bc577909d519228/docs/assets/sky.jpg)