doc: switch from doc_auto_cfg to doc_cfg

In rust-lang/rust#138907, the `doc_auto_cfg`
feature was subsumed by `doc_cfg`. This does overall looks like we're on
a path toward stabilization, which is great.

One problem here though is that a bunch of crates use the `cfg`
`docsrs` to enable `doc_auto_cfg`. So if we enable it, then it causes
those crates to emit hard errors. This is overall very annoying, and
I don't know how to unfuck things. So I changed the `cfg` knob to
`docsrs_jiff` which, doesn't quite provide a guarantee, but gets us
closer to being masters of our own destiny.

See also a similar change made to `regex`:
rust-lang/regex#1305

Author: BurntSushi

.github/workflows/ci.yml

@@ -549,6 +549,24 @@ jobs:
         cd crates/jiff-wasm
         wasm-pack test --node
 
+  # This job checks the docsrs configuration.
+  #
+  # This is important because we enable `doc_cfg`, which is an unstable
+  # feature that can (and has) broken.
+  docsrs:
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: "-D rustdoc::broken_intra_doc_links --cfg docsrs_jiff"
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+    - name: Install Rust
+      uses: dtolnay/rust-toolchain@master
+      with:
+        toolchain: nightly
+    - name: Build docs
+      run: cargo doc --verbose --workspace --all-features
+
   # Check that all files are formatted properly.
   rustfmt:
     runs-on: ubuntu-latest

Cargo.toml

@@ -274,10 +274,20 @@ debug-assertions = false
 all-features = true
 # Since this crate's feature setup is pretty complicated, it is worth opting
 # into a nightly unstable option to show the features that need to be enabled
-# for public API items. To do that, we set 'docsrs', and when that's enabled,
-# we enable the 'doc_auto_cfg' feature.
+# for public API items. To do that, we set `docsrs_jiff`, and when that's
+# enabled, we enable the 'doc_cfg' feature.
 #
 # To test this locally, run:
 #
-#     RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features
-rustdoc-args = ["--cfg", "docsrs"]
+#     RUSTDOCFLAGS="--cfg docsrs_jiff" cargo +nightly doc --all-features
+#
+# Note that we use `docsrs_jiff` instead of the more standard `docsrs` because
+# other crates use that same `cfg` knob. And since we are enabling a nightly
+# feature, they sometimes break. By using our "own" `cfg` knob, we are closer
+# to being masters of our own destiny.
+rustdoc-args = ["--cfg", "docsrs_jiff"]
+
+# This squashes the (AFAIK) erroneous warning that `docsrs_jiff` is not a
+# valid `cfg` knob.
+[lints.rust]
+unexpected_cfgs = { level = "allow", check-cfg = ['cfg(docsrs_jiff)'] }

crates/jiff-icu/Cargo.toml

@@ -42,3 +42,26 @@ icu_time = { version = "2.0.0", optional = true, default-features = false }
 [dev-dependencies]
 jiff = { version = "0.2.11", path = "../..", default-features = true }
 icu = { version = "2.0.0" }
+
+[package.metadata.docs.rs]
+# We want to document all features.
+all-features = true
+# Since this crate's feature setup is pretty complicated, it is worth opting
+# into a nightly unstable option to show the features that need to be enabled
+# for public API items. To do that, we set `docsrs_jiff`, and when that's
+# enabled, we enable the 'doc_cfg' feature.
+#
+# To test this locally, run:
+#
+#     RUSTDOCFLAGS="--cfg docsrs_jiff" cargo +nightly doc --all-features
+#
+# Note that we use `docsrs_jiff` instead of the more standard `docsrs` because
+# other crates use that same `cfg` knob. And since we are enabling a nightly
+# feature, they sometimes break. By using our "own" `cfg` knob, we are closer
+# to being masters of our own destiny.
+rustdoc-args = ["--cfg", "docsrs_jiff"]
+
+# This squashes the (AFAIK) erroneous warning that `docsrs_jiff` is not a
+# valid `cfg` knob.
+[lints.rust]
+unexpected_cfgs = { level = "allow", check-cfg = ['cfg(docsrs_jiff)'] }

crates/jiff-icu/src/lib.rs

@@ -152,6 +152,9 @@ assert_eq!(zdt.to_string(), "2025-02-02T17:30:00-05:00[America/New_York]");
 
 #![no_std]
 #![deny(missing_docs)]
+// This adds Cargo feature annotations to items in the rustdoc output. Which is
+// sadly hugely beneficial for this crate due to the number of features.
+#![cfg_attr(docsrs_jiff, feature(doc_cfg))]
 
 #[cfg(any(test, feature = "std"))]
 extern crate std;

src/lib.rs

@@ -720,10 +720,9 @@ For more, see the [`fmt::serde`] sub-module. (This requires enabling Jiff's
     )),
     allow(dead_code, unused_imports)
 )]
-// No clue why this thing is still unstable because it's pretty amazing. This
-// adds Cargo feature annotations to items in the rustdoc output. Which is
+// This adds Cargo feature annotations to items in the rustdoc output. Which is
 // sadly hugely beneficial for this crate due to the number of features.
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![cfg_attr(docsrs_jiff, feature(doc_cfg))]
 // We generally want all types to impl Debug.
 #![warn(missing_debug_implementations)]
 // Document ALL THE THINGS!