Debian Codegraph @

Doc/Makefile

raw
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: build
93 @echo "Build finished; the LaTeX files are in build/latex."
94 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
95 "run these through (pdf)latex."
96
97 .PHONY: text
98 text: BUILDER = text
99 text: build
100 @echo "Build finished; the text files are in build/text."
101
102 .PHONY: texinfo
103 texinfo: BUILDER = texinfo
104 texinfo: build
105 @echo "Build finished; the python.texi file is in build/texinfo."
106 @echo "Run \`make info' in that directory to run it through makeinfo."
107
108 .PHONY: epub
109 epub: BUILDER = epub
110 epub: build
111 @echo "Build finished; the epub files are in build/epub."
112
113 .PHONY: changes
114 changes: BUILDER = changes
115 changes: build
116 @echo "The overview file is in build/changes."
117
118 .PHONY: linkcheck
119 linkcheck: BUILDER = linkcheck
120 linkcheck:
121 @$(MAKE) build BUILDER=$(BUILDER) || { \
122 echo "Link check complete; look for any errors in the above output" \
123 "or in build/$(BUILDER)/output.txt"; \
124 false; }
125
126 .PHONY: coverage
127 coverage: BUILDER = coverage
128 coverage: build
129 @echo "Coverage finished; see c.txt and python.txt in build/coverage"
130
131 .PHONY: doctest
132 doctest: BUILDER = doctest
133 doctest:
134 @$(MAKE) build BUILDER=$(BUILDER) || { \
135 echo "Testing of doctests in the sources finished, look at the" \
136 "results in build/doctest/output.txt"; \
137 false; }
138
139 .PHONY: pydoc-topics
140 pydoc-topics: BUILDER = pydoc-topics
141 pydoc-topics: build
142 @echo "Building finished; now run this:" \
143 "cp build/pydoc-topics/topics.py ../Lib/pydoc_data/topics.py" \
144 "&& cp build/pydoc-topics/module_docs.py ../Lib/pydoc_data/module_docs.py"
145
146 .PHONY: gettext
147 gettext: BUILDER = gettext
148 gettext: override SPHINXOPTS := --doctree-dir build/doctrees-gettext $(SPHINXOPTS)
149 gettext: build
150
151 .PHONY: htmlview
152 htmlview: html
153 $(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))"
154
155 .PHONY: htmllive
156 htmllive: SPHINXBUILD = PATH=$(VENVDIR)/bin:$$PATH sphinx-autobuild
157 htmllive: SPHINXOPTS = --re-ignore="/venv/" --open-browser --delay 0
158 htmllive: _ensure-sphinx-autobuild html
159
160 .PHONY: clean
161 clean: clean-venv
162 -rm -rf build/*
163
164 .PHONY: clean-venv
165 clean-venv:
166 rm -rf $(VENVDIR)
167
168 .PHONY: venv
169 venv:
170 @if [ -d $(VENVDIR) ] ; then \
171 echo "venv already exists."; \
172 echo "To recreate it, remove it first with \`make clean-venv'."; \
173 else \
174 set -e; \
175 echo "Creating venv in $(VENVDIR)"; \
176 if $(UV) --version >/dev/null 2>&1; then \
177 $(UV) venv --python=$(PYTHON) $(VENVDIR); \
178 VIRTUAL_ENV=$(VENVDIR) $(UV) pip install -r $(REQUIREMENTS); \
179 else \
180 $(PYTHON) -m venv $(VENVDIR); \
181 $(VENVDIR)/bin/python3 -m pip install --upgrade pip; \
182 $(VENVDIR)/bin/python3 -m pip install -r $(REQUIREMENTS); \
183 fi; \
184 echo "The venv has been created in the $(VENVDIR) directory"; \
185 fi
186
187 .PHONY: dist-no-html
188 dist-no-html: dist-text dist-epub dist-texinfo
189
190 .PHONY: dist
191 dist:
192 rm -rf dist
193 mkdir -p dist
194 $(MAKE) dist-html
195 $(MAKE) dist-text
196 $(MAKE) dist-pdf
197 $(MAKE) dist-epub
198 $(MAKE) dist-texinfo
199
200 .PHONY: dist-html
201 dist-html:
202 # archive the HTML
203 @echo "Building HTML..."
204 mkdir -p dist
205 rm -rf build/html
206 find dist -name 'python-$(DISTVERSION)-docs-html*' -exec rm -rf {} \;
207 $(MAKE) html
208 cp -pPR build/html dist/python-$(DISTVERSION)-docs-html
209 rm -rf dist/python-$(DISTVERSION)-docs-html/_images/social_previews/
210 tar -C dist -cf dist/python-$(DISTVERSION)-docs-html.tar python-$(DISTVERSION)-docs-html
211 bzip2 -9 -k dist/python-$(DISTVERSION)-docs-html.tar
212 (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-html.zip python-$(DISTVERSION)-docs-html)
213 rm -r dist/python-$(DISTVERSION)-docs-html
214 rm dist/python-$(DISTVERSION)-docs-html.tar
215 @echo "Build finished and archived!"
216
217 .PHONY: dist-text
218 dist-text:
219 # archive the text build
220 @echo "Building text..."
221 mkdir -p dist
222 rm -rf build/text
223 find dist -name 'python-$(DISTVERSION)-docs-text*' -exec rm -rf {} \;
224 $(MAKE) text
225 cp -pPR build/text dist/python-$(DISTVERSION)-docs-text
226 tar -C dist -cf dist/python-$(DISTVERSION)-docs-text.tar python-$(DISTVERSION)-docs-text
227 bzip2 -9 -k dist/python-$(DISTVERSION)-docs-text.tar
228 (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-text.zip python-$(DISTVERSION)-docs-text)
229 rm -r dist/python-$(DISTVERSION)-docs-text
230 rm dist/python-$(DISTVERSION)-docs-text.tar
231 @echo "Build finished and archived!"
232
233 .PHONY: dist-pdf
234 dist-pdf:
235 # archive the A4 latex
236 @echo "Building LaTeX (A4 paper)..."
237 mkdir -p dist
238 rm -rf build/latex
239 find dist -name 'python-$(DISTVERSION)-docs-pdf*' -exec rm -rf {} \;
240 $(MAKE) latex PAPER=a4
241 # remove zip & bz2 dependency on all-pdf,
242 # as otherwise the full latexmk process is run twice.
243 # ($$ is needed to escape the $; https://www.gnu.org/software/make/manual/make.html#Basics-of-Variable-References)
244 -sed -i 's/: all-$$(FMT)/:/' build/latex/Makefile
245 if [ -n "$(filter output-sync,$(value .FEATURES))" ]; then OUTPUTSYNC=--output-sync; else OUTPUTSYNC=; fi && \
246 (cd build/latex; $(MAKE) clean && $(MAKE) --jobs=$$((`getconf _NPROCESSORS_ONLN`+1)) $$OUTPUTSYNC LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
247 cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
248 cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
249 @echo "Build finished and archived!"
250
251 .PHONY: dist-epub
252 dist-epub:
253 # copy the epub build
254 @echo "Building EPUB..."
255 mkdir -p dist
256 rm -rf build/epub
257 rm -f dist/python-$(DISTVERSION)-docs.epub
258 $(MAKE) epub
259 cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub
260 @echo "Build finished and archived!"
261
262 .PHONY: dist-texinfo
263 dist-texinfo:
264 # archive the texinfo build
265 @echo "Building Texinfo..."
266 mkdir -p dist
267 rm -rf build/texinfo
268 find dist -name 'python-$(DISTVERSION)-docs-texinfo*' -exec rm -rf {} \;
269 $(MAKE) texinfo
270 $(MAKE) info --directory=build/texinfo
271 cp -pPR build/texinfo dist/python-$(DISTVERSION)-docs-texinfo
272 tar -C dist -cf dist/python-$(DISTVERSION)-docs-texinfo.tar python-$(DISTVERSION)-docs-texinfo
273 bzip2 -9 -k dist/python-$(DISTVERSION)-docs-texinfo.tar
274 (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-texinfo.zip python-$(DISTVERSION)-docs-texinfo)
275 rm -r dist/python-$(DISTVERSION)-docs-texinfo
276 rm dist/python-$(DISTVERSION)-docs-texinfo.tar
277 @echo "Build finished and archived!"
278
279 .PHONY: _ensure-package
280 _ensure-package: venv
281 if $(UV) --version >/dev/null 2>&1; then \
282 VIRTUAL_ENV=$(VENVDIR) $(UV) pip install $(PACKAGE); \
283 else \
284 $(VENVDIR)/bin/python3 -m pip install $(PACKAGE); \
285 fi
286
287 .PHONY: _ensure-pre-commit
288 _ensure-pre-commit:
289 $(MAKE) _ensure-package PACKAGE=pre-commit
290
291 .PHONY: _ensure-sphinx-autobuild
292 _ensure-sphinx-autobuild:
293 $(MAKE) _ensure-package PACKAGE=sphinx-autobuild
294
295 .PHONY: check
296 check: _ensure-pre-commit
297 $(VENVDIR)/bin/python3 -m pre_commit run --all-files
298
299 .PHONY: serve
300 serve:
301 @echo "The serve target was removed, use htmllive instead (see gh-80510)"
302
303 # Targets for daily automated doc build
304 # By default, Sphinx only rebuilds pages where the page content has changed.
305 # This means it doesn't always pick up changes to preferred link targets, etc
306 # To ensure such changes are picked up, we build the published docs with
307 # ``--fresh-env`` (to ignore the cached environment) and ``--write-all``
308 # (to ignore already existing output files)
309
310 # for development releases: always build
311 .PHONY: autobuild-dev
312 autobuild-dev: DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py --short)
313 autobuild-dev:
314 $(MAKE) dist-no-html SPHINXOPTS='$(SPHINXOPTS) --fresh-env --write-all --html-define daily=1' DISTVERSION=$(DISTVERSION)
315
316 # for HTML-only rebuilds
317 .PHONY: autobuild-dev-html
318 autobuild-dev-html: DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py --short)
319 autobuild-dev-html:
320 $(MAKE) dist-html SPHINXOPTS='$(SPHINXOPTS) --fresh-env --write-all --html-define daily=1' DISTVERSION=$(DISTVERSION)
321
322 # for stable releases: only build if not in pre-release stage (alpha, beta)
323 # release candidate downloads are okay, since the stable tree can be in that stage
324 .PHONY: autobuild-stable
325 autobuild-stable:
326 @case $(DISTVERSION) in *[ab]*) \
327 echo "Not building; $(DISTVERSION) is not a release version."; \
328 exit 1;; \
329 esac
330 @$(MAKE) autobuild-dev
331
332 .PHONY: autobuild-stable-html
333 autobuild-stable-html:
334 @case $(DISTVERSION) in *[ab]*) \
335 echo "Not building; $(DISTVERSION) is not a release version."; \
336 exit 1;; \
337 esac
338 @$(MAKE) autobuild-dev-html