This change is because pydata-sphinx-theme doesn't support parallel writes: pydata/pydata-sphinx-theme#1643. It doesn't seem to impact build time significantly though, 18m19s before and 18m57s after.

Not tested with the new version, but IIRC, I got significant speedups on my local machine with -j4. If we can't have that anymore, we need to update https://matplotlib.org/devdocs/devel/document.html#build-the-docs. Also, > 10min doc build times makes working on docs very unattractive. As somebody else said

In practice, that goes from "let me quickly build the docs to see the effect of this change" to "let's just hope it renders correctly".

Are the other improvements so significant that we are willing to take this on?

Edit: or is the above comparison old version -j4 vs. new version -j1. There were other performance improvements in the pydata Sphinx theme that might just compensate the losses of non-parallel builds.

The comparison is on circleCI between 591cd65 and f178f5c, the only difference being changing -j4 to -j1. Perhaps even with -j4 circleCI wasn't using any parallelism to build the docs?

Are the other improvements so significant that we are willing to take this on?

They include at least some accesibility improvements which I would advocate for.

Note that this is changing the parallel option only for the circleCI build, not any local or other builds, so the comparison using only times measured on circleCI is fair.

And you can still use parallel options, it will just raise a warning at the end of the doc build that pydata-sphinx-theme isn't parallel write safe.

I don't see any need to change our call here. The theme marks it self as parallel-unsafe, so requesting parallel build will be turned off anyway. And then when they fix themselves, we'd need to remember to turn it back on again.

Without using -j1, shpinx emits a warning that the theme isn't parallel write safe, which fails the build. Ideally there would be a way to ignore just this warning and use -j4, but I'm not aware if that's possible with sphinx?

You could try to add a warnings filter to conf.py

Do you mean the suppress_warnings configuration? It seems to be the only relevant option to do this, but warning about a non-parallel write safe theme doesn't seem to be convered by the list of warning types that can be suppressed.

This CSS interacts badly with dark mode, and removing it (and defaulting to what pydata-sphinx-theme uses) looks fine.