GH-125722: Use long options for Sphinx (#129039)

diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml
index 84675fa62e15164ae28e2cb8103093a12ec777e3..6738acc98c65656f903f3b103be0a71d1df7129b 100644 (file)
--- a/.github/workflows/reusable-docs.yml
+++ b/.github/workflows/reusable-docs.yml
@@ -65,8 +65,8 @@ jobs:
       continue-on-error: true
       run: |
         set -Eeuo pipefail
-        # Build docs with the '-n' (nit-picky) option; write warnings to file
-        make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going -w sphinx-warnings.txt" html
+        # Build docs with the nit-picky option; write warnings to file
+        make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --nitpicky --fail-on-warning --keep-going --warning-file sphinx-warnings.txt" html
     - name: 'Check warnings'
       if: github.event_name == 'pull_request'
       run: |
@@ -101,4 +101,4 @@ jobs:
       run: make -C Doc/ PYTHON=../python venv
     # Use "xvfb-run" since some doctest tests open GUI windows
     - name: 'Run documentation doctest'
-      run: xvfb-run make -C Doc/ PYTHON=../python SPHINXERRORHANDLING="-W --keep-going" doctest
+      run: xvfb-run make -C Doc/ PYTHON=../python SPHINXERRORHANDLING="--fail-on-warning --keep-going" doctest

diff --git a/Doc/Makefile b/Doc/Makefile
index 4a704ad58b33d31f8ccc2c08ddab49d94665a308..1a66642a4a03ede3bed04ed83778f76877e7d8e5 100644 (file)
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -14,15 +14,15 @@ PAPER        =
 SOURCES      =
 DISTVERSION  = $(shell $(PYTHON) tools/extensions/patchlevel.py)
 REQUIREMENTS = requirements.txt
-SPHINXERRORHANDLING = -W
+SPHINXERRORHANDLING = --fail-on-warning
 
 # Internal variables.
-PAPEROPT_a4     = -D latex_elements.papersize=a4paper
-PAPEROPT_letter = -D latex_elements.papersize=letterpaper
+PAPEROPT_a4     = --define latex_elements.papersize=a4paper
+PAPEROPT_letter = --define latex_elements.papersize=letterpaper
 
-ALLSPHINXOPTS = -b $(BUILDER) \
-                -d build/doctrees \
-                -j $(JOBS) \
+ALLSPHINXOPTS = --builder $(BUILDER) \
+                --doctree-dir build/doctrees \
+                --jobs $(JOBS) \
                 $(PAPEROPT_$(PAPER)) \
                 $(SPHINXOPTS) $(SPHINXERRORHANDLING) \
                 . build/$(BUILDER) $(SOURCES)
@@ -144,7 +144,7 @@ pydoc-topics: build
 
 .PHONY: gettext
 gettext: BUILDER = gettext
-gettext: override SPHINXOPTS := -d build/doctrees-gettext $(SPHINXOPTS)
+gettext: override SPHINXOPTS := --doctree-dir build/doctrees-gettext $(SPHINXOPTS)
 gettext: build
 
 .PHONY: htmlview
@@ -300,20 +300,20 @@ serve:
 # By default, Sphinx only rebuilds pages where the page content has changed.
 # This means it doesn't always pick up changes to preferred link targets, etc
 # To ensure such changes are picked up, we build the published docs with
-# `-E` (to ignore the cached environment) and `-a` (to ignore already existing
-# output files)
+# ``--fresh-env`` (to ignore the cached environment) and ``--write-all``
+# (to ignore already existing output files)
 
 # for development releases: always build
 .PHONY: autobuild-dev
 autobuild-dev: DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py --short)
 autobuild-dev:
-       $(MAKE) dist-no-html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1' DISTVERSION=$(DISTVERSION)
+       $(MAKE) dist-no-html SPHINXOPTS='$(SPHINXOPTS) --fresh-env --write-all --html-define daily=1' DISTVERSION=$(DISTVERSION)
 
 # for HTML-only rebuilds
 .PHONY: autobuild-dev-html
 autobuild-dev-html: DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py --short)
 autobuild-dev-html:
-       $(MAKE) dist-html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1' DISTVERSION=$(DISTVERSION)
+       $(MAKE) dist-html SPHINXOPTS='$(SPHINXOPTS) --fresh-env --write-all --html-define daily=1' DISTVERSION=$(DISTVERSION)
 
 # for stable releases: only build if not in pre-release stage (alpha, beta)
 # release candidate downloads are okay, since the stable tree can be in that stage

diff --git a/Doc/make.bat b/Doc/make.bat
index 87d8359ef112bbab1c2f22a6afd16be9925ca147..ede793ed3c6d706c8a62b44ee2e76f1f383aa154 100644 (file)
--- a/Doc/make.bat
+++ b/Doc/make.bat
@@ -144,12 +144,12 @@ if exist ..\Misc\NEWS (
 )
 
 if defined PAPER (
-    set SPHINXOPTS=-D latex_elements.papersize=%PAPER% %SPHINXOPTS%
+    set SPHINXOPTS=--define latex_elements.papersize=%PAPER% %SPHINXOPTS%
 )
 if "%1" EQU "htmlhelp" (
-    set SPHINXOPTS=-D html_theme_options.body_max_width=none %SPHINXOPTS%
+    set SPHINXOPTS=--define html_theme_options.body_max_width=none %SPHINXOPTS%
 )
-cmd /S /C "%SPHINXBUILD% %SPHINXOPTS% -b%1 -dbuild\doctrees . "%BUILDDIR%\%1" %2 %3 %4 %5 %6 %7 %8 %9"
+cmd /S /C "%SPHINXBUILD% %SPHINXOPTS% --builder %1 --doctree-dir build\doctrees . "%BUILDDIR%\%1" %2 %3 %4 %5 %6 %7 %8 %9"
 
 if "%1" EQU "htmlhelp" (
     "%HTMLHELP%" "%BUILDDIR%\htmlhelp\python%DISTVERSION:.=%.hhp"