Issue #12290 - Docs using Furo Theme W/ Dark Mode

[samjirovec]

• Replaced Flask theme for documentation with Furo. (Based on conversation in Support Dark Mode for Pytest Docs Website #12290)
  • Adds supports for dark mode in the docs + matching computer theme.

Light Mode:

Dark Mode:

[bluetech]

Quick link to preview: https://pytest--12326.org.readthedocs.build/en/12326/contents.html

Looks pretty nice to me. I noticed that in the API reference furo shows a warning about the table of contents: https://pytest--12326.org.readthedocs.build/en/12326/reference/reference.html

[samjirovec]

Ah, good find. When I get the chance today, I can go in a fix that.

Edit: cleaned up that error + one more page that had the same problem 🙂

[bluetech]

To me this looks good.

Can you compare this PR with #9788 from @pradyunsg, in case that PR had something that's worth bringing over to this PR?

[bluetech]

Should also remove the pallets-sphinx-themes?

[samjirovec]

Definitely. Will remove this. + removing some extras based on #9788

[The-Compiler]

I love this in general! Not too happy about the "next trainings and events" getting a bit lost now, though:

Is there a nice way we can inject some custom CSS or so to fix that?

[nicoddemus]

Overall I like the new theme!

The code highlighting for the light mode looks a bit off to me, but the highlighting for dark mode looks great. Perhaps that's something we can adjust later.

Is there a nice way we can inject some custom CSS or so to fix that?

Perhaps a small site-wide announcement? https://pradyunsg.me/furo/customisation/#announcement

I do not mean putting the entire information in the announcement, perhaps the announcement could be just a one liner "Next training/sprint: June 11th" with a link to a page with full details?

[samjirovec]

I love this in general! Not too happy about the "next trainings and events" getting a bit lost now, though:

...

Is there a nice way we can inject some custom CSS or so to fix that?

definitely a good callout. Im pretty new to rst, so I'll see if we can get it to be more prominent. The solution may be something like that announcement banner referenced above: #12326 (comment)

[samjirovec]

@nicoddemus @The-Compiler Did some experimenting with using that announcement bar but was having some problems with that static url. I reverted the sidebar for the trainings, here's a quick example of how that looks:

[pradyunsg]

I'd suggest also unsetting the pygments theme (I think it's called sphinx) in conf.py as well.

[pradyunsg]

You should be able to unpin this too since this was pinned due to the existing theme: #10578 (comment)

[samjirovec]

unpinned it + removed sphinx theme. This will affected only the light mode code snippets.

[nicoddemus]

I'd suggest also unsetting the pygments theme (I think it's called sphinx) in conf.py as well.

Ahh the syntax highlight for the light theme is now much better. ❤️

Thanks!

I'm approving, pending @The-Compiler's opinion on how the training looks (however this is of course something we can tweak/improve later).

[ferdnyc]

Sidebars

One difference with the new theme: The layout breakpoints are all expressed in em units now (the old theme used px), and in practice they're a lot bigger.

For example, with the old theme (on an unscaled desktop display, with the browser windowed), the left-hand sidebar only collapses itself when the window is less than 767px wide.

With this theme, the sidebar doesn't open until the window is more than 67em wide, which in practice ends up being around 1060px on my display.

Training & Events box

I also think the "Trainings and events" sidebar could be wider — 50% (instead of the default 30%) seems to strike a much better balance. It's got an ID, so that should be as easy as sticking some custom CSS in with:

#features { width: 50%; }

30%

50%

Bulleted lists

Oh, last but not least: The new theme shows unordered lists with no bullet style at all, just an indent. It's arguably cleaner, but it does change the look of many elements. Including the two date lines in the training & events box. (And makes their indentation kind of excessive, considering the <dd> they're wrapped in already has a huge indent.)

Old theme

New theme

[ferdnyc]

Bulleted lists

Oh, last but not least: The new theme shows unordered lists with no bullet style at all, just an indent. It's arguably cleaner, but it does change the look of many elements. Including the two date lines in the training & events box. (And makes their indentation kind of excessive, considering the <dd> they're wrapped in already has a huge indent.)

Ah, I see now that that part, at least, is not the theme, as it's done locally in the templates/style.html file. Neeeever mind, then.

[ferdnyc]

CSS syntax nit, and because the theme measurements are all in ems:

Suggested change

	li {margin: 5px 0};
	li {margin: 0.4em 0;}

[ferdnyc]

Suggested change

	</style>
	@media (min-width: 46em) {
	#features {width: 50%;}
	}
	</style>

(To widen the trainings & events sidebar. At 46em the width becomes 100%, messing with that looks weird.)

[samjirovec]

@ferdnyc Great callouts. Implemented those changes you suggested. I think that definitely makes that training section look a lot nicer 🙂

[The-Compiler]

Looking great, and seems to be a big improvement! Now the box also doesn't make the next heading look awkward anymore either.

Big fan of this, thanks a lot for tackling it!

[The-Compiler]

@nicoddemus @bluetech What do you think about backporting this to 8.2.x so it appears on pytest.org already?

[bluetech]

I think it's good to backport

[nicoddemus]

Agreed, backporting now.

[webknjaz]

@samjirovec @The-Compiler @nicoddemus @bluetech this makes bullet lists in the change log invisible. Well, globally, really. There are plenty of examples @ https://docs.pytest.org/en/latest/changelog.html#new-features and in the events widget too. What was the intention here?

Oh, @ferdnyc already called out this problem in #12326 (comment)...

[ferdnyc]

Yeah, to be honest I got as far as realizing that the missing bullets were intentional and explicit in the PR's local CSS, and immediately dropped it. Since it was clearly not a bug or an unexpected change, I assumed the decision to hide list markers was an aesthetic choice (possibly discussed elsewhere) for the new-theme look of the docs.

If that wasn't the case, and it was actually "snuck in" with the new theme (not in a malicious sense, just meaning that it wasn't explicitly stated in the PR/commit texts, and probably flew under people's radar), then I should've made a bigger fuss. With such sweeping changes completely transforming the appearance of the docs, it's easy to overlook a difference like that. My bad for not following up on it better.

[webknjaz]

From discussions, I don't think people realized the extent of the effect of this choice and the lack of granularity. Also, many might not be qualified to spot these problems easily. Thanks for trying to warn people, though :)

[nicoddemus]

I do not recall any discussion regarding intentionally hiding those bullet points... I personally would prefer them on.

Perhaps we can follow up another PR enabling them back? That would be a place for anybody who remembers that decision to voice that, but otherwise I suspect indeed this just flew under the radar, or was something that looked better on the old theme.

[ferdnyc]

Done, as #12581

[pradyunsg]

Oh wow, this is a bad way to do things. See https://pradyunsg.me/furo/customisation/injecting/#css-or-js for the guidance from the theme for how to inject CSS.