Skip to content

Fix docs.rs build (crate-root feature(doc_cfg)) + add docs.rs CI job#100

Merged
MagicalTux merged 2 commits into
masterfrom
fix-docsrs-build
Jun 15, 2026
Merged

Fix docs.rs build (crate-root feature(doc_cfg)) + add docs.rs CI job#100
MagicalTux merged 2 commits into
masterfrom
fix-docsrs-build

Conversation

@MagicalTux

Copy link
Copy Markdown
Member

docs.rs failed to build compcol-0.6.4. Root cause + the CI gap that hid it, both fixed here.

Root cause

Modules across the crate carry #![cfg_attr(docsrs, doc(cfg(feature = "...")))] labels (so docs.rs shows which feature each item needs), but the crate root never enabled the nightly doc_cfg feature. docs.rs builds on nightly with --cfg docsrs, so every one of those labels errors:

error[E0658]: `#[doc(cfg)]` is experimental
   = help: add `#![feature(doc_cfg)]` to the crate attributes to enable

Why CI didn't catch it

Our existing docs CI job runs on stable without --cfg docsrs. Under those conditions the cfg_attr(docsrs, …) labels are inert, so the build is clean — the failure only appears in the docs.rs environment. (Notably feature(doc_cfg) was never present — git log -S confirms — so docs.rs builds had been fragile; recent nightly enforces it strictly.)

Fix

  1. src/lib.rs: add #![cfg_attr(docsrs, feature(doc_cfg))] at the crate root — the standard companion to per-module doc(cfg(...)). It's docsrs-gated, so stable builds are completely unaffected (verified).
  2. .github/workflows/ci.yml: new docsrs job that builds the docs exactly as docs.rs does — nightly + --cfg docsrs, warnings denied — so this class of failure is caught before publishing, not after.

Verification

  • Before: RUSTDOCFLAGS="--cfg docsrs -D warnings" cargo +nightly doc --all-features --no-depsE0658 (many modules).
  • After: same command → clean (Generated …/index.html, no errors/warnings).
  • Plain stable cargo doc --all-features → still clean; cargo build --all-features → unaffected.
  • The new CI job reproduces the docs.rs build and is green on this fix.

This needs a patch release (0.6.5) to unbreak docs.rs for the published crate.

🤖 Generated with Claude Code

MagicalTux and others added 2 commits June 15, 2026 23:24
The crate root lacked `#![cfg_attr(docsrs, feature(doc_cfg))]`, which the
per-module `#[cfg_attr(docsrs, doc(cfg(...)))]` labels require. docs.rs
builds on nightly with `--cfg docsrs`, so it failed with E0658 (`#[doc(cfg)]`
is experimental) — while the stable `docs` CI job (no `--cfg docsrs`, labels
inert) passed, hiding the breakage until publish.

- Add the crate-root feature gate (docsrs-only; stable builds unaffected).
- Add a `docsrs` CI job that builds the docs exactly as docs.rs does
  (nightly + `--cfg docsrs`, warnings denied) so the gap can't recur.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@MagicalTux MagicalTux merged commit 8631955 into master Jun 15, 2026
42 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant