Notebook cell styling (nbsphinx and MyST-NB) #2187

gabalafou · 2025-04-11T02:11:51Z

This is an implementation of Isabela's designs for notebook cell styling.

The pull request has a few parts:

A bunch of CSS rules that replace style rules from nbsphinx and MyST-NB. In a previous iteration of this PR, I was overriding nbsphinx's and MyST-NB's rules, but this was complex and not long-term sustainable.
An example notebook copied from nbsphinx's documentation that demonstrates lots of different code cells. This gives us some assurances that the styles are working as we intend and will help us spot errors in the future.
Changes to the build process that enable us to swap out our CSS for the extensions' CSS during build time if the project using our theme depending on which extension the project is using, if it's using one.
Some magic to allow us to build the theme docs using both nbsphinx and myst-nb at the same time. Boils down to designating a special suffix for MyST-NB (.mystnb.ipynb) and copying the source notebook file to path with that extension at the beginning of the build.

Known differences from the design

In the design, the labels for the code cells follow a format like "In 1" and "Out 1", but this PR drops the numbers.
In the design, the vertical bar was green. Here it is the theme blue.

How to test this pull request

To test on the preview build:

Go to the code cells page in the preview build, as well as the code cells MyST-NB preview
Inspect it visually.
Also press the tab key to move about the page and see how the focus ring looks.
Do the same for the pydata notebook
Do it for both light and dark modes.

To test locally, build the docs locally and check the same pages.

isabela-pf

This looks so good! I'm happy to be able to say nothing I saw on the preview page surprised me. Visually, this implementation follows the previously discussed designs and fits in with the visuals surrounding it. It was especially helpful to see it in use on so many notebook output types for review.

In the design, the labels for the code cells follow a format like "In 1" and "Out 1", but these labels are generated by nbsphinx so they are not easy to completely override with CSS. So in this pull request they follow a format like "In [1]" and "Out [1]" with brackets.

I consider this an acceptable break from the design, and really an oversight on my part to not catch the way nbsphinx was doing it in the first place. Thanks for calling this out for clarity regardless.

Other review notes:

This PR doesn't interrupt any responsive page behaviors, nor does it make any new responsive problems as far as I can tell.
I can navigate through the page contents with my keyboard the same way I could before. I'm not finding any changes in behavior with keyboard only-navigation.
I am not finding any changes in screen reader (VoiceOver) behavior with this PR. Everything appears to operate and read the same.
The visual changes this PR makes matches visuals in the existing theme. I wasn't concerned about this changing based on previous discussions, but I do want to vouch it was done properly.

Design-wise, I don't have any changes to request. Thanks for reaching out for a review.

gabalafou

Finished self review. I feel pretty good about this.

One thing to consider is whether we should make it possible to disable these styles with a configuration variable.

gabalafou · 2025-05-06T12:22:22Z

.pre-commit-config.yaml

-          - [email protected]
-          - [email protected]
+          - stylelint
+          - stylelint-scss


I changed these lines because I was getting indecipherable error messages when trying to commit scss files with lint errors. After these changes, I got intelligible error messages.

gabalafou · 2025-05-06T12:26:49Z

docs/examples/code-cells.ipynb

+   "metadata": {
+    "nbsphinx": "hidden"
+   },
+   "source": [


Since most of this notebook is copied from the nbsphinx repo, I copied the MIT license from that repo and added it here in a cell that's hidden from nbsphinx—that way, the notice appears in the source code or any notebook application, but is not shown on the docs site.

gabalafou · 2025-05-06T12:27:18Z

docs/examples/images/notebook_icon.png

These images are needed by the code-cells notebook

gabalafou · 2025-05-06T12:28:04Z

docs/examples/pydata.ipynb

+    "mpg_df = pd.read_csv(mpg_csv, index_col=0)\n",
+    "mpg_df"
+   ]
+  },


