https://github.com/python/cpython/commit/4967fa6a9c0db7ea3ade905d724a04688cfc7a5e
commit: 4967fa6a9c0db7ea3ade905d724a04688cfc7a5e
branch: main
author: Adam Turner <[email protected]>
committer: hugovk <[email protected]>
date: 2025-01-20T08:11:22+02:00
summary:
GH-125722: Use long options for Sphinx (#129039)
files:
M .github/workflows/reusable-docs.yml
M Doc/Makefile
M Doc/make.bat
diff --git a/.github/workflows/reusable-docs.yml
b/.github/workflows/reusable-docs.yml
index 84675fa62e1516..6738acc98c6565 100644
--- 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 4a704ad58b33d3..1a66642a4a03ed 100644
--- 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 87d8359ef112bb..ede793ed3c6d70 100644
--- 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"
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
