Add flag to exclude deprecated items in rustdoc #149551

Saphereye · 2025-12-02T16:55:49Z

This PR introduces a flag that hides all deprecated items when generating docs.

For example, given the following code:

#![allow(unused)]
pub struct Visible;

#[deprecated(since = "1.2.3", note = "use Visible instead")]
pub struct OldType;

pub mod m {
    #[deprecated]
    pub fn old_fn() {}
    pub fn new_fn() {}
}

#[deprecated]
pub fn legacy_api() {}

pub fn modern_api() {}

And on generating the docs:

Original	After Edits
	but the symbols still exists, so its still searchable

Edits:

changed behavior from removing symbols to just hiding them

rustbot · 2025-12-02T16:55:54Z

r? @GuillaumeGomez

rustbot has assigned @GuillaumeGomez.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

GuillaumeGomez · 2025-12-03T10:51:05Z

Instead of not generating items, I think adding a setting to hide them would be better.

Saphereye · 2025-12-06T06:53:05Z

Added a flag to hide unstable items (based on feedback in the parent issue). I also tried adding a corresponding option in the settings panel, but ran into two issues:

Not all elements can be reliably identified as unstable or deprecated via existing tags, so they still appear in places like the sidebar. I experimented with injecting extra metadata into the generated nodes, but it felt hacky and would require adding the metadata to many places. In the future if we were to add more hiding flags this would bloat the docs(?)
I couldn’t make the settings option persist and apply responsively across pages. Enabling it on one page wouldn’t carry over to the next, and elements only refreshed to the hidden state after reopening the settings panel.

I will check this out more but will keep the flags for now.

GuillaumeGomez · 2025-12-08T11:26:43Z

Instead of not generating items, I think adding a setting to hide them would be better.

I meant in the JS settings, not at doc generation time.

GuillaumeGomez · 2025-12-11T10:53:45Z

We talked about this feature in last rustdoc team meeting and it was unanimously accepted by the members present at the time. However, we'd like the implementation to be like #141299. Could you update your PR please?

rustbot · 2025-12-11T19:22:12Z

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @lolbinarycat

rust-log-analyzer · 2025-12-11T19:33:09Z

The job tidy failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

