# Label Feature-Gated Items on docs.rs for a Rust Library

Yes. An agent adds docs.rs metadata so every feature is built, turns on rustdoc's feature labels, checks the build on nightly in CI, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-docs-rs-metadata/rust-library/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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

- [Add release-plz to a Rust Library](https://getrush.ai/run/add-release-plz/rust-library/)
- [Add cargo-semver-checks to a Rust Library's CI](https://getrush.ai/run/add-semver-checks/rust-library/)
- [Write Property-Based Tests for a Rust Library](https://getrush.ai/run/write-property-tests/rust-library/)

## More jobs like this: Hand off a long task

- [Run Sphinx Doctests in CI for a Python Library](https://getrush.ai/run/add-doctest-to-ci/sphinx/)
- [Add Draft Posts to a Gatsby Blog](https://getrush.ai/run/add-draft-posts/gatsby/)
- [Add Draft Posts to a VitePress Blog](https://getrush.ai/run/add-draft-posts/vitepress/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
