This commit tries to solve two problems.

• The pydata_sphinx_theme extension warning can be avoided by setting the default --jobs to 1. This matches spin test.
• The -W option is currently hardcoded in ALLSPHINXOPTS and impossible to override. This commit moves -W to SPHINXOPTS which allows a local machine to remove -W if needed, as described in the documentation. This adds to the discussion in PR DOC: Bump pydata-sphinx-theme version #26125.

[skip actions] [skip azp] [skip cirrus]

Context

While trying to build a workflow that incorporates spin docs, I encountered two issues. First, I noticed that the the following suggestion in the spin documentation was invalid.

The second issue is the known error message

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

This was fixed for those using make by removing -j2 from SPHINXOPTS. The circle build uses make but new users are directed to use spin docs. When someone runs SPHINXOPTS="-n" make -e html everything works fine. When someone runs spin docs, the generated doc build command is

LANG=C sphinx-build -b html -WT --keep-going -d build/doctrees  -j auto source build/html

The problem is -j auto. Running SPHINXOPTS="-j 1" spin docs generates

LANG=C sphinx-build -b html -WT --keep-going -d build/doctrees  -j 1 -j auto source build/html

The problem remains. Using spin docs -j 1 instead of SPHINXOPTS="-j 1" spin docs works. Discovering this fix was difficult for a newcomer, as the rest of the examples in the codebase model changing SPHINXOPTS.

I set up 7 different codespace environments, and sometimes the docs would build without errors, while other times they would fail. My best guess now is that this may have to do with how many cores -j auto was able to access on each different codespace.

Further Discussion

I'd love to change something to help newcomers so they don't have to question why their doc build gives an error message (that they can ignore). Here's some options.

• Swapping the default to 1, and later updating it back to auto when an upstream fix is found, would simplify things for newcomers. This PR follows this option. I purposefully matched the default and help from spin test.
• Alternately, we could add a note in the docs wherever spin docs appears that adds a comment to use spin docs -j 1 if they encounter a warning. IMHO, this makes it harder for newcomers to contribute. If anything, this PR will provide a record for people to find a fix.
• We could test if the pydata_sphinx_theme extension is safe for parallel writing (they fixed things upstream), and then set the default based on that. This muddies up cmds.py, but does mean the change to auto will auto happen.

As for the -W option change, I understand why we want the doc build to throw an error on numpy/numpy. Moving -W to SPHINXOPTS allows both upstream and local repos to set the option as needed.

• I left doc/neps/makefile alone. The -W command is still in ALLSPHINXOPTS. I can update that file as well, if wanted.