[TIMING:end] tool::Tidy { compiler: Compiler { stage: 0, host: x86_64-unknown-linux-gnu, forced_compiler: false }, target: x86_64-unknown-linux-gnu } -- 0.000
fmt check
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:117:
 
 impl<'a> Link<'a> {
     pub fn new(href: impl Into<Cow<'a, str>>, name: impl Into<Cow<'a, str>>) -> Self {
-        Self { href: href.into(), name: name.into(), children: vec![], name_html: None, deprecated: false }
+        Self {
+            href: href.into(),
+            name: name.into(),
+            children: vec![],
+            name_html: None,
+            deprecated: false,
+        }
     }
     pub fn empty() -> Link<'static> {
         Link::new("", "")
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:465:
                         // Inject non-visual marker for deprecated filtering in sidebar entries
                         // by appending a hidden span to the displayed name.
                         // Note: we rely on `Link::new` to accept enriched HTML for the name.
-                        Link::new(l.href.clone(), format!("{}<span class=\"depr-item\" hidden></span>", l.name))
+                        Link::new(
+                            l.href.clone(),
+                            format!("{}<span class=\"depr-item\" hidden></span>", l.name),
+                        )
                     })
                     .collect(),
             ),
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:475:
                 assoc_types
                     .into_iter()
                     .map(|l| {
-                        Link::new(l.href.clone(), format!("{}<span class=\"depr-item\" hidden></span>", l.name))
+                        Link::new(
+                            l.href.clone(),
+                            format!("{}<span class=\"depr-item\" hidden></span>", l.name),
+                        )
                     })
                     .collect(),
             ),
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:485:
                 methods
                     .into_iter()
                     .map(|l| {
-                        Link::new(l.href.clone(), format!("{}<span class=\"depr-item\" hidden></span>", l.name))
+                        Link::new(
+                            l.href.clone(),
+                            format!("{}<span class=\"depr-item\" hidden></span>", l.name),
+                        )
                     })
                     .collect(),
             ),
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:708:
                 let mut l = Link::new(format!("struct.{name_str}"), name_str.to_string());
                 if it.deprecation(cx.tcx()).is_some_and(|d| d.is_in_effect()) {
                     l.deprecated = true;
-                    l.name_html = Some(format!(
-                        "{} <span class=\"stab deprecated\">Deprecated</span>",
-                        name_str
-                    ).into());
+                    l.name_html = Some(
+                        format!("{} <span class=\"stab deprecated\">Deprecated</span>", name_str)
+                            .into(),
+                    );
                 }
                 structs.push(l);
             }
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:719:
                 let mut l = Link::new(format!("fn.{name_str}"), name_str.to_string());
                 if it.deprecation(cx.tcx()).is_some_and(|d| d.is_in_effect()) {
                     l.deprecated = true;
-                    l.name_html = Some(format!(
-                        "{} <span class=\"stab deprecated\">Deprecated</span>",
-                        name_str
-                    ).into());
+                    l.name_html = Some(
+                        format!("{} <span class=\"stab deprecated\">Deprecated</span>", name_str)
+                            .into(),
+                    );
                 }
                 functions.push(l);
             }
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:730:
                 let mut l = Link::new(format!("enum.{name_str}"), name_str.to_string());
                 if it.deprecation(cx.tcx()).is_some_and(|d| d.is_in_effect()) {
                     l.deprecated = true;
-                    l.name_html = Some(format!(
-                        "{} <span class=\"stab deprecated\">Deprecated</span>",
-                        name_str
-                    ).into());
+                    l.name_html = Some(
+                        format!("{} <span class=\"stab deprecated\">Deprecated</span>", name_str)
+                            .into(),
+                    );
                 }
                 enums.push(l);
             }
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:741:
                 let mut l = Link::new(format!("type.{name_str}"), name_str.to_string());
                 if it.deprecation(cx.tcx()).is_some_and(|d| d.is_in_effect()) {
                     l.deprecated = true;
-                    l.name_html = Some(format!(
-                        "{} <span class=\"stab deprecated\">Deprecated</span>",
-                        name_str
-                    ).into());
+                    l.name_html = Some(
+                        format!("{} <span class=\"stab deprecated\">Deprecated</span>", name_str)
+                            .into(),
+                    );
                 }
                 type_aliases.push(l);
             }
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:752:
                 let mut l = Link::new(format!("constant.{name_str}"), name_str.to_string());
                 if it.deprecation(cx.tcx()).is_some_and(|d| d.is_in_effect()) {
                     l.deprecated = true;
-                    l.name_html = Some(format!(
-                        "{} <span class=\"stab deprecated\">Deprecated</span>",
-                        name_str
-                    ).into());
+                    l.name_html = Some(
+                        format!("{} <span class=\"stab deprecated\">Deprecated</span>", name_str)
+                            .into(),
+                    );
                 }
                 constants.push(l);
             }
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:763:
                 let mut l = Link::new(format!("mod.{name_str}"), name_str.to_string());
                 if it.deprecation(cx.tcx()).is_some_and(|d| d.is_in_effect()) {
                     l.deprecated = true;
-                    l.name_html = Some(format!(
-                        "{} <span class=\"stab deprecated\">Deprecated</span>",
-                        name_str
-                    ).into());
+                    l.name_html = Some(
+                        format!("{} <span class=\"stab deprecated\">Deprecated</span>", name_str)
+                            .into(),
+                    );
                 }
                 modules.push(l);
             }
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:896:
                         get_next_url(used_links, format!("{typ}.{name}", typ = ItemType::Method)),
                         name.as_str(),
                     );
