ENH: Add dark mode support for some pydata packages by choldgraf · Pull Request #723 · pydata/pydata-sphinx-theme

choldgraf · 2022-06-11T22:55:06Z

This does two things:

Adds a page where we can show off the outputs from various libraries in the PyData ecosystem.
Adds a few more CSS rules to make sure that these libraries look reasonable in the dark mode.

As part of that, it also adds a (documentation only) dependency on myst-nb, and uses this execute our new pydata demo page. That should make it easier to cache the execution of that page so that it doesn't have to re-execute every time.

I think there's still some improvement to make (e.g., in the xarray CSS styling) but hopefully this makes it easy to naturally extend the CSS as new edge-cases are found with these libraries.

Also fixes two bugs:

Primary sidebar TOC was unnecessarily indented
Primary sidebar scrollbar was not colored properly (the variables didn't seem to be inherited so this set the color as the chrome default)

Check out the demo docs here: https://pydata-sphinx-theme--723.org.readthedocs.build/en/723/demo/pydata.html

12rambau · 2022-06-12T07:43:47Z

+  }
+
+  div.cell_output tbody tr:nth-child(odd) {
+    background: #f5f5f5;


are you sure about a hard coded color ?

12rambau · 2022-06-12T07:51:59Z

you also moved the search item right ?

12rambau · 2022-06-12T07:55:13Z

sorry for making a commit I didn't know how to make a suggestion. Now I do.
...and I didn't see it was a draft.I should stop making review on sunday morning before my first coffee,I'm always making mistakes

12rambau · 2022-06-12T08:03:29Z

+}
+
+// customize xarray display 
+.xr-wrap {


Suggested change

.xr-wrap {

.xr-wrap .x-var-list {

choldgraf · 2022-06-12T09:37:45Z

Oops I did not see that you had left some comments, sorry about that! I actually decided to take a slightly different approach here. Rather than special-casing each library, I decided to special case the execution / notebook libraries that people often use. So this PR now adds some rough dark theme support for jupyter-sphinx and myst-nb. I think that this will be a more sustainable solution than trying to special-case every visualization library out there. Does that make sense?

Also sorry about the search bar stuff, that was just some accidental cruft from another experiment!

I think it's ready for a look now - the failing test is because MyST-NB pins the upper bound of Python to 3.10

choldgraf · 2022-06-12T09:52:52Z

cc @tupui - I'm not sure what tool you're using to generate plots/outputs/etc in the scipy docs. This PR adds support for MyST NB and jupyter-sphinx, but we can add another if there's a different one needed to test (as long as it doesn't conflict w/ the previous two tools)

tupui · 2022-06-12T11:01:00Z

cc @tupui - I'm not sure what tool you're using to generate plots/outputs/etc in the scipy docs. This PR adds support for MyST NB and jupyter-sphinx, but we can add another if there's a different one needed to test (as long as it doesn't conflict w/ the previous two tools)

On SciPy we are using matplotlib.sphinxext.plot_directive. We have very simple needs.

choldgraf · 2022-06-12T13:39:54Z

OK added in a simple example w/ the plot directive in matplotlib...it seems to look OK-enough to me 🤷

tupui · 2022-06-12T13:58:45Z

I will have a look tmr thanks 😊

tupui

Thanks @choldgraf.

For the figures it's a matter of taste. I will keep the inversion in SciPy as I think it looks better because I can blend it with the background.

The code cells look a bit boxy here with the thin white border which is not present with the light theme.

Maybe consider adding a mathjax example? Or just some CSS for it. It's a "heavy" dependency if just for one example.

tupui · 2022-06-13T08:11:53Z

+We store our PyData-specific SCSS in two relevant files, both in the `src/pydata_sphinx_theme/assets/styles/` folder:
+
+- `extensions/_execution.scss` - styles for Sphinx libraries that execute and insert code into the documentation. For example, MyST-NB, Jupyter Sphinx, and the Matplotlib `plot` directive. Most PyData support should go here via generic improvements that all packages benefit from.
+- `extensions/_pydata.scss` - styles for specific libraries in the PyData ecosystem. In general we should try to keep this minimal because it is mostly special-casing single library quirks.


Does it mean we should contribute specific changes we have in SciPy for instance? Is this like a showcase section or it would be used somehow?

My assumption is that there might be many different communities using the functionality of a given PyData package, so if there's a SCSS change that improves something in this category, we should put it in this theme (in the _pydata.scss) file so others benefit from it. See the example in there, it is for an xarray output bug that was conflicting with Bootstrap

Co-authored-by: Pamphile Roy <roy.pamphile@gmail.com>

choldgraf · 2022-06-13T11:41:27Z

Yeah I agree on the boxiness of the cells (especially with the Jupyter Sphinx extension...I think it looks pretty fine w/ the MyST outputs).

re: inversion, my main concern was that this is changing all of the colors in the plot, which I imagine might have negative consequences for the reader's perception of the plot.

re: MathJax example, what kinds of things did you have in mind? I just added a docs section in our special theme elements for math, and this also caught a couple of math bugs :-)

