Update Makefile to use -j2 for parallel builds

[psobolewskiPhD]

References and relevant issues

pydata/pydata-sphinx-theme#1871 enabled parallel builds, see e.g. scipy:
scipy/scipy#20897

Description

Enables parallel building using -j2

[willingc]

@psobolewskiPhD We use the following Markefile config for jobs in CPython doc builds. We set it to auto as default since it can still be overridden on the command line.

# You can set these variables from the command line.
PYTHON       = python3
VENVDIR      = ./venv
UV           = uv
SPHINXBUILD  = PATH=$(VENVDIR)/bin:$$PATH sphinx-build
BLURB        = PATH=$(VENVDIR)/bin:$$PATH blurb
JOBS         = auto
PAPER        =
SOURCES      =
DISTVERSION  = $(shell $(PYTHON) tools/extensions/patchlevel.py)
REQUIREMENTS = requirements.txt
SPHINXERRORHANDLING = --fail-on-warning

# Internal variables.
PAPEROPT_a4     = --define latex_elements.papersize=a4paper
PAPEROPT_letter = --define latex_elements.papersize=letterpaper

ALLSPHINXOPTS = --builder $(BUILDER) \
                --doctree-dir build/doctrees \
                --jobs $(JOBS) \
                $(PAPEROPT_$(PAPER)) \
                $(SPHINXOPTS) $(SPHINXERRORHANDLING) \
                . build/$(BUILDER) $(SOURCES)

auto will use available cpus https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-j

[Czaki]

I am not convinced that it will work. We cannot make screenshots in parallel.

[psobolewskiPhD]

We actually have running -j4 in the docs contributing guide, but it fails for me locally after running though ~77% with

Sphinx parallel build error:
nbclient.exceptions.DeadKernelError: Kernel died

And when the viewers open and close I get a lot of seg faults on exit, so that could be related.

[willingc]

I think something that would be worth investing some time after release 0.6.0 would be to add more logging to the event loop especially around quitting and cleanup. It would be helpful to have more detailed logs to understand failures.

[melissawm]

nbclient is coming from myst-nb and the nbsphinx machinery. I do remember them having issues with parallel builds in the past, but haven't investigated recently.