Dark Mode Rustdocs

[mark-i-m]

I tend to program in dark-mode (white text on black background), so switching to rustdocs in my browser tends to be kind of blinding. It would be really nice if I could choose from a number of styles, kind of like what the rust playground offers.

[steveklabnik]

We historically have not wanted the increased maintenance burden this implies, but are generally open to it in the future.

[mark-i-m]

Hmm... I guess I was under the impression that the same mechanism can be used for this as for the playground... is that not the case? It seems like it should be possible to just use the same set of stylesheets, right?

[steveklabnik]

It's not inherently about the mechanism; it means that any visual changes now need N changes instead of one change.

[onelson]

What if the change was to provide a way to override the stylesheets linked in the generated docs?
Userland themes have worked quite well for projects like Sphinx. A set of stylesheets could be specified in Cargo.toml and would then be copied into the docs directory during the build.

This could mitigate the maintenance burden and give folks with visual preferences a way to customize.

[steveklabnik]

Possibly, yes.

[mark-i-m]

That doesn't give the user of your docs any choice though, right? I imagine that most people refer to other people's docs more than their own... at least, I do...

But perhaps a similar feature could be used somehow with hosted docs? For example, the user could upload a stylesheet to use... I don't know how this would work without some server side work though, which sounds unfavorable.

An alternative is to limit options. For example, give the user a color chooser and let them have at it for certain elements of the DOM. Or to only give them the two choices​ of light and dark mode, which is what e-readers tend to do...

[onelson]

That doesn't give the user of your docs any choice though, right? I imagine that most people refer to other people's docs more than their own... at least, I do...

If you have a theme you like, with the proposed link tag injection, you should be able to build docs locally with your theme on all the docs for all the crates. Perhaps this is unwieldy.

In my mind, hosted docs should be able to offer a range of themes. Permitting user uploads would be up to them.
In fact, with a little dab of javascript they should be able to rewrite the <link> tags based on the reader's preference now, with no change to rustdoc.

Regardless, I think the main thing to focus on with this is to ensure that rust devs don't have to hand-wring too hard about changes to the docs. It should be up to the theme authors to track changes and update as needed as markup evolves.

[mark-i-m]

In fact, with a little dab of javascript they should be able to rewrite the tags based on the reader's preference now, with no change to rustdoc.

Hmm.. this sounds like the best option so far... rustdoc would allow you to specify the URL of a stylesheet to use... Then, just point to a stylesheet online maintained by some third-party...

[durka]

There are some available, e.g. this one but they're not perfect.

[GuillaumeGomez]

We historically have not wanted the increased maintenance burden this implies, but are generally open to it in the future.

Ah? That's good to know. :p

@durka: I already wrote a dark theme as you can see here. Just waiting for the possibility to be able to add custom themes by default in rustdoc some days.

[onelson]

Well, I am pleased to see that I'm not 100% crazy, as per this article by @GuillaumeGomez the feature for adding extra css at build time already exists!

From the article:

RUSTDOCFLAGS='-Z unstable-options --extend-css dark.css' cargo doc

[mgattozzi]

What if there was some way to have some local css file that if it does exist is used to overwrite the docs style and if not it defaults to the current implementation? That way the docs don't have to pay the maintenance version but it still automatically reads from a custom file that people can have.

[onelson]

some way to have some local css file that if it does exist is used to overwrite the docs style

You could likely afford to be a lot less clever than this. Having a link tag that points to a non-existent file should do no harm besides an unsightly 404 in your web server logs. We could just put a link to an "overrides.css" below the rest of the stylesheets. This would let you leverage the cascade to tweak whatever you like.

[GuillaumeGomez]

What I had in mind was more simple: every specified css file would be added into a list which would be displayed at the top right corner of the generated docs so you could switch between them. I made a PR which added this a year (or more?) ago.

[mark-i-m]

That seems like it would a great deal of diversity in how rustdocs look, right? Is that a good thing or a bad thing?

[GuillaumeGomez]

For me it'd be awesome since I hate white themes.

[mark-i-m]

Lol, and here we are on GitHub 😆

[durka]

GitHub, you say‽

[clarfonthey]

We historically have not wanted the increased maintenance burden this implies, but are generally open to it in the future.

This would be really easy to maintain if Rust decided to adopt a CSS preparser like SASS, or decided that CSS variables are worth altering browser support (#1985). Obviously, that's a larger maintenance burden then we have right now, but considering how the rust book has multiple themes, I think that this is very doable.

Another way to manage multiple themes in CSS is to just give the HTML element a class and make all of the colours used in the document relative to that class in the CSS.

[GuillaumeGomez]

I just wait for the dev tools team to be created so I'll be able to start discussions (and hopefully implementation) of the custom themes.

@clarcharr: Not sure it makes it simpler, but worth discussing about it.

[mark-i-m]

Ping! 🏓

Shall I open an RFC for this? My current proposal would be

• to have two rust-provided styles: what we have currently, and a dark mode (perhaps based on @GuillaumeGomez 's stylesheet).
• In addition, we would allow the runner of rustdoc to specify extra stylesheets.
• A viewer of the docs would be able to choose from all available styles (2 rust-provided + any others) from a javascript-powered drop-down.

[GuillaumeGomez]

We have discussed about this recently with @rust-lang/dev-tools team. It should arrive in the next months or so. A few things remain to be done beforehand but it's coming.

[alexheretic]

While we wait for a official solution it's actually pretty effective to apply a colour inversion sledgehammer to the documentation pages, with 3 CSS rules. Also quite change resilient as user styles go.

https://userstyles.org/styles/150560/dark-rust-documentation

[GuillaumeGomez]

It's not very good, just useful but the results sounds like a picture with inverted colors (which is what is done basically). The doc themes are coming once I have a bit of time ahead.

[alexheretic]

The user style is just a simple way to darken it for now, perhaps useful to some. I look forward to proper dark theme support!

[JohnBSmith]

The following solution works with both, server side scripting and JavaScript:

1. Get abstraction by using classes: <tag class="xyz"></tag>.
2. Use a query: https://doc.rust-lang.org/std/?css=dark
3. It's possible to request the query string, even with JavaScript.
4. Switch the file load to "dark.css". It's possible to load a file dynamicly from the same directory including all subdirectories, even with JavaScript by XMLHttpRequest (provided, access is allowed -- the server can control this). Alternatively use <link id="css" href="main.css" rel="stylesheet"> and replace href="main.css" by href="dark.css".
5. If JavaScript is used instead of server side scripting, and JavaScript is turned off, nothing happens. So you're on the safe side if the page is static content anyway.

Assumptions made:

1. A modern browser is used.
2. A modern server software is used.

[GuillaumeGomez]

That's far more complicated than what will be done. We just "switch" the css loaded and save the current one using local storage.

[JohnBSmith]

I forgot to consider keeping the style sheet persistent when following internal links. So, yes, it's better to save the configuration in local storage than to inject the query into all internal links. (The configuration has to be saved somewhere, if JavaScript is used instead of server side scripting.)

Keep in mind that some users configure their browsers to disallow any form of persistent cookies. Thus, local storage degrades approximately into session storage. From that reason I would recommend to activate the dark mode by an URL query (at least as an alternative). This way, one can simply provide a link "into dark mode", which is pretty cool.

[GuillaumeGomez]

Still alternative themes has been merged, I'll close this issue. For any other things you might want to be added, just open other issues. :)