Build the documentation in parallel by default

The docs job takes ~83m on a pull request, ~82m of which is a single serial sphinx-build. Making `-j auto` the default in doc/Makefile speeds up every caller — CI, `make docs`, and a local build — and `SPHINXOPTS=` still gives a serial build. `docs-develop` no longer needs to pass `-j 4` of its own.

sphinx.ext.viewcode is not parallelized (see 45ed317832, which added GALAXY_DOCS_SKIP_VIEW_CODE for exactly that reason), so it is skipped for pull request builds, which only need to prove the documentation still builds. Pushes, which are what gets deployed to docs.galaxyproject.org, keep the embedded highlighted source.

Measured on a pull request run: 83m to 15m.

.github/workflows/docs.yaml

@@ -57,6 +57,11 @@ jobs:
       - name: Append doc/source/conf.versioning.py
         run: cat doc/source/conf.versioning.py >> doc/source/conf.py
       - name: Build docs
+        env:
+          # sphinx.ext.viewcode is not parallelized and dominates the build.
+          # Pull request builds only need to prove the documentation still
+          # builds, so skip it there and keep it for the deployed builds.
+          GALAXY_DOCS_SKIP_VIEW_CODE: ${{ github.event_name == 'pull_request' && '1' || '0' }}
         run: make docs
       - name: Deploy docs
         if: github.event_name == 'push' && github.repository_owner == 'galaxyproject'

Makefile

@@ -43,7 +43,7 @@ docs: ## Generate HTML documentation.
 	$(IN_VENV) $(MAKE) -C doc html
 
 docs-develop: ## Fast doc generation and more warnings (for development)
-	$(IN_VENV) GALAXY_DOCS_SKIP_VIEW_CODE=1 SPHINXOPTS='-j 4' $(MAKE) -C doc html
+	$(IN_VENV) GALAXY_DOCS_SKIP_VIEW_CODE=1 $(MAKE) -C doc html
 
 setup-venv:
 	if [ ! -f $(VENV)/bin/activate ]; then bash scripts/common_startup.sh --dev-wheels; fi

doc/Makefile

@@ -2,7 +2,8 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    ?=
+# Build in parallel by default; override with `SPHINXOPTS=` for a serial build.
+SPHINXOPTS    ?= -j auto
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build