From e3d43763f895740589e6a48cb27c4d4da78e8f4f Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Mon, 29 Apr 2024 18:29:28 +0300
Subject: [PATCH 1/3] Upgrade to Sphinx 7.3

---
 Doc/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Doc/requirements.txt b/Doc/requirements.txt
index 118e6c322b4be2..15675ab45fea71 100644
--- a/Doc/requirements.txt
+++ b/Doc/requirements.txt
@@ -6,7 +6,7 @@
 # Sphinx version is pinned so that new versions that introduce new warnings
 # won't suddenly cause build failures. Updating the version is fine as long
 # as no warnings are raised by doing so.
-sphinx~=7.2.0
+sphinx~=7.3.0
 
 blurb
 

From 4ec0ff68d659d21ed6df110dc0dc380603e6bf23 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Mon, 29 Apr 2024 18:40:06 +0300
Subject: [PATCH 2/3] Use Sphinx 7.3's long options

---
 .github/workflows/reusable-docs.yml |  2 +-
 Doc/Makefile                        | 12 ++++++------
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml
index 9e26d7847d2bd3..fd519d60f324ab 100644
--- a/.github/workflows/reusable-docs.yml
+++ b/.github/workflows/reusable-docs.yml
@@ -55,7 +55,7 @@ jobs:
       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
+        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: |
diff --git a/Doc/Makefile b/Doc/Makefile
index dd068c520ad60c..436146c18ccc06 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -13,15 +13,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)

From 0a5334569fec5d01982133269b81be2845d3b5f5 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Mon, 29 Apr 2024 18:49:12 +0300
Subject: [PATCH 3/3] Keep Sphinx short options in Makefile

---
 Doc/Makefile | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Doc/Makefile b/Doc/Makefile
index 436146c18ccc06..dd068c520ad60c 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -13,15 +13,15 @@ PAPER        =
 SOURCES      =
 DISTVERSION  = $(shell $(PYTHON) tools/extensions/patchlevel.py)
 REQUIREMENTS = requirements.txt
-SPHINXERRORHANDLING = --fail-on-warning
+SPHINXERRORHANDLING = -W
 
 # Internal variables.
-PAPEROPT_a4     = --define latex_elements.papersize=a4paper
-PAPEROPT_letter = --define latex_elements.papersize=letterpaper
+PAPEROPT_a4     = -D latex_elements.papersize=a4paper
+PAPEROPT_letter = -D latex_elements.papersize=letterpaper
 
-ALLSPHINXOPTS = --builder $(BUILDER) \
-                --doctree-dir build/doctrees \
-                --jobs $(JOBS) \
+ALLSPHINXOPTS = -b $(BUILDER) \
+                -d build/doctrees \
+                -j $(JOBS) \
                 $(PAPEROPT_$(PAPER)) \
                 $(SPHINXOPTS) $(SPHINXERRORHANDLING) \
                 . build/$(BUILDER) $(SOURCES)