tupui · 2022-06-13T12:12:03Z

For the maths I noticed that the color did not match. It was light gray so not very readable. I added:

html[data-theme=dark] .MathJax_SVG *  {
    fill: var(--pst-color-text-base);
}

choldgraf · 2022-06-13T12:36:57Z

ah good call - we weren't testing SVG math output here (we're using the HTML version). Latest commit adds that rule 👍

choldgraf · 2022-06-15T09:43:14Z

I think that this one is now ready to go, anything else to add here?

tupui

LGTM 👍

drammock · 2022-06-15T13:30:05Z

LGTM too

choldgraf · 2022-06-16T13:08:05Z

OK merging this one in since we have a bunch of approvals!

Adding dark mode support for some pydata packages

b3a35fb

choldgraf marked this pull request as draft June 12, 2022 07:46

customize wrapped elements

c440ee4

12rambau reviewed Jun 12, 2022

View reviewed changes

typo

845cd23

12rambau reviewed Jun 12, 2022

View reviewed changes

choldgraf added 3 commits June 12, 2022 11:33

Adding styles

b00a14e

Adding styles

8b010e5

navbar

dc3da7d

choldgraf marked this pull request as ready for review June 12, 2022 09:43

choldgraf mentioned this pull request Jun 12, 2022

DOC: dark theme css adjustments scipy/scipy#16379

Merged

choldgraf added 2 commits June 12, 2022 12:36

Fix nav padding bug

069303e

Fix scrollbar color

fa42eae

choldgraf force-pushed the pydata branch from 3d7ba13 to fa42eae Compare June 12, 2022 10:44

Plot directive

39caf35

choldgraf added 2 commits June 13, 2022 09:30

Explanation

5ec4ef1

Setup python action

aa583f3

tupui reviewed Jun 13, 2022

View reviewed changes

Apply suggestions from code review

71e84ff

Co-authored-by: Pamphile Roy <roy.pamphile@gmail.com>

choldgraf added 3 commits June 13, 2022 13:41

Math

84c8283

Merge branch 'main' into pydata

98edd1d

Math

781366e

Math SVG

1b5a45a

choldgraf commented Jun 15, 2022

View reviewed changes

Comment thread .github/workflows/tests.yml

choldgraf and others added 2 commits June 15, 2022 02:53

Update .github/workflows/tests.yml

0a60b02

toml

3668719

tupui approved these changes Jun 15, 2022

View reviewed changes

12rambau approved these changes Jun 16, 2022

View reviewed changes

Merge branch 'main' into pydata

4623a67

choldgraf commented Jun 16, 2022

View reviewed changes

Comment thread docs/contribute/topics.md

Update docs/contribute/topics.md

804aafe

choldgraf changed the title ~~Add dark mode support for some pydata packages~~ ENH: Add dark mode support for some pydata packages Jun 16, 2022

choldgraf merged commit 4c16582 into pydata:main Jun 16, 2022

choldgraf deleted the pydata branch June 16, 2022 13:08

12rambau mentioned this pull request Jun 17, 2022

pandas/xarray HTML representation in dark theme #739

Closed

choldgraf mentioned this pull request Jun 18, 2022

Add NBSphinx support for dark theme #741

Merged

Conversation

choldgraf commented Jun 11, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

12rambau Jun 12, 2022

Choose a reason for hiding this comment

Uh oh!

12rambau commented Jun 12, 2022

Uh oh!

12rambau commented Jun 12, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

12rambau Jun 12, 2022

Choose a reason for hiding this comment

Uh oh!

choldgraf commented Jun 12, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

choldgraf commented Jun 12, 2022

Uh oh!

tupui commented Jun 12, 2022

Uh oh!

choldgraf commented Jun 12, 2022

Uh oh!

tupui commented Jun 12, 2022

Uh oh!

tupui left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tupui Jun 13, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

choldgraf Jun 13, 2022

Choose a reason for hiding this comment

Uh oh!

choldgraf commented Jun 13, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tupui commented Jun 13, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

choldgraf commented Jun 13, 2022

Uh oh!

choldgraf commented Jun 15, 2022

Uh oh!

Uh oh!

tupui left a comment

Choose a reason for hiding this comment

Uh oh!

drammock commented Jun 15, 2022

Uh oh!

Uh oh!

choldgraf commented Jun 16, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

choldgraf commented Jun 11, 2022 •

edited

Loading

12rambau commented Jun 12, 2022 •

edited

Loading

choldgraf commented Jun 12, 2022 •

edited

Loading

tupui Jun 13, 2022 •

edited

Loading

choldgraf commented Jun 13, 2022 •

edited

Loading

tupui commented Jun 13, 2022 •

edited

Loading