From 2df724ffd2693092f00767786aab6d07b043d380 Mon Sep 17 00:00:00 2001 From: Andrew Gallant Date: Mon, 13 Oct 2025 09:50:59 -0400 Subject: [PATCH] docs: swap `doc_auto_cfg` with `doc_cfg` In https://github.com/rust-lang/rust/pull/138907, the `doc_auto_cfg` feature was subsumed by `doc_cfg`. This does overall look 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 stop compiling. This is overall very annoying, and I don't know how to unfuck things. So I changed the `cfg` knob to `docsrs_regex` which, doesn't quite provide a guarantee, but gets us closer to being masters of our own destiny. --- .github/workflows/ci.yml | 36 ++++++++++++++++++++++++--------- CHANGELOG.md | 11 ++++++++++ Cargo.toml | 18 +++++++++++++---- regex-automata/Cargo.toml | 23 +++++++++++++++++++++ regex-automata/src/dfa/regex.rs | 9 ++++----- regex-automata/src/lib.rs | 5 ++--- regex-syntax/Cargo.toml | 18 +++++++++++++---- regex-syntax/src/lib.rs | 4 +++- src/lib.rs | 3 +++ 9 files changed, 101 insertions(+), 26 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 12ca5191b..072ccbe7e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -55,7 +55,7 @@ jobs: rust: stable-x86_64-gnu steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Install Rust uses: dtolnay/rust-toolchain@master with: @@ -107,7 +107,7 @@ jobs: - s390x-unknown-linux-gnu steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Install and configure Cross run: | # In the past, new releases of 'cross' have broken CI. So for now, we @@ -142,7 +142,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Install Rust uses: dtolnay/rust-toolchain@master with: @@ -152,6 +152,24 @@ jobs: - name: Build docs run: cargo doc --verbose + # 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_regex" + steps: + - name: Checkout repository + uses: actions/checkout@v5 + - name: Install Rust + uses: dtolnay/rust-toolchain@master + with: + toolchain: nightly + - name: Build docs + run: cargo doc --verbose --workspace --all-features + # This job runs many more tests for the regex crate proper. Basically, # it repeats the same test suite for a bunch of different crate feature # combinations. There are so many features that exhaustive testing isn't @@ -163,7 +181,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Install Rust uses: dtolnay/rust-toolchain@master with: @@ -176,7 +194,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Install Rust uses: dtolnay/rust-toolchain@master with: @@ -189,7 +207,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Install Rust uses: dtolnay/rust-toolchain@master with: @@ -202,7 +220,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Install Rust uses: dtolnay/rust-toolchain@master with: @@ -217,7 +235,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Install Rust uses: dtolnay/rust-toolchain@master with: @@ -234,7 +252,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Install Rust uses: dtolnay/rust-toolchain@master with: diff --git a/CHANGELOG.md b/CHANGELOG.md index da14a3171..1bd16a1e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,14 @@ +1.12.2 (2025-10-13) +=================== +This release fixes a `cargo doc` breakage on nightly when `--cfg docsrs` is +enabled. This caused documentation to fail to build on docs.rs. + +Bug fixes: + +* [BUG #1305](https://github.com/rust-lang/regex/issues/1305): +Switches the `doc_auto_cfg` feature to `doc_cfg` on nightly for docs.rs builds. + + 1.12.1 (2025-10-10) =================== This release makes a bug fix in the new `regex::Captures::get_match` API diff --git a/Cargo.toml b/Cargo.toml index b7460945c..2b17e7a6c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -229,13 +229,23 @@ name = "integration" 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_regex', 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_regex" cargo +nightly doc --all-features +# +# Note that we use `docsrs_regex` 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_regex"] + +# This squashes the (AFAIK) erroneous warning that `docsrs_regex` is not a +# valid `cfg` knob. +[lints.rust] +unexpected_cfgs = { level = "allow", check-cfg = ['cfg(docsrs_regex)'] } [profile.release] debug = true diff --git a/regex-automata/Cargo.toml b/regex-automata/Cargo.toml index 53e082d89..67d603287 100644 --- a/regex-automata/Cargo.toml +++ b/regex-automata/Cargo.toml @@ -109,3 +109,26 @@ features = ["atty", "humantime", "termcolor"] [[test]] path = "tests/lib.rs" name = "integration" + +[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_regex', and when that's +# enabled, we enable the 'doc_cfg' feature. +# +# To test this locally, run: +# +# RUSTDOCFLAGS="--cfg docsrs_regex" cargo +nightly doc --all-features +# +# Note that we use `docsrs_regex` 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_regex"] + +# This squashes the (AFAIK) erroneous warning that `docsrs_regex` is not a +# valid `cfg` knob. +[lints.rust] +unexpected_cfgs = { level = "allow", check-cfg = ['cfg(docsrs_regex)'] } diff --git a/regex-automata/src/dfa/regex.rs b/regex-automata/src/dfa/regex.rs index 5e7e6e38a..892c442c8 100644 --- a/regex-automata/src/dfa/regex.rs +++ b/regex-automata/src/dfa/regex.rs @@ -70,11 +70,10 @@ define_regex_type!( /// a match. /// /// The type of the DFA used by a `Regex` corresponds to the `A` type - /// parameter, which must satisfy the [`Automaton`] trait. Typically, - /// `A` is either a [`dense::DFA`](crate::dfa::dense::DFA) or a - /// [`sparse::DFA`](crate::dfa::sparse::DFA), where dense DFAs use more - /// memory but search faster, while sparse DFAs use less memory but search - /// more slowly. + /// parameter, which must satisfy the [`Automaton`] trait. Typically, `A` + /// is either a [`dense::DFA`] or a [`sparse::DFA`], where dense DFAs use + /// more memory but search faster, while sparse DFAs use less memory but + /// search more slowly. /// /// # Crate features /// diff --git a/regex-automata/src/lib.rs b/regex-automata/src/lib.rs index 7ca03278e..b29f618a8 100644 --- a/regex-automata/src/lib.rs +++ b/regex-automata/src/lib.rs @@ -603,10 +603,9 @@ enables `alloc` and `nfa-thompson`. )] // We generally want all types to impl Debug. #![warn(missing_debug_implementations)] -// 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_regex, feature(doc_cfg))] // I have literally never tested this crate on 16-bit, so it is quite // suspicious to advertise support for it. But... the regex crate, at time diff --git a/regex-syntax/Cargo.toml b/regex-syntax/Cargo.toml index 3c4f980da..026c09c62 100644 --- a/regex-syntax/Cargo.toml +++ b/regex-syntax/Cargo.toml @@ -43,10 +43,20 @@ arbitrary = { version = "1.3.0", features = ["derive"], optional = true } 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_regex', 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_regex" cargo +nightly doc --all-features +# +# Note that we use `docsrs_regex` 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_regex"] + +# This squashes the (AFAIK) erroneous warning that `docsrs_regex` is not a +# valid `cfg` knob. +[lints.rust] +unexpected_cfgs = { level = "allow", check-cfg = ['cfg(docsrs_regex)'] } diff --git a/regex-syntax/src/lib.rs b/regex-syntax/src/lib.rs index f95f820ce..a4512e23d 100644 --- a/regex-syntax/src/lib.rs +++ b/regex-syntax/src/lib.rs @@ -168,7 +168,9 @@ The following features are available: #![forbid(unsafe_code)] #![deny(missing_docs, rustdoc::broken_intra_doc_links)] #![warn(missing_debug_implementations)] -#![cfg_attr(docsrs, feature(doc_auto_cfg))] +// 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_regex, feature(doc_cfg))] #[cfg(any(test, feature = "std"))] extern crate std; diff --git a/src/lib.rs b/src/lib.rs index 3442137eb..87e48b7e9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1319,6 +1319,9 @@ this for literal optimizations. #![no_std] #![deny(missing_docs)] #![cfg_attr(feature = "pattern", feature(pattern))] +// 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_regex, feature(doc_cfg))] #![warn(missing_debug_implementations)] #[cfg(doctest)]