What the agent does
The agent clones the repository into its own cloud sandbox and reads how the crate exposes its features. In a library like rust-itertools/itertools, Cargo.toml declares use_std and use_alloc, with use_std on by default and implying use_alloc, a rust-version of 1.63.0, and no [package.metadata.docs.rs] table. src/lib.rs starts with #![cfg_attr(not(feature = "use_std"), no_std)], documents both features in prose under a Crate Features heading, and gates items on them throughout: extern crate alloc and every allocating adaptor sit behind use_alloc, and the hash-based methods such as unique and counts behind use_std, well over a hundred cfg(feature = ...) attributes across src/. On docs.rs a reader of Itertools sees every method with nothing to say which feature it needs, and CONTRIBUTING.md tells contributors to gate new methods the same way, so the list keeps growing.
It makes two small changes that docs.rs and rustdoc read. Cargo.toml gains [package.metadata.docs.rs] with all-features = true, so the published documentation includes the use_std items rather than whatever the default set happens to be, and rustdoc-args = ["--cfg", "docsrs"], which docs.rs passes to rustdoc. src/lib.rs gains #![cfg_attr(docsrs, feature(doc_cfg))] as its first attribute, so that only under that cfg the unstable doc_cfg feature is enabled; with it on, rustdoc's automatic cfg display adds a label to each item saying which crate feature it is available on, read from the existing #[cfg(feature = "use_alloc")] and #[cfg(feature = "use_std")] attributes. No item needs a second attribute, and a stable toolchain, including the 1.63.0 the msrv job uses, sees the cfg_attr as false and compiles the crate exactly as before.
The CI change is one job. .github/workflows/ci.yml already has a doc job running cargo doc --all-features on stable with warnings denied; the agent adds a docsrs job on nightly that runs the same command with RUSTDOCFLAGS="--cfg docsrs -Dwarnings" and --no-deps, which is the build docs.rs will do, and lists it in the needs of all-jobs-succeed so branch protection sees it. The check matrix, which already clippies the crate with no features, with use_alloc alone and with everything, is untouched: the new attribute is inert there.
Before opening anything it runs both documentation builds in its sandbox. On stable, cargo doc --all-features with warnings denied must still pass. On nightly with the new flags, it builds the docs and searches the generated target/doc/itertools/ HTML for the availability labels, counting how many items now carry a feature note and reading a handful, such as join under use_alloc and unique under use_std, to confirm the label matches the gate. That count and those examples go into the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Make docs.rs build this Rust library with all features and label every feature-gated item. Read Cargo.toml, src/lib.rs, CONTRIBUTING.md and .github/workflows/ci.yml first, list the crate features and how many items are gated on each, and confirm there is no docs.rs metadata today. Add a package.metadata.docs.rs table with all-features and a docsrs rustdoc cfg, and a crate-level cfg_attr that enables the doc_cfg feature only under that cfg so stable builds, including the MSRV check, are unchanged. Do not add per-item doc attributes. Add a nightly docs job to the workflow that builds with the docsrs cfg and warnings denied and wire it into the job branch protection depends on. In your sandbox run the stable doc build the workflow already runs, then the nightly build with the new flags, count the feature labels in the generated HTML and check a few against their cfg gates, and open a pull request that lists the files changed, the count, and the command output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request touching Cargo.toml, src/lib.rs and .github/workflows/ci.yml. The description explains the two mechanisms, docs.rs reading the metadata table and rustdoc reading the docsrs cfg, names a few methods with the label they will show, and gives the count of labelled items from the nightly build.
The run's record holds the stable cargo doc output, the nightly build with the docsrs cfg, and the grep over the generated HTML, so a reviewer can see the labels exist without building the docs locally or waiting for the next docs.rs build.
Before merging, a reviewer confirms the nightly job is acceptable in a crate that otherwise tests on stable only, and decides whether the prose feature list in the crate docs should stay as the overview or be trimmed now that each item is labelled.
Run it on every new crate repository
An organisation that publishes several crates starts one run per repository. A handler on its own server receives GitHub's organisation webhook for a new repository, checks it has a Cargo.toml with a [features] table, and sends this request with the repository's URL in resources. Each run reads the crate it is given, so a crate with no feature gates gets a pull request that adds only the metadata table and says why the label attribute would be inert.
Every run lands in its own sandbox and opens its own pull request. The key that starts it reports each finished run to its webhook_url, so the handler can note the result beside the repository.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
This is a three-line change that is hard to verify by eye: it only does anything under a cfg that stable never sets, on a build that happens on docs.rs after publishing. The agent installs nightly in its sandbox, runs the exact build docs.rs will run, and reads the generated HTML, so the pull request arrives with the labels counted rather than promised.
The same request runs against every crate an organisation maintains, each in its own sandbox with its own feature list read first, and each pull request keeps the command record. A maintainer reads the three-file diff and the count together and spends their time on the one question of whether a nightly job belongs in their CI.
Frequently asked questions
Does this change what stable users compile?
No. The cfg_attr only enables doc_cfg when docsrs is set, which happens on docs.rs and in the new nightly job. A stable build, including the 1.63.0 the MSRV job uses, sees a false cfg and compiles the crate as before.
Why not add doc(cfg) attributes to each item?
With doc_cfg enabled, rustdoc's automatic cfg display reads the existing #[cfg(feature = ...)] gates and labels items itself, so a per-item attribute would duplicate what is already there and be one more thing contributors must remember. The one crate-level line covers every current and future gate.
Why build with all features on docs.rs?
Without all-features, docs.rs builds the default set, and a method gated on a non-default feature is simply absent from the published documentation. With it, every item is present and the label says which feature a reader needs.
Why add a nightly job to a stable-only CI?
Because the attribute only takes effect on nightly, a stable cargo doc cannot show it is correct. The job runs the same command docs.rs runs, with warnings denied, so a broken doc comment under the cfg fails the pull request rather than the next docs.rs build.
More Rust library jobs
More jobs like this: Hand off a long task
- Run Sphinx Doctests in CI for a Python Library (Sphinx)
- Add Draft Posts to a Gatsby Blog (Gatsby)
- Add Draft Posts to a VitePress Blog (VitePress)