Design interactive docs styling for rendered notebook cells

[isabela-pf]

Context

As a part of this project #19, @gabalafou made changes to PyWavelets’ theme. This included implementing visual styling for notebook code cells. This is not the only project that will need or currently has notebook code cells; we need to provide a baseline styling that can be used across documentation contexts.

To be clear, this feature (rendered notebook cells) already exists across the ecosystem. The goal is to create something standard so that each project does not need to handle it fresh each time.

Proposal

I've been brought in to propose a styling that will work for multiple use cases with the goal of setting a notebook cell styling standard upstream. The changes discussed here will be proposed first to the PyData Sphinx theme by @gabalafou and I. The styling proposed needs to

• Focus on cells that don't make sense rendered as default markup, namely code cells that need their input and outputs shown
• Ensure this does not clash with the rendering of other notebook contents
• Create a baseline design with flexibility to work for a wide range of notebook code cell output types and for potential needs of different projects
• Demonstrate changes as they will appear first in the default PyData Sphinx theme

Updates and actions

• Gather and compare how other notebook code cell styling already existing in the ecosystem.
• Clarify what information we have available from the notebook code cell and potential constraints from MyST-NB and nbsphinx.
• Propose a few styling directions to the PyData Sphinx theme (with pros and cons listed for ease).
• Get review here, on the PyData Sphinx theme repo, and the Scientific Python Discourse at minimum.
• Develop changes into the PyData Sphinx Theme

As always, this this issue will be updated if this changes. Feedback is welcome and needed. Thank you in advance! 🌻

[isabela-pf]

As a first update, I am still early on in this work. I am gathering existing notebook code cells in documentation for comparison, but I don't have them all collected yet. Right now I am looking at

• PyData Sphinx theme (current)
• PyWavelets documentation
• napari documentation
• NumPy tutorials
• If the Quansight or Quansight Labs blog has notebook cell rendering
• Public notebooks from Space Telescope Science Institute
• Jupyter documentation

but would be grateful for other examples of notebooks in documentation if anyone has them. Thank you!

[agriyakhetarpal]

other examples of notebooks in documentation if anyone has them

@isabela-pf, see also: https://scipy.github.io/devdocs/tutorial/stats/hypothesis_bartlett.html for some notebooks in SciPy that make use of jupyterlite-sphinx. These are mostly the same as PyWavelets's notebooks, minus some of the customisations added to PyWavelets in PyWavelets/pywt#741.

https://sphinx-gallery.github.io/stable/configuration.html#jupyterlite also has a JuptyerLite integration. Sphinx-Gallery, in general, has had its own styling guidelines for notebook-based content – one thing of note being the difference in colours between the input cells/consoles (light gray) and the code output background (yellow). However, @gabalafou and I discussed this briefly in agriyakhetarpal/pywt#4, but chose not to align on it at that moment.

I feel that nbsphinx is as close as possible (example page built from a notebook) in terms of offering notebook rendering to Sphinx/PST's native styling.

Another reference point could be this MyST-JS-based branch for the NumPy tutorials: https://github.com/numpy/numpy-tutorials/tree/mystjs (see MyST-JS announcement blog post)

[isabela-pf]

I have an update on reviewing existing notebook code cell styling! I checked the documentation sites listed previously and have come away with the following:

• All inputs are, indeed, code. I had thought this before, but I wanted to confirm this was not an unfounded assumption of mine. While output contents can vary, input contents are code.
• All docs separate code sections, including notebook code cells, with a colored background.
• Many docs are designed like and take elements from their projects’ existing code blocks (where notebooks are not involved). Some of the docs make the two almost indistinguishable save for there being an input and an output back to back.
• Few (but some) borrow from the non-docs notebook design for input and output labels in particular. I’m referring to the bracketed run numbers like [1]:
• This sample of docs has an even split of whether or not inputs and outputs are labeled at all. However, all the ones without labels seem to be coming from the same theme and have almost the same design. The labeled ones seem to be designed. I am not confident what I want to recommend based on this information yet.
• The majority of docs do show inputs by default whether or not inputs and outputs are labeled. napari does hide inputs by default, though from having worked on napari I would guess this is because they generate their images and examples from notebooks rather than storing images in the docs repo, thus not a choice to obscure input and output more generally.

For ease of comparison, here’s a table marking traits I did and did not see in the documentation sites I reviewed for notebook cells.

Source	Code Inputs	Input Label	Output Label	Shown by Default	Colored Background	Designed like Notebook Cell	Designed like Code Block
PyWavelets	✅	✅	✅	✅	✅	❌	❌
PyData Sphinx Theme	✅	✅	✅	✅	✅	✅	✅
napari	✅	❌	❌	❌	✅	❌	✅
NumPy Tutorials	✅	❌	❌	✅	✅	❌	✅
Quansight Labs Blog	✅	✅	✅	✅	✅	❌	✅
STScI JDAT Notebooks	✅	❌	❌	✅	✅	❌	✅
GitHub Notebook Preview	✅	✅	❌	✅	✅	✅	❌
Project Jupyter Docs	✅	✅	✅	✅	✅	✅	✅
SciPy	✅	❌	❌	✅	✅	❌	✅

