From b4cdb0f615db849df1ffc61de230595c7806166e Mon Sep 17 00:00:00 2001
From: Eduard-Mihai Burtescu <eddyb@lyken.rs>
Date: Fri, 14 Jul 2023 15:05:09 +0300
Subject: [PATCH] spirv-builder: try getting the `docs.rs` doc build to succeed
 (by making `rustc_codegen_spirv` optional).

---
 .github/workflows/ci.yaml       |  4 ++++
 crates/spirv-builder/Cargo.toml | 29 +++++++++++++++++++++--------
 crates/spirv-builder/src/lib.rs | 25 +++++++++++++++++++++++++
 3 files changed, 50 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 11148a5eba..189aa16832 100644
--- a/.github/workflows/ci.yaml
+++ b/.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
 
diff --git a/crates/spirv-builder/Cargo.toml b/crates/spirv-builder/Cargo.toml
index b40aa59fe7..87afb668c7 100644
--- a/crates/spirv-builder/Cargo.toml
+++ b/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"]
+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 = ["notify"]
+
+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"] }
diff --git a/crates/spirv-builder/src/lib.rs b/crates/spirv-builder/src/lib.rs
index b38579fff8..b926dc6285 100644
--- a/crates/spirv-builder/src/lib.rs
+++ b/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;