Make JupyterLab CSS align with the CSS of this theme

[choldgraf]

Context

JupyterLab is a very popular interface that is used by many in the PyData ecosystem, and that is increasingly becoming easier to embed directly into HTML pages via projects like JupyterLite. I suspect that over time, we'll see more documentation sites embedding live Jupyter kernels into Sphinx docs.

The PyData theme has a set of color variables that define dark/light themes.

JupyterLab has its own notion of a "light and dark mode", though this is presumably structured differently from this theme's CSS variables etc.

Suggestion

This theme could somehow trigger the respective mode in JupyterLab when it was embedded in the PyData Sphinx Theme. I think there are roughly two things to improve here:

• The default CSS variables in a theme might propagate to JupyterLab somehow
• When the documentation changes its theme mode, this should also trigger in JupyterLab as well.

Would love feedback on whether this would be interesting/useful, or ideas for implementation! cc @martinRenou who was interested in this too.

References

• https://twitter.com/martinRenou/status/1539236698068074497

[martinRenou]

I wonder if we could implement a way for the user to configure the JupyterLab theme they want to use:

html_theme_options = {
    # Would use https://github.com/timkpaine/jupyterlab_miami_nights 
    # (first need to be installed on the docs build machine)
    "jupyterlab-theme": "@timkpaine/jupyterlab_miami_nights"  
}

Then I guess we need to implement a bridge from the JupyterLab variables to the pydata-theme variables for the JupyterLab theme to properly apply?

--pst-color-primary: var(--jp-brand-color0);
--pst-color-success: var(--jp-success-color0);
/* etc... */

[12rambau]

Happy to help on this one

[12rambau]

Is there a way to trigger from dark to light theme in jupyterlite ?
This trigger should be listening to the data-theme property of the html tag. Also I would do it the other way around for the colors:

--jp-brand-color0: var(--pst-color-primary) !important;

To adapt jupyterLite to us and not the other way around (there are plenty of other sphinx theme and they should'nt be forced to use pst var)

[martinRenou]

Yes, I guess there are two separate things we could consider:

1 - Have the pydata-sphinx theme switch be propagated to JupyterLite when JupyterLite is embedded in sphinx (what Chris suggested in the issue) and JupyterLite respect the CSS variables from pydata-sphinx
2 - Have pydata-sphinx support core and custom JupyterLab themes (what I was suggesting in my comment) and overwrite the CSS variables pydata-sphinx provides

I suppose those two could probably be two separate issues/PRs and can be both implemented.

I fear the first proposition might be difficult because JupyterLite runs in an iframe (at least that's how https://github.com/jupyterlite/jupyterlite-sphinx is implemented), so sharing CSS and have the switch event propagate might be tricky (impossible?)

Is there a way to trigger from dark to light theme in jupyterlite ?

Yes, you can add the JavaScript logic to manipulate the JupyterLab theme manager and make it use a new theme.

[12rambau]

so sharing CSS and have the switch event propagate might be tricky (impossible?)

look like it's doable: https://stackoverflow.com/a/217833/6734243 (I'm not 100% that it's applicable here as I don't know how jupyterlite works)

[choldgraf]

I think a relatively low hanging fruit could be to just add an event listener callback to our theme function to trigger some JS that manually sets the jupyterlab theme to the same, if it is embedded on the page.

I think people would be ok with "slightly different but still dark" themes, that's already a huge improvement even if some colors are slightly off.

@psychemedia might think this is cool as well

[psychemedia]

Being able to synch themes "for free" could be really handy, esp if the end user has control of the light and dark theme...

Would this be limited to very specific themes, and would there be a boolean to optionally (dis)able this?

Is there any guidance / policy on setting JupyterLab/Lite and Sphinx themes so they colour co-ordinate?

Also, I wonder: co-ordinated language packs (if sphinx supports language packs?)?!

[martinRenou]

@12rambau @choldgraf

@jtpio just linked this in another thread https://jupyterlite.readthedocs.io/en/stable/howto/configure/advanced/iframe.html

It showcases an example making a jupyterlite plugin allowing to set the theme from outside of the iframe.

We could provide such a plugin by default in jupyterlite-sphinx, allowing pydata-sphinx-theme to notify jupytelite iframes of a potential theme change.

[12rambau]

That would be perfect, at the end of the day we have the whole infrastructure ready, we just miss a handle from JupyterLite side to trigger a change so anything that you have is a very good news !

[Carreau]

what kind of handled would you like ?
Would something like #1900 work ?

[trallard]

Bringing in @gabalafou for opinions/thoughts (also there is #1740 which is somewhat related via #1740 (comment))