I added this table because I wanted to see if the table-layout: auto rule would have any effect. (It doesn't.)

gabalafou · 2025-05-06T12:32:26Z

src/pydata_sphinx_theme/assets/styles/extensions/_notebooks.scss

-// Override nbsphinx's colors for notebook cell prompts because they do not have
-// sufficient contrast. Colors chosen from accessible-pygments
-// a11y-high-contrast-{light,dark} themes.
+  // Override nbsphinx's styles with our own <pre> tag styles
+  div.nbinput.container div.input_area div[class*="highlight"] > pre,
+  div.nboutput.container div.output_area div[class*="highlight"] > pre {
+    @extend %pre-style;

-// Notebook cell input line number. Replace nbsphinx's low contrast blue with
-// higher contrast blues.
-.nbinput.container .prompt pre {
-  html[data-theme="light"] & {
-    // Copied from accessible-pygments [a11y-high-contrast-light](https://github.com/Quansight-Labs/accessible-pygments/tree/main/a11y_pygments/a11y_high_contrast_light)
-    color: #005b82;
+    margin: 0;
  }

-  html[data-theme="dark"] & {
-    // Copied from accessible-pygments [a11y-high-contrast-dark](https://github.com/Quansight-Labs/accessible-pygments/tree/main/a11y_pygments/a11y_high_contrast_dark)
-    color: #00e0e0;
+  // Last container styles
+  div.container.nblast {
+    margin-bottom: $top-and-bottom-container-space;
+
+    // Override nbsphinx's padding rule. Let the whitespace be controlled by the
+    // margin-bottom rule above. This is important because if we create
+    // whitespace with padding instead of margin, then we create a misalignment
+    // between the vertical left bar and the bottom of the notebook cell.
+    padding-bottom: 0;
  }
 }

-// Notebook cell output line number. Replace nbsphinx's low contrast red with
-// higher contrast red / orange.
-.nboutput.container .prompt pre {
-  html[data-theme="light"] & {
-    // Copied from accessible-pygments [a11y-high-contrast-light](https://github.com/Quansight-Labs/accessible-pygments/tree/main/a11y_pygments/a11y_high_contrast_light)
-    color: #a12236;
-  }
+// Nest under .bd-article-container so that selectors have higher specificity
+// and can therefore override the rules in the nbphinx stylesheet.
+.bd-article-container {
+  @include _nbsphinx-restyle;
+
+  .nboutput {
+    .output_area {
+      &.rendered_html,
+      .jp-RenderedHTMLCommon {
+        // pandas
+        table.dataframe {
+          @include table-colors;
+
+          tbody {
+            tr:hover {
+              background-color: var(--pst-color-table-row-hover-bg);
+            }
+          }
+        }
+      }

-  html[data-theme="dark"] & {
-    // Copied from accessible-pygments [a11y-high-contrast-dark](https://github.com/Quansight-Labs/accessible-pygments/tree/main/a11y_pygments/a11y_high_contrast_dark)
-    color: #ffa07a;


Removed these lines (61-89) because in Isabela's design, the cell label text, In [N] and Out [N], is just the same color as the surrounding documentation text.

gabalafou · 2025-05-06T12:50:40Z

src/pydata_sphinx_theme/assets/styles/extensions/_notebooks.scss

-        tbody {
-          tr:hover {
-            background-color: var(--pst-color-table-row-hover-bg);
-          }


I mostly yanked the above lines (12-36) and pasted them further down the file.

However, the margin rule was no longer needed because the other style rules added take care of focus ring issues.

gabalafou · 2025-05-06T14:08:48Z

src/pydata_sphinx_theme/assets/styles/extensions/_notebooks.scss

+
+    div.input_area {
+      border: none; // border taken care of by <pre> styles elsewhere in the theme
+      overflow: visible;


I think all of the overflow: visible rules added in this PR were added to make the focus ring visible.

A safer, but more complex alternative would be to carefully add focus-ring-width padding to focusable elements. However, I have observed that whatever gets rendered into the input or output areas is usually rendered within some kind of container that has overflow: auto rules. In other words, I haven't seen any cases where the content rendered into the output or input areas overflows its parent (except for a few specific HTML widget cases that I handle separately).

Furthermore, I tried going down the route of adding padding to create space for the focus ring, and it really is quite a bit more complex. If you want the stuff in the input and output areas to be left-aligned with the labels (as in Isabela's designs), then you have to start carefully subtracting padding from parent elements wherever you add padding to child elements. Furthermore, as you will see further down, the way I fixed padding-related alignment issues was to set padding to zero using the same selectors that nbsphinx uses in its CSS. When you set padding to zero, you don't have to worry whether you're applying the rule to both parent and child. But when you add padding to create space in which to draw the focus ring, then you have to know whether the parent or child is getting focus, and the way this currently works is not consistent. Sometimes the parent element gets focus, for example the div.output_area containing a wide Pandas data table. Sometimes the child gets focus, for example the pre element inside of the div.output_area in the case of a plain text output.

So if you want to add focus-ring-width padding to div.output_area you have to make sure it does not contain any of those elements that are focusable and that also need focus-ring-width padding. That would mean a selector that looks like:

div.output_area:not(:has(pre, ...))

And I just think this is a very messy way to write CSS, and may not even work well across all browsers.

So I think it's worth taking the risk of setting overflow: visible in several places.

gabalafou · 2025-05-06T14:14:12Z

src/pydata_sphinx_theme/assets/styles/extensions/_notebooks.scss

+      // Override our own style rule in _math.scss
+      div.math {
+        display: block;
+      }
+
+      span.math {
+        display: inline;


I will open a follow-up PR to better handle math content both within notebooks and outside of notebooks. That way we won't need to override our own rules.

gabalafou · 2025-05-06T14:15:27Z

src/pydata_sphinx_theme/assets/styles/extensions/_notebooks.scss

-      &.rendered_html:not(:has(table.dataframe)),
-      // ipywidgets
-      .widget-subarea {
-        @include cell-output-background;


These lines (41-46) are just moved down, not actually deleted.

gabalafou · 2025-05-06T14:19:15Z

src/pydata_sphinx_theme/assets/styles/extensions/_notebooks.scss

-  }
+// Nest under .bd-article-container so that selectors have higher specificity
+// and can therefore override the rules in the nbphinx stylesheet.
+.bd-article-container {


Some of these rules used to be nested under .bd-content. But as far as I can tell, notebook content will always be rendered within .bd-article-container, so this is the better selector to use for nesting.

gabalafou · 2025-05-06T15:25:53Z

Labeling this as "do not merge" because it can be reviewed right now but it should not be merged until after 0.17 is released

drammock

this is looking pretty good! nice work @isabela-pf and @gabalafou. Comments below on quirks that I noticed.

drammock · 2025-05-08T16:06:53Z

docs/examples/code-cells.ipynb

+    "The standard error stream is highlighted and displayed just below the code cell.\n",
+    "The standard output stream comes afterwards (with no special highlighting).\n",
+    "Finally, the \"normal\" output is displayed."


as mentioned in the note box below, this doesn't necessarily reflect the order in the rendered doc (where stdout precedes stderr): https://pydata-sphinx-theme--2187.org.readthedocs.build/en/2187/examples/code-cells.html

Can we generalize the language here to say "normal output comes last" and update the note to say "when stdout/stderr are both present, which one comes first can vary by kernel"?

Yep! Added in the latest updates.

drammock · 2025-05-08T16:14:58Z

docs/examples/code-cells.ipynb

+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "Image(url=\"https://jupyter.org/assets/homepage/main-logo.svg\")"
+   ]
+  },


Seems redundant; what does this cell demonstrate that is different from the one 2 cells before it (the first python logo, without embed=True)? Is .png vs .svg the point?

I'm not sure myself, but yes I think that is the point.

In the latest update, I have added some markdown cells to label these code cells, which should help the reader to understand that the point of these code cells is in fact to png vs svg, passing the embed keyword argument versus not passing it.

drammock · 2025-05-08T16:16:52Z

docs/examples/code-cells.ipynb

+    "\n",
+    "\n",
+    "Latex(\n",
+    "    r\"This is a \\LaTeX{} equation \"\n",


\\LaTeX{} isn't rendering correctly in the output

Latex also not rendering on NBSphinx docs. I'll just remove the Latex reference.

drammock · 2025-05-08T16:19:53Z

docs/examples/code-cells.ipynb

+    "<div class=\"alert alert-info\">\n",
+    "\n",


maybe better? Or was this meant to intentionally show a no-title alert box?

Suggested change

"<div class=\"alert alert-info\">\n",

"\n",

"<div class=\"alert alert-info\">\n",

"\n",

"Note\n",

"\n",

No, I don't think the point is to show a no-title alert box. I don't think the point of the code-cells.ipynb notebook is to demo any markdown cells, only code cells (the nbsphinx docs have a separate page to demo markdown cells). So I added your suggestion in the latest update.

drammock · 2025-05-08T16:24:20Z

docs/examples/code-cells.ipynb

+   "outputs": [],
+   "source": [
+    "fig, ax = plt.subplots(figsize=[6, 3])\n",
+    "ax.plot([4, 9, 7, 20, 6, 33, 13, 23, 16, 62, 8]);"


this renders as a .png in the built docs, identical to the .png in the following cell's output.

I added a code cell above and checked locally that it makes this output SVG instead.

docs/examples/code-cells.ipynb

drammock · 2025-05-08T16:27:54Z

docs/examples/code-cells.ipynb

+   "source": [
+    "a = {}\n",
+    "for name in [\"t\", \"q\"]:\n",
+    "    da = xr.DataArray(\n",
+    "        [\n",
+    "            [[11, 12, 13], [21, 22, 23], [31, 32, 33]],\n",
+    "            [[14, 15, 16], [24, 25, 26], [34, 35, 36]],\n",
+    "        ],\n",
+    "        coords={\"level\": [\"500\", \"700\"], \"x\": [1, 2, 3], \"y\": [4, 5, 6]},\n",
+    "        name=name,\n",
+    "        attrs={\"param\": name},\n",
+    "    )\n",
+    "    a[name] = da\n",
+    "\n",
+    "ds = xr.Dataset(a, attrs={\"title\": \"Demo dataset\", \"year\": 2024})\n",
+    "ds"
+   ]


output is illegible in dark mode, though for xarray content this is a known bug, not a regression (#2189)

Should be fixed by my addition of :not:has(.xr-wrap) to this SCSS selector:

&.rendered_html:not(:has(table.dataframe, .xr-wrap)),

Xarray in dark mode looks better now. Screenshot from preview build:

drammock · 2025-05-08T16:33:33Z

docs/examples/code-cells.ipynb

+    "link = w.IntSlider(description=\"link\")\n",
+    "w.link((slider, \"value\"), (link, \"value\"))\n",
+    "jslink = w.IntSlider(description=\"jslink\")\n",
+    "w.jslink((slider, \"value\"), (jslink, \"value\"))\n",
+    "dlink = w.IntSlider(description=\"dlink\")\n",
+    "w.dlink((slider, \"value\"), (dlink, \"value\"))\n",
+    "jsdlink = w.IntSlider(description=\"jsdlink\")\n",
+    "w.jsdlink((slider, \"value\"), (jsdlink, \"value\"))\n",
+    "w.VBox([link, jslink, dlink, jsdlink])"


the labels "link", "dlink", "jslink", and "jsdlink" won't communicate the 4 scenarios clearly to many readers. Can we change to something like:

kernel vs javascript

bidirectional vs oneway

and also specify that what these are (bi/uni)directionally linking to is slider from the prior cell?

Tried to address this feedback in my latest updates!

drammock · 2025-05-08T16:36:50Z

docs/examples/code-cells.ipynb

+   "source": [
+    "tabs = w.Tab()\n",
+    "for idx, obj in enumerate([df, fig, eq, i, md, slider]):\n",
+    "    out = w.Output()\n",
+    "    with out:\n",
+    "        display(obj)\n",
+    "    tabs.children += (out,)\n",
+    "    tabs.set_title(idx, obj.__class__.__name__)\n",
+    "tabs"
+   ]


math isn't correctly rendered in dataframe colnames, nor in the dedicated math tab.

Markdown text is nearly illegible in dark mode:

contrast on widget slider handle border is pretty subtle

Same issues on the corresponding nbsphinx code cells doc page. I have no idea how to fix this.

Latest update should fix it

Latest update should fix

One way to fix the broken math in the tab would be just to remove it. I already tried moving the math tab to the first — in case being hidden off the DOM at page load was the reason it wasn't rendering. That didn't work.

Markdown issue fixed! Screenshot from preview build:

drammock · 2025-05-08T16:49:00Z

docs/examples/code-cells.ipynb

+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "raises-exception"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "traceback  # NOQA: F821"
+   ]
+  },


it's odd that this cell gets the green "success" color for its left-border line. I would have expected orange/red. 🤔

This is a very good point. I wonder if we should use a different color that doesn't have semantic associations with success or failure. Maybe a gray border would be better? @isabela-pf, what do you think?

Here's a screenshot for reference:

This is a very good point. I wonder if we should use a different color that doesn't have semantic associations with success or failure. Maybe a gray border would be better? @isabela-pf, what do you think?

IMO, if this is an error or an exception this should use the failure (or equivalent) semantic colour. Or is there a reason you are suggesting using gray instead?

In consultation with Isabela, I updated this PR to use the primary (blue) color instead of green.

@trallard, to avoid scope creep, I would prefer to tackle the feature of a vertical bar that changes color (green for successfully executed code cells, red for failed) in a potential future PR. As far as I can tell, nbsphinx does not provide an easy way to distinguish success from error.

It is fine, I had not realised this was changed to the primary colour, but if we were using semantic colours for one state, that should be consistent across various states.

Let me know what you think about the primary, blue color bar. Maybe I've been looking at it too much, but I think it adds too much color to the page and distracts from the content. I'm thinking it should be gray, which would also allow it to be more consistent across all sites (even if they have customized the primary color to something other than blue). Also, if any site is using green for their primary color, then their users might also infer that the bar means "success" and be a little confused when it doesn't change color next to a cell that failed. Using gray would avoid that scenario.

gabalafou · 2025-05-09T14:08:51Z

@drammock, thank you so much for this feedback!

A lot of the things you caught have something to do with the original Code Cells notebook and nbsphinx itself. Almost all of the problems that you point out exist on the corresponding nbsphinx docs page for Code Cells (except for the dark mode stuff because the nbsphinx docs site does not support dark mode).

Some of these things I can fix on our docs by modifying the Code Cells notebook (such as changing the prose to make the document clearer). Some of these things will be beyond my ability to fix in this PR because they would require me to patch nbsphinx (or further upstream).

I think your comments raise an important point that I didn't fully appreciate when I copied this notebook from nbsphinx to our own documentation, which is that once it is on our docs site, we become in some way responsible for whatever shortcomings exist in the document. I was thinking about this page less in terms of documentation and more as just a place to check how our theme combines with nbsphinx. But maybe the docs site is not the appropriate place for that. Do you think it would make sense to create a separate site that isn't aimed at end users? Not a doc site but a demo site?

drammock · 2025-05-09T14:28:54Z

I think docs/examples is a fine place for content like this (many users won't use nbsphinx, but for those who do, they should be able to easily see and assess how well we interoperate with it). I agree that by incorporating it here we take some degree of ownership, and I think that the right way forward is to modify the content to make clear what we can and can't fix (i.e., make the example a bit more self-documenting). In other words, more interleaved prose that points out the shortcomings and the barriers (big or small) to overcoming them.

gabalafou

@drammock, I think I addressed all of your comments in my latest updates. I will need to go back through and give this another round of self review because I have made substantial changes since your last comments.

The big shift in the latest updates to this PR is that I am no longer overriding nbsphinx's style rules. Rather, I am completely replacing nbpshinx's stylesheet with one of our own.

This comes with a number of changes to the Python and build sides of the theme package.

gabalafou · 2025-05-27T18:29:05Z

docs/examples/code-cells.ipynb

+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "Image(url=\"https://jupyter.org/assets/homepage/main-logo.svg\")"
+   ]
+  },


I'm not sure myself, but yes I think that is the point.

In the latest update, I have added some markdown cells to label these code cells, which should help the reader to understand that the point of these code cells is in fact to png vs svg, passing the embed keyword argument versus not passing it.

gabalafou · 2025-05-27T18:37:39Z

docs/examples/code-cells.ipynb

+    "\n",
+    "\n",
+    "Latex(\n",
+    "    r\"This is a \\LaTeX{} equation \"\n",


Latex also not rendering on NBSphinx docs. I'll just remove the Latex reference.

gabalafou · 2025-05-27T18:38:20Z

docs/examples/code-cells.ipynb

+    "<div class=\"alert alert-info\">\n",
+    "\n",


No, I don't think the point is to show a no-title alert box. I don't think the point of the code-cells.ipynb notebook is to demo any markdown cells, only code cells (the nbsphinx docs have a separate page to demo markdown cells). So I added your suggestion in the latest update.

gabalafou · 2025-05-27T18:38:58Z

docs/examples/code-cells.ipynb

+   "outputs": [],
+   "source": [
+    "fig, ax = plt.subplots(figsize=[6, 3])\n",
+    "ax.plot([4, 9, 7, 20, 6, 33, 13, 23, 16, 62, 8]);"


I added a code cell above and checked locally that it makes this output SVG instead.

gabalafou · 2025-05-27T18:42:38Z

docs/examples/code-cells.ipynb

+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "raises-exception"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "traceback  # NOQA: F821"
+   ]
+  },


In consultation with Isabela, I updated this PR to use the primary (blue) color instead of green.

@trallard, to avoid scope creep, I would prefer to tackle the feature of a vertical bar that changes color (green for successfully executed code cells, red for failed) in a potential future PR. As far as I can tell, nbsphinx does not provide an easy way to distinguish success from error.

docs/examples/code-cells.ipynb

gabalafou · 2025-05-27T18:46:58Z

docs/examples/code-cells.ipynb

+   "source": [
+    "a = {}\n",
+    "for name in [\"t\", \"q\"]:\n",
+    "    da = xr.DataArray(\n",
+    "        [\n",
+    "            [[11, 12, 13], [21, 22, 23], [31, 32, 33]],\n",
+    "            [[14, 15, 16], [24, 25, 26], [34, 35, 36]],\n",
+    "        ],\n",
+    "        coords={\"level\": [\"500\", \"700\"], \"x\": [1, 2, 3], \"y\": [4, 5, 6]},\n",
+    "        name=name,\n",
+    "        attrs={\"param\": name},\n",
+    "    )\n",
+    "    a[name] = da\n",
+    "\n",
+    "ds = xr.Dataset(a, attrs={\"title\": \"Demo dataset\", \"year\": 2024})\n",
+    "ds"
+   ]


Should be fixed by my addition of :not:has(.xr-wrap) to this SCSS selector:

&.rendered_html:not(:has(table.dataframe, .xr-wrap)),

gabalafou · 2025-05-27T19:29:30Z

docs/examples/code-cells.ipynb

+   "source": [
+    "tabs = w.Tab()\n",
+    "for idx, obj in enumerate([df, fig, eq, i, md, slider]):\n",
+    "    out = w.Output()\n",
+    "    with out:\n",
+    "        display(obj)\n",
+    "    tabs.children += (out,)\n",
+    "    tabs.set_title(idx, obj.__class__.__name__)\n",
+    "tabs"
+   ]


Same issues on the corresponding nbsphinx code cells doc page. I have no idea how to fix this.

Latest update should fix it

Latest update should fix

gabalafou

@trallard oopsies you reviewed this PR as I was making changes on it today, before I had a chance to update the PR description.

There are a lot of changes that might not make sense without a good overview. I updated the PR description.

I also answered your inline comments.

Thanks so much!

gabalafou · 2025-05-27T20:12:31Z

src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss

+  :focus-visible {
+    outline-color: #{map-deep-get($pst-semantic-colors, "accent", "light")};
+  }


This is within a mixin that's used to apply a light background to code cell outputs (such as ipywidgets) that we do not expect to have dark mode support built-in.

gabalafou · 2025-05-27T20:20:20Z

src/pydata_sphinx_theme/assets/styles/nbsphinx-pydata-theme.scss

+    // TODO: add to translations
+    content: "In:";
+  }


But these in/out labels don't exist in JupyterLab or other notebook app interfaces that I have seen.

We are adding them in this theme as an accessibility affordance — primarily for cognitive accessibility, I would argue.

It's ultimately a rather small thing, but then again, big enough for us to add the labels in English...

So I think it would probably make sense to translate them, or rather, to make them translatable, and leave it up to the translators to make a judgment call about whether or not it would be appropriate to translate these strings given the context.

gabalafou · 2025-05-27T20:21:24Z

src/pydata_sphinx_theme/assets/styles/nbsphinx-pydata-theme.scss

+/*
+ * Syntax highlighting for console/terminal output
+ */


Some of this is copy-paste from nbsphinx: https://github.com/spatialaudio/nbsphinx/blob/master/src/nbsphinx/_static/nbsphinx-code-cells.css_t

gabalafou · 2025-05-27T20:22:04Z

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

+@import "abstracts/all";
+
+// These files output *CSS* variables (not to be confused with SCSS variables)


No that should not be right. I tried to make sure that was not happening. Can you show me where that's happening?

gabalafou · 2025-05-27T20:23:42Z

src/pydata_sphinx_theme/nbsphinx.py

+# This function will allow us to catch during development or CI if nbsphinx ever
+# changes the name of the CSS file where it outputs its notebook styles.


No this function deletes their stylesheet. The other function replaces (sorta, it actually just updates the link to point to a different place).

The comment may not be in the best place but I'm trying to answer the question: why did I even bother to write this delete function? (cause it's pretty harmless to just leave nbpshinx's CSS file in the build directory)

gabalafou · 2025-05-27T20:28:59Z

src/pydata_sphinx_theme/nbsphinx.py

+        return
+
+    nbsphinx_css = Path(app.builder.outdir) / "_static" / "nbsphinx-code-cells.css"
+    assert nbsphinx_css.exists()


Sure I can look into changing this. I was just following the patterns in other theme functions that also use plain asserts and are called within conf.py.

Should I just get rid of the assert and allow the unlink call to throw an error if the file does not exist? That makes more sense.

I guess there is a question of intent here. My main intent of the function is the assert. The delete is really secondary. I care more about catching if the file isn't there and being alerted by a change to nbsphinx then I do about deleting the file. Does that make sense?

webpack.config.js

trallard · 2025-05-28T15:22:46Z

src/pydata_sphinx_theme/assets/styles/abstracts/_color.scss

After thinking more about this, I do not think moving the colour variables definitions to abstract while keeping the supporting functions in variables makes sense conceptually. This seems backwards and goes against the established patterns in PST, where variables, pure functions, and mixins live.

Good catch! In my latest commits, I cut the mixin I had left in variables and pasted it in abstracts.

Just to make sure we're on the same page, my understanding is:

Sass files under abstracts should NOT output any CSS; they should only define variables, functions, mixins, etc.

Sass files under variables should output CSS, and it should mostly only be CSS variable definitions

Is that correct?

That is my understanding, yes. I had initially put all the colours + functions in variables as that is where they were initially placed (back when they were all plain CSS variables, but in hindsight, I don't think this distinction was clear to me at the time and should have moved them to abstracts instead).

Sass files under abstracts should NOT output any CSS; they should only define variables, functions, mixins, etc.

Sass files under variables should output CSS, and it should mostly only be CSS variable definitions

Can this info be added to a new file src/pydata_sphinx_theme/assets/styles/README.md?

Added in latest updates!

Oh, wait. A README.md in styles/. I put a separate README in each of the two folders, abstracts and variables. Okay, will combine them into a README for the styles folder.

trallard · 2025-05-28T15:24:44Z

src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss

+  :focus-visible {
+    outline-color: #{map-deep-get($pst-semantic-colors, "accent", "light")};
+  }


Can you add a comment to this effect? Otherwise, it might surprise others who look at the code later.

trallard · 2025-05-28T15:46:18Z

src/pydata_sphinx_theme/assets/styles/nbsphinx-pydata-theme.scss

+    // TODO: add to translations
+    content: "In:";
+  }


But these in/out labels don't exist in JupyterLab or other notebook app interfaces that I have seen.

Mainly because these are not needed in an interactive context where the user gets to execute the cell and immediately see the output or result from such action. Or where this relationship is more evident.
In a static notebook version (like this in PST), there is no explicit interaction or relationship (especially if/when the output is suppressed for whatever reason), so these affordances are needed due to the lack of interactivity.

So I think it would probably make sense to translate them, or rather, to make them translatable, and leave it up to the translators to make a judgment call about whether or not it would be appropriate to translate these strings given the context.

Translators cannot decide whether these must be translated based on use/context. Once there are translation strings and added translations these will always be translated by default in all docs using PST for a given language (there is no way to turn a given translation on/off). So, a context-based translation cannot be done by translators or from a tooling POV.
So I do not think these should be translated and is in line with many discussions I have seen around whether all technical terms should always be translated. The overall consensus is that not all should be (the closest example I could find was the stdin/out one wich is generally not translated).

trallard · 2025-05-28T15:47:35Z

src/pydata_sphinx_theme/assets/styles/nbsphinx-pydata-theme.scss

+/*
+ * Syntax highlighting for console/terminal output
+ */


I have not checked nbsphinx rendering in a while, but do these meet WCAG AA contrast requirements? If not it would make sense to instead use colours more in line with our pygments style.

trallard · 2025-05-28T15:54:39Z

src/pydata_sphinx_theme/nbsphinx.py

+# This function will allow us to catch during development or CI if nbsphinx ever
+# changes the name of the CSS file where it outputs its notebook styles.


Well it deletes it but the comment makes it seem this is purposely created to check (or test) if the name has changed on the the nbsphinx side of things

trallard · 2025-05-28T15:56:18Z

src/pydata_sphinx_theme/nbsphinx.py

+        return
+
+    nbsphinx_css = Path(app.builder.outdir) / "_static" / "nbsphinx-code-cells.css"
+    assert nbsphinx_css.exists()


If the main intent is to do a "check," then an appropriate error should be thrown if such a check is not successful.

webpack.config.js

gabalafou · 2025-05-30T18:14:28Z

Okay, I just pushed a lot of changes to this PR.

tl;dr-- this PR now includes MyST-NB; there's a list of tasks remaining to do

Since I labeled this PR as do-not-merge, and we are going to wait until the 0.18 release, I thought it would be better to put everything in one big PR.

By everything, I mean instead of handling nbsphinx and MyST-NB in separate PRs, I'm handling them now in this one PR.

Finding a way to build the example notebook with both nbsphinx and MyST-NB and putting the final result in our docs was one of the trickiest parts of this PR. I settled on a strategy that's a little bit hacky but has the virtue of being pretty straightforward:

At the start of the build, copy code-cells.ipynb to a file with a special .mystnb.ipynb suffix: code-cells-myst-nb.mystnb.ipynb
In examples/index.rst, create a toctree entry to that copied-in-the-future file: code-cells-myst-nb
Update conf.py so that it maps .mystnb.ipynb files to MyST-NB and .ipynb to nbsphinx
Update code-cells.ipynb with headings that are hidden from nbsphinx when converted by MyST-NB and from MyST-NB when converted with nbsphinx.

I decided on this strategy by working backwards from what I thought would be the best end user experience. In my view, the best experience would be two pages—one labeled nbsphinx (and generated with nbsphinx), the other labeled MyST-NB (and generated with MyST-NB)—both in the same documentation hierarchy. I also wanted to avoid creating a build process with multiple sphinx-build commands and a lot of copying files around between builds.

Some known issues / to-do's:

Do a line-by-line self-review of all of my latest changes
Fix all Axe-core issues found on these two pages
Investigate and possibly fix some rendering differences between nbsphinx and MyST-NB (for example, with MyST-NB the admonition is not rendering correctly).
Document known issues with these extensions at the top of the example notebook (for example, certain outputs get doubled in MyST-NB)
Add the example notebook docs page to our accessibility tests
Figure out if there's a way to use Pygments to color the ANSI-coded strings at the bottom of the example notebook. That way we avoid having to copy-paste a bunch of color mappings from nbsphinx and MyST-NB.

Future PRs:

Restructure the Examples section. I think the examples section looks a tad messy after this PR. However, I didn't want to squeeze a re-organization of the docs into this PR. In the future, I think it would be good for each extension to get its own page in the example section.

gabalafou · 2025-05-30T19:23:03Z

Latest commit updates the PR to copy the source file at build time, rather than rely on a symlink. I will go back and edit the description and my last comment to reflect these changes.

gabalafou · 2025-05-31T11:11:37Z

I should mention that there is another way to achieve the same goal of demonstrating both nbsphinx and MyST-NB:

We can create an environment variable like PST_WHICH_NB_EXTENSION, which is set either to "nbsphinx" or "myst_nb"
In conf.py we modify the extensions list based on the value of the environment variable
We create a new project in our Read the Docs account. The new project sets the environment variable like so: PST_WHICH_NB_EXTENSION=myst_nb
The site built with MyST-NB will be available at a URL like https://pydata-sphinx-theme.readthedocs.io/en/latest/myst-nb
We create a new doc page that contains a link to the site built with MyST-NB

The reason I didn't want to go with this approach is because it adds yet another multiplying factor to the documentation variations: software version (latest, stable, old versions) times language (just "en" currently, but could be more in the future) times notebook extension (myst-nb, or default nbsphinx).

trallard · 2025-06-02T11:24:26Z

I should mention that there is another way to achieve the same goal of demonstrating both nbsphinx and MyST-NB:

I do not think that having one notebook rendered with nbsphinx or myst-nb while the rest of our docs is the same warrants the overheard of having two sites so let's leave it as is.

gabalafou changed the title ~~prettier~~ Notebook cell styling Apr 11, 2025

gabalafou marked this pull request as ready for review April 25, 2025 17:11

isabela-pf approved these changes Apr 25, 2025

View reviewed changes

maximlt mentioned this pull request Apr 26, 2025

Design interactive docs styling for rendered notebook cells Quansight-Labs/czi-scientific-python-mgmt#142

Open

5 tasks

trallard self-requested a review April 28, 2025 16:04

gabalafou changed the title ~~Notebook cell styling~~ Notebook cell styling (nbsphinx only) Apr 29, 2025

gabalafou commented May 6, 2025

View reviewed changes

gabalafou added impact: high Something that is relevant to nearly all users DO NOT MERGE There is something blocking merging this PR labels May 6, 2025

gabalafou added this to the 0.18.0 milestone May 6, 2025

gabalafou added the tag: design Items related to design tasks or improvements label May 6, 2025

drammock reviewed May 8, 2025

View reviewed changes

gabalafou added 15 commits May 27, 2025 10:55

prettier

bf1d86c

in/out labels

abb1bd3

refactor, remove tab trap (and ipympl), add comments

f60a3fa

polish

d2b2513

Add MIT License to code-cells notebook

ce7c4c4

undo change in _api.scss

5547365

fix stylelint pre-commit, better organize scss

51fc4cf

Fix math, fix alignment (use padding not margin), add more examples

76fde56

revert changes to bottom of pydata.ipynb

0e04488

add back table-layout: auto

6064059

long input and output example

5d07520

remove nbsphinx stylesheet

f752baa

fix focus ring for dark mode exceptions

f535b13

use webpack to create separate css file to overwrite

ef86d7c

be less implicit overwriting nbsphinx

877dca1

some more fixes for the rendered notebook

586d7bf

gabalafou commented May 27, 2025

View reviewed changes

gabalafou added 2 commits May 28, 2025 12:14

update nbsphinx functions based on review feedback

db7bb75

Add new CSS file to sdist

66c429d

trallard reviewed May 28, 2025

View reviewed changes

gabalafou added 10 commits May 29, 2025 13:03

move mixin to abstracts/_color.scss

13c50a2

remove TODO comments

91b6051

Environment variable to build with MyST-NB instead of nbsphinx

1dfa4d4

myst-nb styles

bc72c6e

working build

b90d26d

build still working

86aead2

make each heading specific to its extension

29f8cf8

replace myst_nb css with our css, restructure css files

c60f2e6

cleanup

82a473c

edit myst-nb css

287b6e4

gabalafou changed the title ~~Notebook cell styling (nbsphinx only)~~ Notebook cell styling (nbsphinx and MyST-NB) May 30, 2025

copy notebook at build, rather than use symlink

b92f760

update comment

f0c1605

drammock mentioned this pull request May 31, 2025

Non-legible Xarray HTML representation in dark mode #2189

Open

gabalafou and others added 5 commits June 2, 2025 06:51

Update README.md

ceb5278

[pre-commit.ci] Automatic linting and formatting fixes

96aa14e

Update README.md

547a68d

[pre-commit.ci] Automatic linting and formatting fixes

4f8ef73

styles/README

10113de

benbovy mentioned this pull request Jun 3, 2025

Switch docs to jupyter-execute sphinx extension for HTML reprs pydata/xarray#10383

Open

4 tasks

		@import "abstracts/all";

		// These files output CSS variables (not to be confused with SCSS variables)

		# This function will allow us to catch during development or CI if nbsphinx ever
		# changes the name of the CSS file where it outputs its notebook styles.

Notebook cell styling (nbsphinx and MyST-NB) #2187

Are you sure you want to change the base?

Notebook cell styling (nbsphinx and MyST-NB) #2187

Conversation

gabalafou commented Apr 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Known differences from the design

How to test this pull request

Uh oh!

isabela-pf left a comment

Choose a reason for hiding this comment

Uh oh!

gabalafou left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gabalafou commented May 6, 2025

Uh oh!

drammock left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

gabalafou commented Apr 11, 2025 •

edited

Loading

gabalafou May 9, 2025 •

edited

Loading