| 1 |
# |
| 2 |
# Makefile for Python documentation |
| 3 |
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 4 |
# |
| 5 |
|
| 6 |
# You can set these variables from the command line. |
| 7 |
PYTHON = python3 |
| 8 |
VENVDIR = ./venv |
| 9 |
UV = uv |
| 10 |
SPHINXBUILD = PATH=$(VENVDIR)/bin:$$PATH sphinx-build |
| 11 |
BLURB = PATH=$(VENVDIR)/bin:$$PATH blurb |
| 12 |
JOBS = auto |
| 13 |
PAPER = |
| 14 |
SOURCES = |
| 15 |
DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py) |
| 16 |
REQUIREMENTS = requirements.txt |
| •17 |
#SPHINXERRORHANDLING = --fail-on-warning |
| 18 |
|
| 19 |
# Internal variables. |
| 20 |
PAPEROPT_a4 = --define latex_elements.papersize=a4paper |
| 21 |
PAPEROPT_letter = --define latex_elements.papersize=letterpaper |
| 22 |
|
| 23 |
ALLSPHINXOPTS = --builder $(BUILDER) \ |
| 24 |
--doctree-dir build/doctrees \ |
| 25 |
--jobs $(JOBS) \ |
| 26 |
$(PAPEROPT_$(PAPER)) \ |
| 27 |
$(SPHINXOPTS) $(SPHINXERRORHANDLING) \ |
| 28 |
. build/$(BUILDER) $(SOURCES) |
| 29 |
|
| 30 |
.PHONY: help |
| 31 |
help: |
| 32 |
@echo "Please use \`make <target>' where <target> is one of" |
| 33 |
@echo " clean to remove build files" |
| 34 |
@echo " venv to create a venv with necessary tools" |
| 35 |
@echo " html to make standalone HTML files" |
| 36 |
@echo " gettext to generate POT files" |
| 37 |
@echo " htmlview to open the index page built by the html target in your browser" |
| 38 |
@echo " htmllive to rebuild and reload HTML files in your browser" |
| 39 |
@echo " htmlhelp to make HTML files and a HTML help project" |
| 40 |
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" |
| 41 |
@echo " text to make plain text files" |
| 42 |
@echo " texinfo to make Texinfo file" |
| 43 |
@echo " epub to make EPUB files" |
| 44 |
@echo " changes to make an overview over all changed/added/deprecated items" |
| 45 |
@echo " linkcheck to check all external links for integrity" |
| 46 |
@echo " coverage to check documentation coverage for library and C API" |
| 47 |
@echo " doctest to run doctests in the documentation" |
| 48 |
@echo " pydoc-topics to regenerate the pydoc topics file" |
| 49 |
@echo " dist to create a \"dist\" directory with archived docs for download" |
| 50 |
@echo " check to run a check for frequent markup errors" |
| 51 |
|
| 52 |
.PHONY: build |
| 53 |
build: |
| 54 |
-mkdir -p build |
| 55 |
# Look first for a Misc/NEWS file (building from a source release tarball |
| 56 |
# or old repo) and use that, otherwise look for a Misc/NEWS.d directory |
| 57 |
# (building from a newer repo) and use blurb to generate the NEWS file. |
| 58 |
@if [ -f ../Misc/NEWS ] ; then \ |
| 59 |
echo "Using existing Misc/NEWS file"; \ |
| 60 |
cp ../Misc/NEWS build/NEWS; \ |
| 61 |
elif $(BLURB) --version && $(SPHINXBUILD) --version ; then \ |
| 62 |
if [ -d ../Misc/NEWS.d ]; then \ |
| 63 |
echo "Building NEWS from Misc/NEWS.d with blurb"; \ |
| 64 |
$(BLURB) merge -f build/NEWS; \ |
| 65 |
else \ |
| 66 |
echo "Neither Misc/NEWS.d nor Misc/NEWS found; cannot build docs"; \ |
| 67 |
exit 1; \ |
| 68 |
fi \ |
| 69 |
else \ |
| 70 |
echo ""; \ |
| 71 |
echo "Missing the required blurb or sphinx-build tools."; \ |
| 72 |
echo "Please run 'make venv' to install local copies."; \ |
| 73 |
echo ""; \ |
| 74 |
exit 1; \ |
| 75 |
fi |
| 76 |
$(SPHINXBUILD) $(ALLSPHINXOPTS) |
| 77 |
@echo |
| 78 |
|
| 79 |
.PHONY: html |
| 80 |
html: BUILDER = html |
| 81 |
html: build |
| 82 |
@echo "Build finished. The HTML pages are in build/html." |
| 83 |
|
| 84 |
.PHONY: htmlhelp |
| 85 |
htmlhelp: BUILDER = htmlhelp |
| 86 |
htmlhelp: build |
| 87 |
@echo "Build finished; now you can run HTML Help Workshop with the" \ |
| 88 |
"build/htmlhelp/pydoc.hhp project file." |
| 89 |
|
| 90 |
.PHONY: latex |
| 91 |
latex: BUILDER = latex |
| 92 |
latex: _ensure-sphinxcontrib-svg2pdfconverter |
| 93 |
$(MAKE) build BUILDER=$(BUILDER) |
| 94 |
@echo "Build finished; the LaTeX files are in build/latex." |
| 95 |
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ |
| 96 |
"run these through (pdf)latex." |
| 97 |
|
| 98 |
.PHONY: text |
| 99 |
text: BUILDER = text |
| 100 |
text: build |
| 101 |
@echo "Build finished; the text files are in build/text." |
| 102 |
|
| 103 |
.PHONY: texinfo |
| 104 |
texinfo: BUILDER = texinfo |
| 105 |
texinfo: build |
| 106 |
@echo "Build finished; the python.texi file is in build/texinfo." |
| 107 |
@echo "Run \`make info' in that directory to run it through makeinfo." |
| 108 |
|
| 109 |
.PHONY: epub |
| 110 |
epub: BUILDER = epub |
| 111 |
epub: build |
| 112 |
@echo "Build finished; the epub files are in build/epub." |
| 113 |
|
| 114 |
.PHONY: changes |
| 115 |
changes: BUILDER = changes |
| 116 |
changes: build |
| 117 |
@echo "The overview file is in build/changes." |
| 118 |
|
| 119 |
.PHONY: linkcheck |
| 120 |
linkcheck: BUILDER = linkcheck |
| 121 |
linkcheck: |
| 122 |
@$(MAKE) build BUILDER=$(BUILDER) || { \ |
| 123 |
echo "Link check complete; look for any errors in the above output" \ |
| 124 |
"or in build/$(BUILDER)/output.txt"; \ |
| 125 |
false; } |
| 126 |
|
| 127 |
.PHONY: coverage |
| 128 |
coverage: BUILDER = coverage |
| 129 |
coverage: build |
| 130 |
@echo "Coverage finished; see c.txt and python.txt in build/coverage" |
| 131 |
|
| 132 |
.PHONY: doctest |
| 133 |
doctest: BUILDER = doctest |
| 134 |
doctest: |
| 135 |
@$(MAKE) build BUILDER=$(BUILDER) || { \ |
| 136 |
echo "Testing of doctests in the sources finished, look at the" \ |
| 137 |
"results in build/doctest/output.txt"; \ |
| 138 |
false; } |
| 139 |
|
| 140 |
.PHONY: pydoc-topics |
| 141 |
pydoc-topics: BUILDER = pydoc-topics |
| 142 |
pydoc-topics: build |
| 143 |
@echo "Building finished; now run this:" \ |
| 144 |
"cp build/pydoc-topics/topics.py ../Lib/pydoc_data/topics.py" \ |
| 145 |
"&& cp build/pydoc-topics/module_docs.py ../Lib/pydoc_data/module_docs.py" |
| 146 |
|
| 147 |
.PHONY: gettext |
| 148 |
gettext: BUILDER = gettext |
| 149 |
gettext: override SPHINXOPTS := --doctree-dir build/doctrees-gettext $(SPHINXOPTS) |
| 150 |
gettext: build |
| 151 |
|
| 152 |
.PHONY: htmlview |
| 153 |
htmlview: html |
| 154 |
$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))" |
| 155 |
|
| 156 |
.PHONY: htmllive |
| 157 |
htmllive: SPHINXBUILD = PATH=$(VENVDIR)/bin:$$PATH sphinx-autobuild |
| 158 |
htmllive: SPHINXOPTS = --re-ignore="/venv/" --open-browser --delay 0 |
| 159 |
htmllive: _ensure-sphinx-autobuild html |
| 160 |
|
| 161 |
.PHONY: clean |
| 162 |
clean: clean-venv |
| 163 |
-rm -rf build/* |
| 164 |
|
| 165 |
.PHONY: clean-venv |
| 166 |
clean-venv: |
| 167 |
rm -rf $(VENVDIR) |
| 168 |
|
| 169 |
.PHONY: venv |
| 170 |
venv: |
| 171 |
@if [ -d $(VENVDIR) ] ; then \ |
| 172 |
echo "venv already exists."; \ |
| 173 |
echo "To recreate it, remove it first with \`make clean-venv'."; \ |
| 174 |
else \ |
| 175 |
set -e; \ |
| 176 |
echo "Creating venv in $(VENVDIR)"; \ |
| 177 |
if $(UV) --version >/dev/null 2>&1; then \ |
| 178 |
$(UV) venv --python=$(PYTHON) $(VENVDIR); \ |
| 179 |
VIRTUAL_ENV=$(VENVDIR) $(UV) pip install -r $(REQUIREMENTS); \ |
| 180 |
else \ |
| 181 |
$(PYTHON) -m venv $(VENVDIR); \ |
| 182 |
$(VENVDIR)/bin/python3 -m pip install --upgrade pip; \ |
| 183 |
$(VENVDIR)/bin/python3 -m pip install -r $(REQUIREMENTS); \ |
| 184 |
fi; \ |
| 185 |
echo "The venv has been created in the $(VENVDIR) directory"; \ |
| 186 |
fi |
| 187 |
|
| 188 |
.PHONY: dist-no-html |
| 189 |
dist-no-html: dist-text dist-epub dist-texinfo |
| 190 |
|
| 191 |
.PHONY: dist |
| 192 |
dist: |
| 193 |
rm -rf dist |
| 194 |
mkdir -p dist |
| 195 |
$(MAKE) dist-html |
| 196 |
$(MAKE) dist-text |
| 197 |
$(MAKE) dist-pdf |
| 198 |
$(MAKE) dist-epub |
| 199 |
$(MAKE) dist-texinfo |
| 200 |
|
| 201 |
.PHONY: dist-html |
| 202 |
dist-html: |
| 203 |
# archive the HTML |
| 204 |
@echo "Building HTML..." |
| 205 |
mkdir -p dist |
| 206 |
rm -rf build/html |
| 207 |
find dist -name 'python-$(DISTVERSION)-docs-html*' -exec rm -rf {} \; |
| 208 |
$(MAKE) html |
| 209 |
cp -pPR build/html dist/python-$(DISTVERSION)-docs-html |
| 210 |
rm -rf dist/python-$(DISTVERSION)-docs-html/_images/social_previews/ |
| 211 |
tar -C dist -cf dist/python-$(DISTVERSION)-docs-html.tar python-$(DISTVERSION)-docs-html |
| 212 |
bzip2 -9 -k dist/python-$(DISTVERSION)-docs-html.tar |
| 213 |
(cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-html.zip python-$(DISTVERSION)-docs-html) |
| 214 |
rm -r dist/python-$(DISTVERSION)-docs-html |
| 215 |
rm dist/python-$(DISTVERSION)-docs-html.tar |
| 216 |
@echo "Build finished and archived!" |
| 217 |
|
| 218 |
.PHONY: dist-text |
| 219 |
dist-text: |
| 220 |
# archive the text build |
| 221 |
@echo "Building text..." |
| 222 |
mkdir -p dist |
| 223 |
rm -rf build/text |
| 224 |
find dist -name 'python-$(DISTVERSION)-docs-text*' -exec rm -rf {} \; |
| 225 |
$(MAKE) text |
| 226 |
cp -pPR build/text dist/python-$(DISTVERSION)-docs-text |
| 227 |
tar -C dist -cf dist/python-$(DISTVERSION)-docs-text.tar python-$(DISTVERSION)-docs-text |
| 228 |
bzip2 -9 -k dist/python-$(DISTVERSION)-docs-text.tar |
| 229 |
(cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-text.zip python-$(DISTVERSION)-docs-text) |
| 230 |
rm -r dist/python-$(DISTVERSION)-docs-text |
| 231 |
rm dist/python-$(DISTVERSION)-docs-text.tar |
| 232 |
@echo "Build finished and archived!" |
| 233 |
|
| 234 |
.PHONY: dist-pdf |
| 235 |
dist-pdf: _ensure-sphinxcontrib-svg2pdfconverter |
| 236 |
# archive the A4 latex |
| 237 |
@echo "Building LaTeX (A4 paper)..." |
| 238 |
mkdir -p dist |
| 239 |
rm -rf build/latex |
| 240 |
find dist -name 'python-$(DISTVERSION)-docs-pdf*' -exec rm -rf {} \; |
| 241 |
$(MAKE) latex PAPER=a4 |
| 242 |
# remove zip & bz2 dependency on all-pdf, |
| 243 |
# as otherwise the full latexmk process is run twice. |
| 244 |
# ($$ is needed to escape the $; https://www.gnu.org/software/make/manual/make.html#Basics-of-Variable-References) |
| 245 |
-sed -i 's/: all-$$(FMT)/:/' build/latex/Makefile |
| 246 |
if [ -n "$(filter output-sync,$(value .FEATURES))" ]; then OUTPUTSYNC=--output-sync; else OUTPUTSYNC=; fi && \ |
| 247 |
(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=$$((`getconf _NPROCESSORS_ONLN`+1)) $$OUTPUTSYNC LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2) |
| 248 |
cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip |
| 249 |
cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2 |
| 250 |
@echo "Build finished and archived!" |
| 251 |
|
| 252 |
.PHONY: dist-epub |
| 253 |
dist-epub: |
| 254 |
# copy the epub build |
| 255 |
@echo "Building EPUB..." |
| 256 |
mkdir -p dist |
| 257 |
rm -rf build/epub |
| 258 |
rm -f dist/python-$(DISTVERSION)-docs.epub |
| 259 |
$(MAKE) epub |
| 260 |
cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub |
| 261 |
@echo "Build finished and archived!" |
| 262 |
|
| 263 |
.PHONY: dist-texinfo |
| 264 |
dist-texinfo: |
| 265 |
# archive the texinfo build |
| 266 |
@echo "Building Texinfo..." |
| 267 |
mkdir -p dist |
| 268 |
rm -rf build/texinfo |
| 269 |
find dist -name 'python-$(DISTVERSION)-docs-texinfo*' -exec rm -rf {} \; |
| 270 |
$(MAKE) texinfo |
| 271 |
$(MAKE) info --directory=build/texinfo |
| 272 |
cp -pPR build/texinfo dist/python-$(DISTVERSION)-docs-texinfo |
| 273 |
tar -C dist -cf dist/python-$(DISTVERSION)-docs-texinfo.tar python-$(DISTVERSION)-docs-texinfo |
| 274 |
bzip2 -9 -k dist/python-$(DISTVERSION)-docs-texinfo.tar |
| 275 |
(cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-texinfo.zip python-$(DISTVERSION)-docs-texinfo) |
| 276 |
rm -r dist/python-$(DISTVERSION)-docs-texinfo |
| 277 |
rm dist/python-$(DISTVERSION)-docs-texinfo.tar |
| 278 |
@echo "Build finished and archived!" |
| 279 |
|
| 280 |
.PHONY: _ensure-package |
| 281 |
_ensure-package: venv |
| 282 |
if $(UV) --version >/dev/null 2>&1; then \ |
| 283 |
VIRTUAL_ENV=$(VENVDIR) $(UV) pip install $(PACKAGE); \ |
| 284 |
else \ |
| 285 |
$(VENVDIR)/bin/python3 -m pip install $(PACKAGE); \ |
| 286 |
fi |
| 287 |
|
| 288 |
.PHONY: _ensure-pre-commit |
| 289 |
_ensure-pre-commit: |
| 290 |
$(MAKE) _ensure-package PACKAGE=pre-commit |
| 291 |
|
| 292 |
.PHONY: _ensure-sphinx-autobuild |
| 293 |
_ensure-sphinx-autobuild: |
| 294 |
$(MAKE) _ensure-package PACKAGE=sphinx-autobuild |
| 295 |
|
| 296 |
.PHONY: _ensure-sphinxcontrib-svg2pdfconverter |
| 297 |
_ensure-sphinxcontrib-svg2pdfconverter: |
| 298 |
$(MAKE) _ensure-package PACKAGE=sphinxcontrib-svg2pdfconverter |
| 299 |
|
| 300 |
.PHONY: check |
| 301 |
check: _ensure-pre-commit |
| 302 |
$(VENVDIR)/bin/python3 -m pre_commit run --all-files |
| 303 |
|
| 304 |
.PHONY: serve |
| 305 |
serve: |
| 306 |
@echo "The serve target was removed, use htmllive instead (see gh-80510)" |
| 307 |
|
| 308 |
# Targets for daily automated doc build |
| 309 |
# By default, Sphinx only rebuilds pages where the page content has changed. |
| 310 |
# This means it doesn't always pick up changes to preferred link targets, etc |
| 311 |
# To ensure such changes are picked up, we build the published docs with |
| 312 |
# ``--fresh-env`` (to ignore the cached environment) and ``--write-all`` |
| 313 |
# (to ignore already existing output files) |
| 314 |
|
| 315 |
# for development releases: always build |
| 316 |
.PHONY: autobuild-dev |
| 317 |
autobuild-dev: DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py --short) |
| 318 |
autobuild-dev: |
| 319 |
$(MAKE) dist-no-html SPHINXOPTS='$(SPHINXOPTS) --fresh-env --write-all --html-define daily=1' DISTVERSION=$(DISTVERSION) |
| 320 |
|
| 321 |
# for HTML-only rebuilds |
| 322 |
.PHONY: autobuild-dev-html |
| 323 |
autobuild-dev-html: DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py --short) |
| 324 |
autobuild-dev-html: |
| 325 |
$(MAKE) dist-html SPHINXOPTS='$(SPHINXOPTS) --fresh-env --write-all --html-define daily=1' DISTVERSION=$(DISTVERSION) |
| 326 |
|
| 327 |
# for stable releases: only build if not in pre-release stage (alpha, beta) |
| 328 |
# release candidate downloads are okay, since the stable tree can be in that stage |
| 329 |
.PHONY: autobuild-stable |
| 330 |
autobuild-stable: |
| 331 |
@case $(DISTVERSION) in *[ab]*) \ |
| 332 |
echo "Not building; $(DISTVERSION) is not a release version."; \ |
| 333 |
exit 1;; \ |
| 334 |
esac |
| 335 |
@$(MAKE) autobuild-dev |
| 336 |
|
| 337 |
.PHONY: autobuild-stable-html |
| 338 |
autobuild-stable-html: |
| 339 |
@case $(DISTVERSION) in *[ab]*) \ |
| 340 |
echo "Not building; $(DISTVERSION) is not a release version."; \ |
| 341 |
exit 1;; \ |
| 342 |
esac |
| 343 |
@$(MAKE) autobuild-dev-html |
| 344 |
|
| 345 |
# Collect HTML IDs to a JSON document |
| 346 |
.PHONY: html-ids |
| 347 |
html-ids: |
| 348 |
$(PYTHON) tools/check-html-ids.py collect build/html \ |
| 349 |
-o build/html/html-ids.json.gz |