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

…ng is working as expected

… setting, allowing to simplify JS code

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.

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

GuillaumeGomez added 4 commits January 14, 2026 22:08

Add new "hide deprecated items" setting in rustdoc

4ded639

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

f20e425

…ng is working as expected

Improve JS source code for settings

67db6d9

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

33bbf06

… setting, allowing to simplify JS code

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

	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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lolbinarycat left a comment •

edited by rustbot

Loading