Add new "hide deprecated items" setting in rustdoc #151091

GuillaumeGomez · 2026-01-13T23:52:23Z

This PR adds a new JS setting which allows the JS to hide deprecated items. This is especially useful for crates like std which accumulates deprecated items but never removes them.

Nicely enough, the "deprecation" information was already in the search index, meaning I didn't need to change anything there. Before this PR, it was only used to make the deprecated items rank lower. Well now it's also used to generate an extra CSS class, allowing the JS setting to work.

This is taking over #149551.

This feature got approved by the rustdoc team in the meeting of december.

You can give it a try here.

r? @lolbinarycat

rustbot · 2026-01-13T23:52:26Z

Some changes occurred in HTML/CSS/JS.

cc @lolbinarycat

GuillaumeGomez · 2026-01-14T13:55:34Z

Rebased so it includes #151053, which hopefully should fix the flakyness issue.

lolbinarycat · 2026-01-14T19:11:00Z

This made me realize that we use the word "hide" inconsistently in this settings panel, sometimes we mean "collapse, with a button to expand it again", and sometimes we mean "act like it doesn't exist at all".

I think the former should be referred to with the verb "Collapse", I think that would make things seem a bit less inconsistent.

lolbinarycat

Logic looks sound, but there's a bunch of stuff that I think could be written either more readably or more compactly, and there's a few more test cases I would like to see.

View changes since this review

lolbinarycat · 2026-01-14T19:15:03Z

src/librustdoc/html/render/mod.rs

                Either::Right(boring)
            };

