rustdoc: deterministic sorting for doc_cfg badges

[shivendra02467]

Fixes #156391

Currently, target-exclusive doc_cfg badges (eg. "Available on...") reuse the order of predicates as they appear in the source code. This often buries popular targets behind niche ones and leads to inconsistent UI rendering.

This PR introduces a deterministic sorting mechanism to the Cfg AST prior to HTML/JSON rendering.

Note for Reviewers:
To provide the best UX, I implemented a lightweight tiering heuristic (prioritizing major platforms like Linux/Apple/Windows first, followed by mobile, then BSDs, and alphabetizing the rest). However, I am completely open to tweaking these priority groupings or falling back to a different sorting logic if the team prefers. Let me know what you think!

[rustbot]

r? @fmease

rustbot has assigned @fmease.
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

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: rustdoc
• rustdoc expanded to 9 candidates
• Random selection from GuillaumeGomez, fmease, lolbinarycat, notriddle

[rustbot]

Some changes occurred in GUI tests.

cc @GuillaumeGomez

[GuillaumeGomez]

Sorting the doc_cfg badges sounds like a good idea, but I'm not sure sorting by "importance" is a good idea. I think we should sort by target then by feature and internally alphabetically.

As for not()/all()/any(), not too sure...

[GuillaumeGomez]

Also, would be nice to have a unit test with different scenarios directly in cfg.rs.

[shivendra02467]

Sorting the doc_cfg badges sounds like a good idea, but I'm not sure sorting by "importance" is a good idea. I think we should sort by target then by feature and internally alphabetically.

@GuillaumeGomez Thanks for the review! That makes complete sense.

I've just pushed a commit that drops the importance heuristic and replaces it with the logic you suggested.

Updates:

1. Sorting Order: It now categorizes by Targets (0) -> Target Features (1) -> Crate Features (2). Within those categories, it falls back to case-insensitive alphabetical sorting.
2. Unit Tests: Added test_sort_for_rendering in cfg/tests.rs to assert this exact categorization and alphabetical fallback, and moved the HTML regression test into the doc-cfg/ directory.

As for not()/all()/any(), not too sure...

I completely agree these are tricky! Here is how this commit handles them:

• It recursively sorts their internal contents using the exact same target -> feature -> alphabetical rules.
• It places the any/all/not blocks themselves into a final Category (3). This effectively pushes complex, nested groupings to the end of the badge list, keeping the simple, single-item targets and features grouped neatly at the front (e.g., it will render unix and (linux or windows) rather than (linux or windows) and unix).

Does pushing the complex nested blocks to the end seem like the best UX call to you, or would you prefer them sorted differently?

[GuillaumeGomez]

Does pushing the complex nested blocks to the end seem like the best UX call to you, or would you prefer them sorted differently?

Sounds like the right way to handle them indeed. Good call!

[shivendra02467]

Sounds like the right way to handle them indeed. Good call!

@GuillaumeGomez Thanks! Is there any other change needed before we can merge this?

@rustbot ready

[GuillaumeGomez]

Sorry, I didn't realize that the changes were already pushed. Looks all good to me, thanks!

@bors r+ rollup

[rust-bors]

📌 Commit 7cbc028 has been approved by GuillaumeGomez

It is now in the queue for this repository.

[GuillaumeGomez]

Failed in #157020 (comment).

@bors r-

[rust-bors]

This pull request was unapproved.

This PR was contained in a rollup (#157020), which was unapproved.

View changes since this unapproval

[GuillaumeGomez]

cfg() and doc(cfg()) should work the same, so not sure your last commit is fixing the CI issue. However: please add the same test for both kind of attributes so we're sure they're handled the same.

[shivendra02467]

cfg() and doc(cfg()) should work the same, so not sure your last commit is fixing the CI issue. However: please add the same test for both kind of attributes so we're sure they're handled the same.

You are absolutely right that their badges should look and behave identically!
Just to clarify the CI failure: the Windows runner failed previously because #[cfg(target_os = "linux")] caused the Rust compiler to actively strip fn foo() out of the AST before rustdoc could even see it, resulting in a 'File does not exist' test error. Switching it to #[doc(cfg(...))] made the attribute inert for conditional compilation, allowing the file to generate and the badge sorting to be tested across all CI platforms.
However, I completely agree we need to guarantee the sorting AST hits both paths! I have just pushed an update to tests/rustdoc-html/doc-cfg/sort.rs. I included #![doc(auto_cfg)] (noting that doc_auto_cfg was recently merged into doc_cfg) and added a second test specifically for standard #[cfg(...)]. I used custom feature flags passed via compile-flags for that second test so it will successfully compile and test the badge sorting on all CI runners without being stripped.
Let me know if everything looks good!

[GuillaumeGomez]

You can remove this line.

View changes since the review