Debian Codegraph @

Doc/Makefile

raw ◀ ▶
1 Debian patch touch this file
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