feat: Add instability_disable_unstable_docs RUSTFLAGS (#23)

Setting instability_disable_unstable_docs to true in your
RUSTFLAGs now disables generating docs unless unstable
feature flag is enabled. This makes it possible to use tools like
cargo-semver-checks against the doucmentation, without
having unstable docs muddy the checks.

To use:

```shell
RUSTFLAGS=instability_disable_unstable_docs cargo build
```

Author: bjoernQ

.github/workflows/test.yml

@@ -41,6 +41,10 @@ jobs:
         run: cargo generate-lockfile
       - name: cargo test --locked
         run: cargo test --locked --all-features --all-targets
+      - name: cargo test with instability_exclude_unstable_docs
+        env:
+          RUSTFLAGS: --cfg instability_disable_unstable_docs
+        run: cargo test --locked --all-features --all-targets
       - name: cargo test --doc
         run: cargo test --locked --all-features --doc
   minimal-versions:
@@ -80,6 +84,10 @@ jobs:
         run: cargo +nightly update -Zdirect-minimal-versions
       - name: cargo test
         run: cargo test --locked --all-features --all-targets
+      - name: cargo test with instability_exclude_unstable_docs
+        env:
+          RUSTFLAGS: --cfg instability_disable_unstable_docs
+        run: cargo test --locked --all-features --all-targets
       - name: Cache Cargo dependencies
         uses: Swatinem/rust-cache@v2
   os-check:
@@ -100,6 +108,10 @@ jobs:
         run: cargo generate-lockfile
       - name: cargo test
         run: cargo test --locked --all-features --all-targets
+      - name: cargo test with instability_exclude_unstable_docs
+        env:
+          RUSTFLAGS: --cfg instability_disable_unstable_docs
+        run: cargo test --locked --all-features --all-targets
       - name: Cache Cargo dependencies
         uses: Swatinem/rust-cache@v2
   coverage:

build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    println!("cargo:rustc-check-cfg=cfg(instability_disable_unstable_docs)");
+}

src/lib.rs

@@ -66,6 +66,19 @@ mod unstable;
 /// - `issue`: a link or reference to a tracking issue for the unstable feature. This will be
 ///   included in the item's documentation.
 ///
+/// # Disabling during documentation generation
+///
+/// By default, this macro will include the unstable item when generating documentation by gating
+/// using a composite configuration flag that includes `docs`. In some cases, this may not be
+/// desirable, such as when checking docs with `cargo-semver-checks`. You can disable this by adding
+/// the `instability_disable_unstable_docs` RUSTFLAGS configuration flag to your build script. E.g.:
+///
+/// ```shell
+/// RUSTFLAGS="--cfg instability_disable_unstable_docs" cargo build
+/// ```
+///
+/// This will not prevent the item from being compiled when the unstable feature flag is enabled.
+///
 /// # Examples
 ///
 /// We can apply the attribute to a public function like so:

src/unstable.rs

@@ -64,12 +64,24 @@ impl UnstableAttribute {
             .into_iter()
             .map(|ident| quote! { #[allow(#ident)] });
 
+        #[cfg(not(instability_disable_unstable_docs))]
+        let (cfg_gate_unstable, cfg_gate_stable) = (
+            quote! { #[cfg(any(doc, feature = #feature_flag))] },
+            quote! { #[cfg(not(any(doc, feature = #feature_flag)))] },
+        );
+
+        #[cfg(instability_disable_unstable_docs)]
+        let (cfg_gate_unstable, cfg_gate_stable) = (
+            quote! { #[cfg(feature = #feature_flag)] },
+            quote! { #[cfg(not(feature = #feature_flag))] },
+        );
+
         quote! {
-            #[cfg(any(doc, feature = #feature_flag))]
+            #cfg_gate_unstable
             #[cfg_attr(docsrs, doc(cfg(feature = #feature_flag)))]
             #item
 
-            #[cfg(not(any(doc, feature = #feature_flag)))]
+            #cfg_gate_stable
             #(#allows)*
             #hidden_item
         }
@@ -78,8 +90,15 @@ impl UnstableAttribute {
     pub fn expand_impl(&self, mut item: impl Stability + ToTokens) -> TokenStream {
         let feature_flag = self.feature_flag();
         self.add_doc(&mut item);
+
+        #[cfg(not(instability_disable_unstable_docs))]
+        let cfg_gate_unstable = quote! { #[cfg(any(doc, feature = #feature_flag))] };
+
+        #[cfg(instability_disable_unstable_docs)]
+        let cfg_gate_unstable = quote! { #[cfg(feature = #feature_flag)] };
+
         quote! {
-            #[cfg(any(doc, feature = #feature_flag))]
+            #cfg_gate_unstable
             #[cfg_attr(docsrs, doc(cfg(feature = #feature_flag)))]
             #item
         }
@@ -107,7 +126,8 @@ impl UnstableAttribute {
             .map_or(String::from("unstable"), |name| format!("unstable-{name}"))
     }
 }
-#[cfg(test)]
+
+#[cfg(all(test, not(instability_disable_unstable_docs)))]
 mod tests {
     use pretty_assertions::assert_eq;
     use quote::quote;
@@ -410,3 +430,54 @@ mod tests {
         assert_eq!(tokens.to_string(), expected.to_string());
     }
 }
+
+#[cfg(all(test, instability_disable_unstable_docs))]
+mod tests {
+    use pretty_assertions::assert_eq;
+    use quote::quote;
+    use syn::parse_quote;
+
+    use super::*;
+
+    const DEFAULT_DOC: &str = "# Stability\n\n**This API is marked as unstable** and is only available when the `unstable`\ncrate feature is enabled. This comes with no stability guarantees, and could be changed\nor removed at any time.";
+
+    #[test]
+    fn expand_public_fn() {
+        let item: syn::ItemFn = parse_quote! {
+            pub fn foo() {}
+        };
+        let tokens = UnstableAttribute::default().expand(item);
+        let expected = quote! {
+            #[cfg(feature = "unstable")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
+            #[doc = #DEFAULT_DOC]
+            pub fn foo() {}
+
+            #[cfg(not(feature = "unstable"))]
+            #[allow(dead_code)]
+            #[doc = #DEFAULT_DOC]
+            pub(crate) fn foo() {}
+        };
+        assert_eq!(tokens.to_string(), expected.to_string());
+    }
+
+    #[test]
+    fn expand_public_use() {
+        let item: syn::ItemUse = parse_quote! {
+            pub use crate::foo::bar;
+        };
+        let tokens = UnstableAttribute::default().expand(item);
+        let expected = quote! {
+            #[cfg(feature = "unstable")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
+            #[doc = #DEFAULT_DOC]
+            pub use crate::foo::bar;
+
+            #[cfg(not(feature = "unstable"))]
+            #[allow(unused_imports)]
+            #[doc = #DEFAULT_DOC]
+            pub(crate) use crate::foo::bar;
+        };
+        assert_eq!(tokens.to_string(), expected.to_string());
+    }
+}