+            let mut deprecation_attr = if trait_item_deprecated || item.is_deprecated(cx.tcx()) {


Suggested change

let mut deprecation_attr = if trait_item_deprecated || item.is_deprecated(cx.tcx()) {

let mut deprecation_class = if trait_item_deprecated || item.is_deprecated(cx.tcx()) {

This isn't a full attribute, only the value of the class attribute.

This also makes it clear we aren't talking about the #[deprecation] (rust) attribute, but an html attribute.

Good point, updating variable name then.

lolbinarycat · 2026-01-14T19:19:15Z

src/librustdoc/html/render/print_item.rs

 }

 fn item_module(cx: &Context<'_>, item: &clean::Item, items: &[clean::Item]) -> impl fmt::Display {
+    fn deprecation_class(is_deprecated: bool) -> &'static str {


Suggested change

fn deprecation_class(is_deprecated: bool) -> &'static str {

fn deprecation_class_attr(is_deprecated: bool) -> &'static str {

This is a full attribute.

lolbinarycat · 2026-01-14T19:22:35Z

src/librustdoc/html/render/print_item.rs


                let content = document_full(m, cx, HeadingOffset::H5).to_string();

+                let mut deprecation_attr =


Suggested change

let mut deprecation_attr =

let mut deprecation_class =

same nit as before, not a full attribute.

lolbinarycat · 2026-01-14T19:28:17Z

src/librustdoc/html/static/js/storage.js

 if (getSettingValue("source-sidebar-show") === "true") {
    addClass(document.documentElement, "src-sidebar-expanded");
 }
 if (getSettingValue("hide-sidebar") === "true") {
    addClass(document.documentElement, "hide-sidebar");
 }
 if (getSettingValue("hide-toc") === "true") {
    addClass(document.documentElement, "hide-toc");
 }
 if (getSettingValue("hide-modnav") === "true") {
    addClass(document.documentElement, "hide-modnav");
 }
 if (getSettingValue("sans-serif-fonts") === "true") {
    addClass(document.documentElement, "sans-serif");
 }
 if (getSettingValue("word-wrap-source-code") === "true") {
    addClass(document.documentElement, "word-wrap-source-code");
 }
+if (getSettingValue("hide-deprecated-items") === "true") {
+    addClass(document.documentElement, "hide-deprecated-items");
+}


This is starting to look like a lot of duplicated code that could be made more compact by just calling into changeSetting, or by taking advantage of the fact most of the class names and the settings names are the same. Is there a reason this isn't done?

No, I was thinking about it. Well, since you agree, I can simplify this code. :)

lolbinarycat · 2026-01-14T19:31:47Z

src/librustdoc/html/static/js/settings.js

+            case "hide-deprecated-items":
+                if (value === true) {
+                    addClass(document.documentElement, "hide-deprecated-items");
+                } else {
+                    removeClass(document.documentElement, "hide-deprecated-items");
+                }


I would think this could all be done much more compactly by having a single case body for all the settings that add/remove a class of the same name, no? like, addClass(document.documentElement, settingName); (and the same for removeClass) should handle the majority of settings, right?

Same as previous comment. In short: strongly agree.

lolbinarycat · 2026-01-14T19:36:40Z

tests/rustdoc-gui/src/lib2/lib.rs

+    #[deprecated(since = "1.26.0", note = "deprecated")]
+    pub struct DeprecatedStruct;
+
+    pub struct NonDeprecatedStruct;


we should have a since = "future" deprecation notice, and make sure that works correctly both in the regular module view and in rustdoc search (i'm not sure, but there's a chance future deprecations are actually treated differently between the two)

I use is_in_effect, so it won't impact the display, adding a case though.

My bad, it is impacted. ^^'

lolbinarycat · 2026-01-14T19:39:40Z

tests/rustdoc-gui/setting-hide-deprecated.goml

+// We disable the setting.
+click: "#hide-deprecated-items"
+// All of them should be displayed back.
+wait-for-css: ("details.deprecated", {"display": "block"}, ALL)


just to make sure localStorage is working, one of these times we should keep the setting checked, go to a different page, make sure all the deprecated items are hidden, uncheck it, then make sure all the deprecated items are shown.

Local storage is a bit tricky locally as it depends on the web browser whether or not the local storage is shared per-file or per-folder. So I'd rather not check that if you don't mind.

ah, right. file://// is weird. one of these days it would be nice to also have some test ran against a normal http server, so we can test stuff like localstorage.

lolbinarycat · 2026-01-14T19:41:07Z

tests/rustdoc-gui/utils.goml

        // and so do file:/// URLs, which means we need to block
        // it here if we want to avoid breaking the main docs site.
        // https://github.com/rust-lang/rust/issues/145646
        block-network-request: "file://*//*"


why is this happening here an not literally anywhere else (genuine question)?

I think it's because we try to load JS files which don't exist. As for the why, might be worth asking @notriddle and to update this comment.

lolbinarycat · 2026-01-14T19:47:08Z

@rustbot author

rustbot · 2026-01-14T21:36:04Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

GuillaumeGomez · 2026-01-16T15:28:50Z

@rustbot ready

lolbinarycat

Code looks much better (better than what I would've written, even), but I'm still not 100% satisfied with the tests.

View changes since this review

lolbinarycat · 2026-01-16T22:20:57Z

src/librustdoc/html/static/css/rustdoc.css

@@ -64,7 +64,7 @@ xmlns="http://www.w3.org/2000/svg" fill="black" height="18px">\
 		<path d="M3,5h16M3,11h16M3,17h16" stroke-width="2.75"/></svg>');
 }

-:root.sans-serif {
+:root.sans-serif-fonts {


Good job changing the class name to sans-serif-fonts instead of changing the setting name, it's an elegant solution that simplifies the code without breaking compatibility with existing localStorage.

lolbinarycat · 2026-01-16T22:27:08Z

tests/rustdoc-gui/src/lib2/lib.rs

+        #[deprecated(since = "future", note = "deprecated")]
+        /// doc
+        pub fn future_deprecated_fn() {}


Can we put #![staged_api] on this lib so this actually get interpreted as DeprecatedSince::Future, so we can actually have coverage for the use of is_in_effect? Also, I want to see what DeprecatedSince::Future does to the search results, since that attribute is handled with the existing data, and I'm not sure if that uses is_in_effect or not.

Neither future nor CURRENT_RUSTC_VERSION work:

error: 'since' must be a Rust version number, such as "1.31.0" --> lib.rs:402:9 | 402 | #[deprecated(since = "CURRENT_RUSTC_VERSION", note = "deprecated")] | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

I think staged_api prevents that. What about in a follow-up?

I had to look into the attribute parsing code (compiler/rustc_attr_parsing/src/attributes/deprecation.rs), and it looks like the magic string we actually want here is "TBD", not "future", and we shouldn't even need staged_api either. If that doesn't work, then I'd be fine putting it off to a followup.

Let me check.

Yep it works! I updated the test.

lolbinarycat · 2026-01-16T22:29:36Z

tests/rustdoc-gui/setting-hide-deprecated.goml

+// with deprecated associated items.
+go-to: "file://" + |DOC_PATH| + "/lib2/deprecated/struct.NonDeprecatedStruct.html"
+
+// There should be five deprecated items...


This comment doesn't make sense anymore.

lolbinarycat · 2026-01-16T22:29:53Z

tests/rustdoc-gui/setting-hide-deprecated.goml

+assert-count: ("details.deprecated", 6)
+// One of which being a deprecated impl because the trait itself is deprecated.
+assert-count: ("details.implementors-toggle.deprecated", 1)
+// And another has `since = "future"` and should also be impacted here.


"should also be impacted" is pretty vague.

Agreed, improved the comment.

GuillaumeGomez · 2026-01-17T16:21:52Z

Applied parts of the suggestions.

…ng is working as expected

… setting, allowing to simplify JS code

lolbinarycat · 2026-01-19T21:34:00Z

One final bit of test coverage I would like to see: when searching future_deprecated_fn with "Hide deprecated items" enabled, it should not be hidden. It's a small thing, but it would be nice to make sure the handling of items with pending deprecation has consistency across search and non-search contexts.

… value in the end, no need to keep it around. Also: takes into account "is_in_effect"

Improve the `perform-search` goml function to work when search is already open

lolbinarycat · 2026-01-19T23:17:11Z

Thanks!

@bors r+

rust-bors · 2026-01-19T23:17:13Z

📌 Commit aef8112 has been approved by lolbinarycat

It is now in the queue for this repository.

rustbot assigned lolbinarycat Jan 13, 2026

GuillaumeGomez mentioned this pull request Jan 13, 2026

Add flag to exclude deprecated items in rustdoc #149551

Closed

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the hide-deprecated-items branch 2 times, most recently from 1fe45dd to 4622f64 Compare January 14, 2026 13:54

rustbot added the A-rustdoc-js Area: Rustdoc's JS front-end label Jan 14, 2026

This comment has been minimized.

Sign in to view

lolbinarycat added the relnotes Marks issues that should be documented in the release notes of the next release. label Jan 14, 2026

rustbot mentioned this pull request Jan 14, 2026

Tracking issue for release notes of #151091: Add new "hide deprecated items" setting in rustdoc #151133

Open

lolbinarycat reviewed Jan 14, 2026

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jan 14, 2026

Add new "hide deprecated items" setting in rustdoc

4ded639

GuillaumeGomez force-pushed the hide-deprecated-items branch from 4622f64 to 33bbf06 Compare January 14, 2026 21:36

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jan 16, 2026

lolbinarycat reviewed Jan 16, 2026

View reviewed changes

GuillaumeGomez force-pushed the hide-deprecated-items branch from 33bbf06 to 893a742 Compare January 17, 2026 16:21

GuillaumeGomez added 3 commits January 19, 2026 21:37

Add rustdoc GUI test to ensure that the "hide deprecated items" setti…

9f965bc

…ng is working as expected

Improve JS source code for settings

5561167

Rename sans-serif CSS class into sans-serif-fonts to match the JS…

bf49068

… setting, allowing to simplify JS code

GuillaumeGomez force-pushed the hide-deprecated-items branch from 893a742 to bf49068 Compare January 19, 2026 20:37

GuillaumeGomez added 2 commits January 19, 2026 23:10

Simplify IndexItem::deprecation field: since we only need a boolean…

9e5e432

… value in the end, no need to keep it around. Also: takes into account "is_in_effect"

Add test for search results of not yet deprecated search items

aef8112

Improve the `perform-search` goml function to work when search is already open

rust-bors bot added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jan 19, 2026

	let mut deprecation_attr = if trait_item_deprecated \|\| item.is_deprecated(cx.tcx()) {
	let mut deprecation_class = if trait_item_deprecated \|\| item.is_deprecated(cx.tcx()) {

	fn deprecation_class(is_deprecated: bool) -> &'static str {
	fn deprecation_class_attr(is_deprecated: bool) -> &'static str {


		let content = document_full(m, cx, HeadingOffset::H5).to_string();

		let mut deprecation_attr =

Uh oh!

Add new "hide deprecated items" setting in rustdoc #151091

Are you sure you want to change the base?

Add new "hide deprecated items" setting in rustdoc #151091

Conversation

GuillaumeGomez commented Jan 13, 2026

Uh oh!

rustbot commented Jan 13, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

GuillaumeGomez commented Jan 14, 2026

Uh oh!

lolbinarycat commented Jan 14, 2026

Uh oh!

lolbinarycat left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lolbinarycat commented Jan 14, 2026

Uh oh!

rustbot commented Jan 14, 2026

Uh oh!

GuillaumeGomez commented Jan 16, 2026

Uh oh!

lolbinarycat left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lolbinarycat left a comment •

edited by rustbot

Loading

lolbinarycat left a comment •

edited by rustbot

Loading

GuillaumeGomez commented Jan 17, 2026 •

edited

Loading