Pick themes on settings page, not every page

[jsha]

This hides the paintbrush icon on most pages by default, in preference for the settings on the settings page. When loading from a local file, and not in mobile view, continue to show the theme picker. That's because some browsers limit access to localStorage from file:/// URLs, so choosing a theme from settings.html doesn't take effect.

Fixes #84539
Part of #59840

r? @GuillaumeGomez

Demo: https://rustdoc.crud.net/jsha/theme-picker-local-only-2/std/io/trait.Read.html

[rust-highfive]

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez,@Folyd

[GuillaumeGomez]

It's not appearing on the settings page either:

Also, on the settings page I would not put it alongside the sidebar but above all other parameters so it has more space. What do you think?

[jsha]

My thought was that people would use the "preferred dark theme" / "preferred light theme". But we also need something on the settings page for when "Use system theme" is off. I'll work on that.

[jsha]

Ok, updated the settings page too.

[notriddle]

and I discussed via PM on Zulip, and came to a compromise solution: We'll show the theme picker icon only when visiting a file:/// URL. That way we get a nice uncluttered UI on doc.rust-lang.org and docs.rs, but we don't lose the theme-picking functionality on local files.

Showing the paintbrush icon on file URLs, while not showing it on http URLs, is definitely a compromise, but it doesn't sound like a very good idea.

• You're making the theming functionality more prominent in exactly the situations where it's less useful. This is the opposite of good design: since the functionality is broken, rustdoc should hide it.
• The code for rendering that drop down menu is getting served to people who won't actually be running it, on the WWW, the situation where avoiding bloat is the most important.
• If someone looks at the docs on their local machine, and sees that button, then uploads the docs to a web server and the button goes away, they're going to think it's a bug. Self-served docs aren't exceptionally common, but bigger projects like gtk and rocket, as well as many proprietary software shops, do self-host their own rustdocs.

[GuillaumeGomez]

"preferred theme" seems weirdly worded to me. Also, when changing its value, it doesn't change the current theme.

@notriddle: Interestingly enough, you have the exact opposite logic that we used. When on a website, you only need to change it once to get it applied correctly on all the pages whereas it's not the case for local docs (hence why we keep it there).

The code for rendering that drop down menu is getting served to people who won't actually be running it, on the WWW, the situation where avoiding bloat is the most important.

I'm not sure to see how much of an issue it is. Could you elaborate a bit more?

If someone looks at the docs on their local machine, and sees that button, then uploads the docs to a web server and the button goes away, they're going to think it's a bug. Self-served docs aren't exceptionally common, but bigger projects like gtk and rocket, as well as many proprietary software shops, do self-host their own rustdocs.

I agree that it's not the best. The idea is to reduce the number of buttons we have because they're distracting (@jsha received complains about it iirc) when it's not really necessary (because again, on a website you only need to change it once).

An alternative would be for the settings to be 100% JS and therefore to have access to it on all pages, allowing us to remove tje theme button on all pages. But that bring other issues.

[notriddle]

When on a website, you only need to change it once to get it applied correctly on all the pages whereas it's not the case for local docs (hence why we keep it there).

If the theme gets “randomly” reverted when you switch pages, is the functionality really useful? Blinding white flashes in dark mode can be pretty uncomfortable.

Personally, I stopped setting rustdoc themes, exactly because it doesn’t really work.

I'm not sure to see how much of an issue it is. Could you elaborate a bit more?

Since the image is only hidden by CSS, the SVG file still gets downloaded. There’s also quite a bit of CSS and JavaScript used to implement that control, since it’s currently the only JavaScript-based drop-down in all of rustdoc. If it was removed, all that code could go away, or be migrated to settings.js and not get loaded by default.

[bors]

☔ The latest upstream changes (presumably #92526) made this pull request unmergeable. Please resolve the merge conflicts.

[GuillaumeGomez]

The display of the setting of the theme selection is still not great. Do you have an idea on how improve it? (If you have ideas for the whole setting page, go ahead! :D )

[jsha]

The display of the setting of the theme selection is still not great. Do you have an idea on how improve it? (If you have ideas for the whole setting page, go ahead! :D )

I have some ideas about improving the design of the settings page in general, but I don't think they should block progress on this issue. The goal of the settings change in this PR is to make sure the settings page has the same features as the paintbrush, so we can remove the paintbrush in most cases. The design is the same as it is on https://doc.rust-lang.org/nightly/settings.html.

[GuillaumeGomez]

As discussed on zulip, since settings are only useful for users with JS enabled, I'll move the settings into full JS. Thanks @jsha!

@bors: r+ rollup

[bors]

📌 Commit 04f0402 has been approved by GuillaumeGomez