Change:
Right now, the docs produced on the stable and beta channels include unstable items. The docs are already fairly complex and contain a lot of information to sort through, and finding documentation for items that are not usable for the majority of developers working on stable Rust does not help with this. In addition, unstable APIs have very attention-grabbing warnings associated with them, making them much more prominent than the APIs that are actually usable. <img width="1031" alt="Screen shot demonstrating eye-catching unstable warning" src="https://user-"This has been broken out of to provide smaller, actionable items that can be independently discussed and worked on. A review of rustdoc for accessibility, especially for dyslexia and attention disorders, finds that there are a number of visually distracting elements in rustdoc which can draw attention away from the main content. This should be considered along with the other issues mentioned in about the overall effect of a number of distracting elements on the page. This has been previously discussed and closed in and . However, when it was first discussed was very shortly after the Rust 1.0 release, when there was a large amount of API surface which had not been stabilized for the 1.0 release, and what could be done with stable Rust was fairly limited (for example, no stable proc macros so Serde was only usable on nightly Rust). At this point, most people can use stable Rust for most tasks. There is a lot less reason for the average Rust developer to need to switch to nightly to use unstable standard library features. There is also the open issue that the stable docs of unstable items may be out of date; because these items are unstable, they can change in nightly releases, so not only are they a distraction, but they may be misleading for people who actually try to use them. Between the extra information that most people don't need, distracting UI, potential for being out of date, and time since this was last discussed, I think that it is worth reconsidering this decision and hiding unstable items in the stable docs by default. This would require either providing an opt-in setting for seeing them, or make finding the nightly docs easier. An alternative discussed in the comments is to just make them less visually prominent; unstable items are already rendered at lower contrast and at the bottom on module index pages, but within struct or trait documentation they have big bright warning boxes calling attention to them. Making them less visually prominent, such as by reducing their contrast and making the warning just plain unstyled text, perhaps in the same place that stability information goes (though see for discussion on that), would help out a lot.
I would prefer this option. One benefit of showing the unstable APIs is that it invites people to test them, so having an opt-in for the curious would be good.
I would prefer an opt-out to an opt-in, that is, keep what we do today, but provide the ability to hide it if desired.
After spending some more time browsing the docs with an eye out for things that are visually distracting or attention grabbing, another option would be to just use a less attention grabbing way to denote unstable and deprecated items. Right now, they each use an extra, brightly colored box that makes them take up more visual space on the screen than stable items. On module index pages, they are actually made less prominent; they are sorted to the bottom, and made lower contrast with the background. This helps make them less attention catching, rather than more attention catching. But when browsing the methods provided on a struct or trait, they come with the big bright warning boxes that make them stand out more. I think I would still have a slight preference for having them hidden by default and just making the nightly docs easier to discover, such as having a version chooser in the header or sidebar, because of the issue mentioned in about docs of unstable items potentially being out of date. But making them less visually prominent rather than more visually prominent would help a lot.
I agree that the better way to solve this is by (perhaps) reducing the prominence of the "nightly-only" box. I don't think we should hide unstable items in the stable rustdoc generated at If someone is reading code that uses an unstable method, there's a good chance they will go to look it up in the stable docs. It would be a frustrating and confusing experience to not be able to find the method in the docs. It's a much better experience to find the method and be informed it's nightly-only / unstable. We probably don't want to reduce the prominence too much, though. If someone's looking for a method to call, it's pretty important that they notice when it's nightly-only. If they're working on a stable crate, that may mean they're not able to use the method at all.
Candidate PR at

Discussion:
// Render unstable items. But don't render "rustc_private" crates (internal compiler crates). // Those crates are permanently unstable so it makes no sense to render "unstable" everywhere. <del> if let Some((StabilityLevel::Unstable { reason, issue, .. }, feature)) = item </del> <ins> if let Some((StabilityLevel::Unstable { reason: _, issue, .. }, feature)) = item </ins> .stability(cx.tcx()) .as_ref() .filter(|stab| stab.feature != sym::rustc_private)

message.push_str(&format!(" ({})", feature)); <del> if let Some(unstable_reason) = reason { let mut ids = cx.id_map.borrow_mut(); message = format!( "<details><summary>{}</summary>{}</details>", message, MarkdownHtml( &unstable_reason.as_str(), &mut ids, error_codes, cx.shared.edition(), &cx.shared.playground, ) .into_string() ); } </del> extra_info.push(format!("<div class="stab unstable">{}</div>", message)); }

display: table; } .stab { <del> border-width: 1px; border-style: solid; </del> padding: 3px; margin-bottom: 5px; font-size: 90%;

} .stab .emoji { <del> font-size: 1.5em; </del> <ins> font-size: 1.2em; </ins> } /* Black one-pixel outline around emoji shapes */

size: (1100, 800) // We check that ".item-info" is bigger than its content. assert-css: (".item-info", {"width": "807px"}) <del> assert-css: (".item-info .stab", {"width": "343px"}) </del> <ins> assert-css: (".item-info .stab", {"width": "341px"}) </ins>

#![feature(staged_api)] #![doc(issue_tracker_base_url = "https://issue_url/")] <del> #![unstable(feature="test", issue = "32374")] </del> <ins> #![unstable(feature = "test", issue = "32374")] </ins> // @matches issue_32374/index.html '//*[@class="item-left unstable deprecated module-item"]/span[@class="stab deprecated"]'  //      'Deprecated'

//      '👎 Deprecated since 1.0.0: deprecated' // @has issue_32374/struct.U.html '//*[@class="stab unstable"]'  //      '🔬 This is a nightly-only experimental API. (test #32374)' <del> // @has issue_32374/struct.U.html '//details'  //      '🔬 This is a nightly-only experimental API. (test #32374)' // @has issue_32374/struct.U.html '//summary'  //      '🔬 This is a nightly-only experimental API. (test #32374)' // @has issue_32374/struct.U.html '//details/p'  //      'unstable' </del> #[rustc_deprecated(since = "1.0.0", reason = "deprecated")] #[unstable(feature = "test", issue = "32374", reason = "unstable")] pub struct U;