Non-legible Xarray HTML representation in dark mode

[scottyhq]

The documentation example for Xarray isn't legible in dark mode:
https://pydata-sphinx-theme.readthedocs.io/en/v0.16.1/examples/pydata.html#Xarray

I see this came up in the past (#739) but I noticed at least in recent versions, the pandas dataframes look great in either mode, but I think the Xarray representation has gotten worse.

I'm new to CSS but am wondering if it would be easy to fix in the theme here by somehow specifying to "only display Xarray cell outputs with light mode styling". Or should the fix really happen in the Xarray code (pydata/xarray#8097)?

I ask because of noticing the changing appearance with different versions of this theme, I believe without changes on the Xarray side. So it does seem like some coordination is necessary. See for example this older version which wasn't ideal, but I'd argue better than the current rendering:
https://pydata-sphinx-theme.readthedocs.io/en/v0.13.3/examples/pydata.html#xarray

Also, we are finally getting around to upgrading the theme to 0.16.1 in the Xarray docs (pydata/xarray#8708), thanks for all the great work here :)

[drammock]

duplicate of #2020.

the heart of the problem is probably

pydata-sphinx-theme/src/pydata_sphinx_theme/assets/styles/extensions/_notebooks.scss

Lines 42 to 47 in f5c69c8

	html[data-theme="dark"] & {
	&.rendered_html:not(:has(table.dataframe)),
	// ipywidgets
	.widget-subarea {
	@include cell-output-background;
	}

which in turn calls

pydata-sphinx-theme/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss

Lines 14 to 23 in f5c69c8

	/**
	* Set background of some cell outputs to white-ish to make sure colors work
	* This is because many libraries make output that only looks good on white
	*/
	@mixin cell-output-background {
	color: var(--pst-color-on-background);
	background-color: var(--pst-color-text-base);
	border-radius: 0.25rem;
	padding: 0.5rem;
	}

I'd be totally happy doing something a bit more custom for xarray like we do for Pandas DataFrame table output, i.e.:

pydata-sphinx-theme/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss

Lines 25 to 55 in f5c69c8

	@mixin table-colors {
	color: var(--pst-color-table);
	border: 1px solid var(--pst-color-table-outer-border);
	th,
	td {
	~ th,
	~ td {
	border-left: 1px solid var(--pst-color-table-inner-border);
	}
	}
	thead {
	tr {
	background-color: var(--pst-color-table-heading-bg);
	border-bottom: 2px solid var(--pst-color-primary);
	}
	}
	tbody {
	tr {
	&:nth-child(odd) {
	background-color: var(--pst-color-table-row-zebra-low-bg);
	}
	&:nth-child(even) {
	background-color: var(--pst-color-table-row-zebra-high-bg);
	}
	}
	}
	}

The main barrier to getting this done is not having a contributor/maintainer with both the CSS knowledge to write the rules and also sufficient familiarity with xarray to know what all the possible output nodes might be. In other words, I could probably write some CSS that makes the one example in our docs look good, but don't have the time to put together a bunch of test cases for xarray objects of different flavors, compare their _html_repr_ outputs to make sure I know what all the relevant node classes are, etc.

If someone from the xarray team can confidently tell us that:

1. the example in PST's docs is exhaustive, in terms of including all the possible nodes/classes that xarray writes, and
2. those nodes/classes (probably) won't change very often (AKA, xarray treats their _html_repr_ output akin to a public-facing API)

then I think we can reasonably move forward. Without (1), we won't know that what we're doing will generalize, and without (2), we're shooting at a potentially moving target.

Side note: probably most of the solution exists in the aforementioned CSS file that gets embedded. We would "just" need to special-case xarray outputs to not get the light background for cell output, and "just" need to translate the embedded CSS rules into our SCSS source (subbing in our own variables where appropriate).

[scottyhq]

duplicate of #2020.

Sorry I overlooked that one! But thank you very much for the detailed response @drammock

The main barrier to getting this done is not having a contributor/maintainer with both the CSS knowledge to write the rules and also sufficient familiarity with xarray to know what all the possible output nodes might be.

Makes sense. I'm pinging @benbovy here to help answer your specific questions above! I'm hopeful we can identify the way forward and help out.

[benbovy]

Thanks for pinging me @scottyhq.

@drammock -- Although I haven't been closely following the changes in the Xarray's repr CSS lately (especially those related to themes), most of the useful information about it can be found at the top of https://github.com/pydata/xarray/blob/main/xarray/static/css/style.css. More specifically:

• The whole repr of each Xarray object is wrapped in an HTML container with class xr-wrap and I don't think it's going to change anytime soon
• For colors in the repr we use the CSS variables defined at the top of that css file. We'd be happy to special-case PST there too I think (like we already do for JupyterLab). My knowledge of CSS is limited: can we define multiple fallbacks for CSS variables? Something like --xr-background-color: var(--jp-layout-color0, var(--pst-color-something, white));?

[benbovy]

For Xarray's documentation it should be fixed with the workaround introduced in pydata/xarray#10353. However, it would still be nice if a special case could be introduced here (could simply be :not(:has(div.xr-wrap)) selector) so the documentation of Xarray extension or other projects do not need the same workaround.

[drammock]

Sorry for the radio silence... I think @gabalafou is now addressing this in #2187

[drammock]

(see https://pydata-sphinx-theme--2187.org.readthedocs.build/en/2187/examples/code-cells.html#Xarray-Datasets )

[gabalafou]

See also the preview build for #2187 at /examples/pydata.html#Xarray, which is the same example originally reported in this issue.