rustdoc: Please provide way to set the default theme

[ijackson]

When I view rustdoc-generated documents via file:// urls on my own system, the (I think cookie-based) mechanism for saving my doc theme preference does not work.

Can we please have a command-line option or config file setting or something, to change the default theme? (I guess it might be possible to do this with --extend-css but that seems complicated and probably fragile too.)

I imagine implementing this would not be too hard even for someone unfamiliar with the rustdoc code, so I would be happy to do an MR if you like. I guess the right way would be a --default-theme command line option?

[jyn514]

-Z unstable-theme seems reasonable (or -Z unstable-options --default-theme). @Cldfire might have suggestions for how to implement it.

[Mark-Simulacrum]

Are we sure that there's nothing we can do that'll work for file:// URLs? I guess most things are probably tied to the domain, but maybe something that's global to file:/// exists? I'm not personally familiar with browser APIs that would allow this though.

[jyn514]

Are we sure that there's nothing we can do that'll work for file:// URLs? I guess most things are probably tied to the domain, but maybe something that's global to file:/// exists? I'm not personally familiar with browser APIs that would allow this though.

rust-lang/rustup#2151 (comment)

[ijackson]

Mark Rousskov writes ("Re: [rust-lang/rust] rustdoc: Please provide way to set the default theme (#77024)"):

Are we sure that there's nothing we can do that'll work for file:// URLs?

You mean to save the preferences ? Maybe. I'm not sure of the browser APIs myself. However it seems to me that it should be up to the person who is building documents for local use, what the default theme is (for a user who hasn't specified a personal default). After all, maybe the documentation builder wants to change the default for a local userbase. We shouldn't ask them to maintain a patched version of rustdoc. or go messing with additional CSS, to do something so simple. Thanks, Ian.

…

-- Ian Jackson <ijackson@chiark.greenend.org.uk> These opinions are my own. Pronouns: they/he. If I emailed you from @fyvzl.net or @evade.org.uk, that is a private address which bypasses my fierce spamfilter.

[workingjubilee]

The current solution uses localStorage, which is designed to work in a "per-website" fashion but persist across sessions. However, there are several special-cases around file:// addresses in general for security reasons. I agree that a local filesystem concern should probably not be handled with Web APIs, and offering a compilation option that strips out the JS that handles localStorage and then includes a specific css theme should be implementable, and would probably be the simplest approach.

[Cldfire]

@ijackson:

However it seems to me that it should be up to the person who is
building documents for local use, what the default theme is (for a
user who hasn't specified a personal default).

I agree, and we can absolutely do this. See https://github.com/rust-lang/rust/blob/master/src/librustdoc/html/static/storage.js#L126-L128; the call to switchTheme defaults to light if no saved setting or system preference is found. It would be trivial to swap that out for a harcoded theme name based on a CLI arg (or even just change the default from light to something else).

@workingjubilee:

offering a compilation option that strips out the JS that handles localStorage and then includes a specific css theme should be implementable, and would probably be the simplest approach.

The above would be the "simplest" approach, but this would produce the cleaner end result as we'd be able to remove the (non-functioning) theme selector as well.

That would also introduce more maintenance complexity, however.

[workingjubilee]

...perplexed, did I say something that did not have an identical meaning?

[Cldfire]

...perplexed, did I say something that did not have an identical meaning?

Unless I'm misreading, your approach involves removing the storage.js file whereas the one I described does not. This precludes the ability to change the default theme chosen for users who haven't yet specified a default while keeping the theme picker functionality. Other than that, they're definitely very similar 🙂

[workingjubilee]

Oh, true actually, I crossed a wire at some point.

[Mark-Simulacrum]

IMO, while a compilation time option is plausible, I would personally prefer that we just make the existing options UI work locally rather than adding ability to configure defaults; that would apply (presumably) to all Rust documentation viewed through file:///, so it shouldn't be too much of a problem to configure that once.

[jyn514]

That would be great to do, but I don't see how it's possible. There's no shared state between local files, rustdoc would need to run a local webserver which has its own issues.

[workingjubilee]

That's fair.
So, speaking of which: I cannot reproduce this bug.
I used rustup doc and clicked through to TRPL in Firefox. The themes were default (light) on this computer. I set the theme to the "Rust" sepia-ish theme. I then closed Firefox entirely. I then reopened TRPL in the same manner. The theme was still set. I repeated the same process with the std docs, but because they use a different set of themes, I needed to set a new theme.

The actual problem is likely:
User expects setting theme on e.g. Rust By Example to also set theme on e.g. The Rust Programming Language. A reasonable expectation as these both use the same theme set (with std it is slightly touchier).
The actual behavior: Each is determined independently, likely because they are "different sites" insofar as the browser is concerned.