-                    if item
-                        .deprecation(tcx)
-                        .is_some_and(|d| d.is_in_effect())
-                    {
+                    if item.deprecation(tcx).is_some_and(|d| d.is_in_effect()) {
                         // Mark as deprecated for template-based class insertion
                         link.deprecated = true;
                         // Also render the native deprecation tag in the link label
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:906:
-                        link.name_html = Some(format!(
-                            "{} <span class=\"stab deprecated\">Deprecated</span>",
-                            name
-                        ).into());
+                        link.name_html = Some(
+                            format!("{} <span class=\"stab deprecated\">Deprecated</span>", name)
+                                .into(),
+                        );
                     }
                     Some(link)
                 }
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:930:
             {
                 {
                     let mut link = Link::new(
-                        get_next_url(used_links, format!("{typ}.{name}", typ = ItemType::AssocConst)),
+                        get_next_url(
+                            used_links,
+                            format!("{typ}.{name}", typ = ItemType::AssocConst),
+                        ),
                         name.as_str(),
                     );
-                    if item
-                        .deprecation(tcx)
-                        .is_some_and(|d| d.is_in_effect())
-                    {
+                    if item.deprecation(tcx).is_some_and(|d| d.is_in_effect()) {
                         // Mark for template-based class insertion
                         link.deprecated = true;
                         // Also render the native deprecation tag in the link label
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:943:
-                        link.name_html = Some(format!(
-                            "{} <span class=\"stab deprecated\">Deprecated</span>",
-                            name
-                        ).into());
+                        link.name_html = Some(
+                            format!("{} <span class=\"stab deprecated\">Deprecated</span>", name)
+                                .into(),
+                        );
                     }
                     Some(link)
                 }
Diff in /checkout/src/librustdoc/html/render/sidebar.rs:969:
                     get_next_url(used_links, format!("{typ}.{name}", typ = ItemType::AssocType)),
                     name.as_str(),
                 );
-                if item
-                    .deprecation(tcx)
-                    .is_some_and(|d| d.is_in_effect())
-                {
+                if item.deprecation(tcx).is_some_and(|d| d.is_in_effect()) {
                     link.deprecated = true;
-                    link.name_html = Some(format!(
-                        "{} <span class=\"stab deprecated\">Deprecated</span>",
-                        name
-                    ).into());
+                    link.name_html = Some(
+                        format!("{} <span class=\"stab deprecated\">Deprecated</span>", name)
+                            .into(),
+                    );
                 }
                 Some(link)
             } else {

GuillaumeGomez · 2025-12-12T12:50:24Z

src/librustdoc/html/render/sidebar.rs

+                        // Inject non-visual marker for deprecated filtering in sidebar entries
+                        // by appending a hidden span to the displayed name.
+                        // Note: we rely on `Link::new` to accept enriched HTML for the name.
+                        Link::new(l.href.clone(), format!("{}<span class=\"depr-item\" hidden></span>", l.name))


Why adding a hidden attribute?

Also might be better to use deprecated instead of depr-item.

GuillaumeGomez · 2025-12-12T12:50:34Z

src/librustdoc/html/render/sidebar.rs

+                assoc_types
+                    .into_iter()
+                    .map(|l| {
+                        Link::new(l.href.clone(), format!("{}<span class=\"depr-item\" hidden></span>", l.name))


Same question.

GuillaumeGomez · 2025-12-12T12:50:39Z

src/librustdoc/html/render/sidebar.rs

+                methods
+                    .into_iter()
+                    .map(|l| {
+                        Link::new(l.href.clone(), format!("{}<span class=\"depr-item\" hidden></span>", l.name))


Same question.

GuillaumeGomez · 2025-12-12T12:54:01Z

src/librustdoc/html/templates/sidebar.html

                                        <ul>
                                            {% for child in link.children %}
-                                                <li><a href="#{{child.href|safe}}" title="{{child.name}}">
+                                                <li{% if (block.heading.name == "Structs" || block.heading.name == "Functions") && child.deprecated +%} class="depr-item"{% endif %}><a href="#{{child.href|safe}}" title="{{child.name}}">


I think the only interested check in here should be if child.deprecated.

GuillaumeGomez · 2025-12-12T12:54:26Z

src/librustdoc/html/templates/sidebar.html

                        <ul class="block{% if !block.class.is_empty() +%} {{+block.class}}{% endif %}">
                            {% for link in block.links %}
-                                <li> {# #}
+                                <li{% if (block.heading.name == "Structs" || block.heading.name == "Functions") && link.deprecated +%} class="depr-item"{% endif %}> {# #}


I think the only interested check in here should be if child.deprecated.

GuillaumeGomez · 2025-12-12T12:54:54Z

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

+if (hideDepr === "true") {
+    addClass(document.documentElement, "hide-depr");
+} else {
+    removeClass(document.documentElement, "hide-depr");


You don't need this else clause.

GuillaumeGomez · 2025-12-12T12:56:47Z

src/librustdoc/html/static/js/main.js

 window.currentCrate = getVar("current-crate");

+// Tag deprecated entries in the current page and sidebar, and expose an updater
+function rustdocTagDeprecated() {


All of these changes are unnecessary. If you have the document class set to hide deprecated items, then a rule in the CSS should hide all of them, there is no need to modify the existing HTML.

GuillaumeGomez · 2025-12-12T12:57:19Z

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

 }

 /* General structure and fonts */
+.hide-depr dt:has(.stab.deprecated),


Please use hide-deprecated instead of hide-depr.

GuillaumeGomez · 2025-12-12T12:57:46Z

src/librustdoc/html/render/sidebar.rs

+                    .is_some_and(|d| d.is_in_effect())
+                {
+                    link.deprecated = true;
+                    link.name_html = Some(format!(


Not sure to understand why we need this new name_html field.

GuillaumeGomez · 2025-12-12T12:58:10Z

src/librustdoc/html/render/sidebar.rs

        .collect();

-    sidebar_module_like(item_sections_in_use, ids, module_like)
+    let mut blocks = vec![sidebar_module_like(item_sections_in_use, ids, module_like)];


Why changing all this code?

init

cbf0e3b

rustbot assigned GuillaumeGomez Dec 2, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Dec 2, 2025