Improve stability of rustdoc

[Diggsey]

Recently there have been a lot of issues introduced with rustdoc.

Reported issues:

• Poor UX: Stop hiding type declarations in docs #49764
• Flickering: Documentation is flickering on light theme #49648

Additional issues:

• Docs are now incredibly slow to load
• Search bar is bugged (cannot type 's' into the search bar!)
• Anchor links broken to collapsed sections
• Search showing duplicate results
• Some items are shown in search results that don't exist on the page it links to

It makes me really sad that the documentation is now so much worse to use than it used to be.

If this is because development of rustdoc can't keep up with changes to the compiler internals, then there's not really anything that can be done here, but from an outside perspective it seems like many of these issues stem from new features being added to rustdoc, many of which have... questionable value, and are not sufficiently tested.

The problem is made worse because https://docs.rs/ uses the nightly compiler to build its documentation. I don't want to see this change because a lot of crates are nightly-only, or have nightly-specific features that it is important to document, but the net result is that the canonical documentation for many rust crates is now almost unusable, especially on slow internet connections.

[GuillaumeGomez]

Bugs are generally fixed in the next days they're reported. However, if they hit beta release, then it'll take 12 weeks to be fixed in stable. For docs.rs, we work with the current maintainer and he makes release when he thinks they're worth enough an internal release.

[Xaeroxe]

Search bar is bugged (cannot type 's' into the search bar!)

This is infuriating, I'd like to get this fixed ASAP. Are there any other relevant issues or PRs I can chime in on or help with? This is the only issue I was able to find that mentioned this.

[GuillaumeGomez]

@Xaeroxe: It's been fixed weeks ago. Refer to my previous message for more details.

[varkor]

Would it plausible to separate the UI from the content/generation/rustc integration, so that UI bug fixes or tweaks could be made available much sooner?

[GuillaumeGomez]

It could but it needs to be discussed. Generally they get backported. This case is an exception since no one found out the bug before a few versions passed (which is strange).

[QuietMisdreavus]

To me this issue seems like it doesn't have a concrete suggestion to make? At best it's an aggregation of other issues that were reported elsewhere. If you have issues to report, report them separately, so that we can tackle them one-by-one.

As for the thrust of the OP, rustdoc doesn't have the same "stability" concerns that the compiler does; we add features as we see fit and change the display just as often. In fact, when we were discussing the --extend-css option, it was explicitly said that we don't have a guarantee for the exact HTML of the output. To provide a stability story for rustdoc, we'll need to define what that actually means.

[kzys]

I agree with @QuietMisdreavus. This issue is not actionable.

Regarding regressions, Rustdoc will have Puppeteer-based tests (#53319) that would allow us to make sure that all features (incl. JavaScript) are working, while we need to write tests first though.

[Mark-Simulacrum]

Closing per the above, as this is not actionable. We do our best :)