On the whole, this makes decisions the ecosystem is already making clear. Because we’re trying to fit within this, I think these majorities also make much of the design elements for my recommendation clear. I see the next step as mocking up what these choices (with a few variations) would look like. However, that is subject to change to as I may get feedback on this comparison that pulls us in another direction.

[rgommers]

That looks like a pretty comprehensive overview, thanks @isabela-pf!

I see the next step as mocking up what these choices (with a few variations) would look like. However, that is subject to change to as I may get feedback on this comparison that pulls us in another direction.

Perhaps feedback is in the works from 1-2 people (if so, I'm unaware - just back from holiday)? Based on the above I'm not 100% sure what to say right now - from a bit of thinking about the projects I'm familiar with, the set of traits in the columns above seem complete, and mockups sounds like a good next step to me.

[trallard]

Thanks @isabela-pf. This is informative, and I think 🎉 I agree that the best next step is to create some mockups.

[gabalafou]

On the whole, this makes decisions the ecosystem is already making clear. Because we’re trying to fit within this, I think these majorities also make much of the design elements for my recommendation clear.

💯

Looking at that table, it looks like the greatest disagreement is between the last two columns: designed like a notebook cell versus designed like a code block. Upon first glance, I thought those two columns were mutually exclusive, but then I realized they were not. Project Jupyter Docs is marked as having both. I'm curious what that means, what that looks like. Do you have a link to a page you were using as reference from the Project Jupyter Docs? (More broadly, it would be great if that table could include links to example pages.)

[isabela-pf]

Thank you all for the positive feedback! I’ll respond to questions first.

Looking at that table, it looks like the greatest disagreement is between the last two columns: designed like a notebook cell versus designed like a code block. Upon first glance, I thought those two columns were mutually exclusive, but then I realized they were not. Project Jupyter Docs is marked as having both. I'm curious what that means, what that looks like. Do you have a link to a page you were using as reference from the Project Jupyter Docs?

It’s true, I didn’t design comparisons as mutually exclusive (though they often are in practice). I think I could’ve been clearer with my categories too. “Designed like Notebook Cell” is really a comparison to the styling on run notebook cells in an active (not rendered for docs) notebook; usually this meant it labeled its inputs and outputs, displayed labels in the code font, and numbered the run order.

While “Designed like Code Block” is a comparison to that documentation’s own styling for non-notebook code blocks. This means the point of comparison was changing based on the documentation site I was on. Project Jupyter Docs’ cell styling matches both elements of the notebook cells in how they are labelled and designed and happen to match their code blocks on the docs as well. Jupyter’s Notebook Examples - Running Code was the best example I found on their documentation.

---

(More broadly, it would be great if that table could include links to example pages.)

Sure thing. It was an oversight on my part to not link the first time around.

Source	Sample Screen Shot
PyWavelets
PyData Sphinx Theme
napari
NumPy Tutorials
Quansight Labs Blog
STScI JDAT Notebooks
GitHub Notebook Preview
Project Jupyter Docs
SciPy

[isabela-pf]

From reviewing documentation sites, I find to community appears to agree on the following decisions broadly.

• Interactive docs have different styling for notebook code cells. Not for other types of cells or other notebook contents.
• Code inputs and outputs are shown by default (not collapsed or otherwise obscured), like in a notebook.
• Notebook cells in interactive docs have a colored background separating them from surrounding content, just like…
• Documentation site’s code block styling is carried over in rendered notebook code cells.

These are the traits I want to continue in whatever solution we end up with. While not every project follows them, I am finding enough consistency that I think it’s worth keeping these conventions.

I also thinks this helps up by lessening the number of unique decisions we have to make.

I’ve narrowed down my potential proposals to two (similar) options. Both of these do label notebook inputs and outputs, style their labels with the docs’ code font, and focus on the relationship between input and output—in my view the main difference between a code block and a notebook cell when reading the docs is that the code block is one unit and cells are units with relationships to one another.

Option 1-1

Straightforward, no frills code block styling in sequence. This is closest to what many projects already do with notebook code cells in their docs. There’s an input block, an output, and labels to communicate which is which.

Without project-specific styling:

Styled after PyData Sphinx theme’s current code blocks:

Option 1-2

While it keeps the labeling and code block styling from option 1-1, this option breaks from notebook convention of having the labels be to the left of the code. More vertical space is needed for this option, but it gives more room for the code itself.

Additionally, I pulled in the idea of a colored bar spanning notebook cells from Executable Book’s Sphinx Book theme which a few of the projects I reviewed seem to use. These projects do not label/number inputs and outputs, so their main differentiation between a standard code block and notebook cells is a colored bar in each of the blocks.

Without project-specific styling:

Styled after PyData Sphinx theme’s current code blocks:

[gabalafou]

I prefer the second option because documentation sites need to look good on mobile phones, where the screen real estate is very narrow. Alternatively, we could think about blending the two options: so that on desktop it looks more like the first option, whereas on mobile it looks more like the second.

[isabela-pf]

I think maintenance for having two versions will be more and I know that's usually not preferred, but it is certainly possible if it is wanted.

I'll leave more time for people to weigh in, just wanted to add that.

[isabela-pf]

I'm planning to move forward with the second option since I haven't heard otherwise. Unless there's other feedback I see in between, I'm planning to annotate the second option so that the features of the designs are made clearer for implementation.

Let me know if anything changes!