I think these warnings are failing the build

WARNING: the pydata_sphinx_theme extension is not safe for parallel writing
WARNING: doing serial write

Perhaps the -j will have to be removed to get a docs build

Thanks, updated!

here is an example API page. Generally it seems quite nice. I find the orange of the "See also" header a bit jarring. Do we need to remove some of our CSS styling?

Yes, that contrast needs fixing:

If we disable the :before CSS from that file:

.admonition-legacy.admonition>.admonition-title::before,
div.admonition>.admonition-title::before {
  color: var(--pst-color-warning);
  content: var(--pst-icon-admonition-attention);
  background-color: var(--pst-color-warning);
}

We get:

This CSS was added by @melissawm in #24939.

Melissa: is right thing to do, is delete div.admonition>.admonition-title::before and div.admonition>.admonition-title::after from that CSS and keep the .admonition-legacy bits?

That sounds about right, can you give it a try? Thanks for the ping!

@hugovk it looks like there's a bit of extra customization that is still causing some misalignment of items and truncation (see for example the top navbar and cards at the landing page: https://output.circle-artifacts.com/output/job/e09e4603-3ea6-4dc9-be1a-42c27782dbcd/artifacts/0/doc/build/html/index.html?pr=26125)

I'm not sure if that's from existing NumPy customization or from new PyData theme settings.

Hmm, not sure where to look for that. I did notice the some of the header elements have col-lg-3 and col-lg-9 classes, which are not used for https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html, removing those helps a bit, but I don't think that's the root issue.

https://numpy.org/doc/stable/ has a search box in the left column, not in the header like the PR preview, and the version selector is wider ("Choose version" vs. "1.26"). Deleting the col-lg- classes and search box makes the header "fit" like before...

Looks like this is a bigger job than just bumping a version and deleting some old CSS :) It might be better for someone else to continue this PR.

I can do that - thanks for getting it started! We can keep this one open and I'll push to it so you are still a co-author. Does that work for you? Thanks ❤️

Certainly! I'm not worried about co-author, feel free to push to this, close and create a new one, use or ditch my commits, or whatever is best for you. Thank you!

Hi folks - just updated this, and included some cleanup for the CSS file. If this is too much I'll understand and break it into another PR, but I figure since I needed to touch the CSS file anyway...

Here's a summary of the major changes:

• Landing page
  • Old https://numpy.org/devdocs/index.html
  • New https://output.circle-artifacts.com/output/job/af72bb8e-e5b6-425d-a47c-f0ca0cf6ed25/artifacts/0/doc/build/html/index.html?pr=26125 (the overflow in the navbar here comes from the large version switcher, I will fix in the next commit)
• Some colors and style for the API documentation. Example:
  • Old https://numpy.org/devdocs/reference/generated/numpy.bitwise_invert.html#numpy-bitwise-invert
  • New https://output.circle-artifacts.com/output/job/af72bb8e-e5b6-425d-a47c-f0ca0cf6ed25/artifacts/0/doc/build/html/reference/generated/numpy.bitwise_invert.html#numpy.bitwise_invert
• Admonition colors now inherit directly from the PyData Sphinx Theme. Example:
  • Old https://numpy.org/devdocs/building/index.html
  • New https://output.circle-artifacts.com/output/job/af72bb8e-e5b6-425d-a47c-f0ca0cf6ed25/artifacts/0/doc/build/html/building/index.html
• See also the Absolute Beginners guide which show some of the style changes
  • Old https://numpy.org/devdocs/user/absolute_beginners.html
  • New https://output.circle-artifacts.com/output/job/af72bb8e-e5b6-425d-a47c-f0ca0cf6ed25/artifacts/0/doc/build/html/user/absolute_beginners.html

Similar to scipy/scipy#20460, I'm using as much of the PyData Sphinx Theme predefined colors as possible. This means some of the NumPy colors are absent from this version. Again, if that's too aggressive I'm happy to walk those back.

Related: #25927

I will add links to the preview of the pages mentioned above as soon as CI finishes building.

Commit eb4c33d removed an unrelated file, was that on purpose?

Looks much better. The version switcher is bright red on my browser. Is that the desired color?

@mattip the version switcher is red when it displays "choose version". It should be orange on devdocs and red on older versions. On stable it has the regular background color. This is the same approach I took for scipy, but maybe the red is too much?

This is the same approach I took for scipy

Then it should be fine. Let's get this in, we can always do more later.

Thanks @hugovk, @melissawm

Thank you @melissawm!

Figured I'd add what I found to the conversation. I've been building numpy on codespaces multiple times today. Twice I've been able to build the docs without any errors. Every other time I've built the docs I've encountered the exact same warning messages with an error at the last stage of the doc build.

WARNING: the pydata_sphinx_theme extension is not safe for parallel writing
WARNING: doing serial write

I've set up 7 different codespace environments today. My best guess is that when I build the docs from the main branch, I have no issues. When I build the docs from another branch, I get the warning messages.

To build the docs with codespaces, I'm using the following 5 commands.

conda activate numpy-dev
pip install -r requirements/build_requirements.txt
spin build
pip install --pre --force-reinstall --extra-index-url https://pypi.anaconda.org/scientific-python-nightly-wheels/simple -r requirements/doc_requirements.txt
spin docs

Hi @bmwoodruff - the parallel safety warning is a known issue with the PyData Sphinx theme and something that will be fixed upstream. It should not impact the documentation build. Are you able to build despite the warning?

Hi @melissawm , the docs build and are viewable, but the ending message suggests otherwise.

build finished with problems, 2 warnings.
make: *** [Makefile:144: html-build] Error 1
make: Leaving directory '/workspaces/numpy/doc'

I tried running the docs with SPHINXOPTS="" spin docs, following