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?