1# 2# Makefile for Python documentation 3# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4# 5 6# You can set these variables from the command line. 7PYTHON = python3 8VENVDIR = ./venv 9SPHINXBUILD = PATH=$(VENVDIR)/bin:$$PATH sphinx-build 10SPHINXLINT = PATH=$(VENVDIR)/bin:$$PATH sphinx-lint 11BLURB = PATH=$(VENVDIR)/bin:$$PATH blurb 12JOBS = auto 13PAPER = 14SOURCES = 15DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py) 16REQUIREMENTS = requirements.txt 17SPHINXERRORHANDLING = -W 18 19# Internal variables. 20PAPEROPT_a4 = -D latex_elements.papersize=a4paper 21PAPEROPT_letter = -D latex_elements.papersize=letterpaper 22 23ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees $(PAPEROPT_$(PAPER)) -j $(JOBS) \ 24 $(SPHINXOPTS) $(SPHINXERRORHANDLING) . build/$(BUILDER) $(SOURCES) 25 26.PHONY: help build html htmlhelp latex text texinfo changes linkcheck \ 27 suspicious coverage doctest pydoc-topics htmlview clean dist check serve \ 28 autobuild-dev autobuild-stable venv 29 30help: 31 @echo "Please use \`make <target>' where <target> is one of" 32 @echo " clean to remove build files" 33 @echo " venv to create a venv with necessary tools" 34 @echo " html to make standalone HTML files" 35 @echo " htmlview to open the index page built by the html target in your browser" 36 @echo " htmlhelp to make HTML files and a HTML help project" 37 @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 38 @echo " text to make plain text files" 39 @echo " texinfo to make Texinfo file" 40 @echo " epub to make EPUB files" 41 @echo " changes to make an overview over all changed/added/deprecated items" 42 @echo " linkcheck to check all external links for integrity" 43 @echo " coverage to check documentation coverage for library and C API" 44 @echo " doctest to run doctests in the documentation" 45 @echo " pydoc-topics to regenerate the pydoc topics file" 46 @echo " dist to create a \"dist\" directory with archived docs for download" 47 @echo " suspicious to check for suspicious markup in output text" 48 @echo " check to run a check for frequent markup errors" 49 50build: 51 -mkdir -p build 52# Look first for a Misc/NEWS file (building from a source release tarball 53# or old repo) and use that, otherwise look for a Misc/NEWS.d directory 54# (building from a newer repo) and use blurb to generate the NEWS file. 55 @if [ -f ../Misc/NEWS ] ; then \ 56 echo "Using existing Misc/NEWS file"; \ 57 cp ../Misc/NEWS build/NEWS; \ 58 elif $(BLURB) help >/dev/null 2>&1 && $(SPHINXBUILD) --version >/dev/null 2>&1; then \ 59 if [ -d ../Misc/NEWS.d ]; then \ 60 echo "Building NEWS from Misc/NEWS.d with blurb"; \ 61 $(BLURB) merge -f build/NEWS; \ 62 else \ 63 echo "Neither Misc/NEWS.d nor Misc/NEWS found; cannot build docs"; \ 64 exit 1; \ 65 fi \ 66 else \ 67 echo ""; \ 68 echo "Missing the required blurb or sphinx-build tools."; \ 69 echo "Please run 'make venv' to install local copies."; \ 70 echo ""; \ 71 exit 1; \ 72 fi 73 $(SPHINXBUILD) $(ALLSPHINXOPTS) 74 @echo 75 76html: BUILDER = html 77html: build 78 @echo "Build finished. The HTML pages are in build/html." 79 80htmlhelp: BUILDER = htmlhelp 81htmlhelp: build 82 @echo "Build finished; now you can run HTML Help Workshop with the" \ 83 "build/htmlhelp/pydoc.hhp project file." 84 85latex: BUILDER = latex 86latex: build 87 @echo "Build finished; the LaTeX files are in build/latex." 88 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ 89 "run these through (pdf)latex." 90 91text: BUILDER = text 92text: build 93 @echo "Build finished; the text files are in build/text." 94 95texinfo: BUILDER = texinfo 96texinfo: build 97 @echo "Build finished; the python.texi file is in build/texinfo." 98 @echo "Run \`make info' in that directory to run it through makeinfo." 99 100epub: BUILDER = epub 101epub: build 102 @echo "Build finished; the epub files are in build/epub." 103 104changes: BUILDER = changes 105changes: build 106 @echo "The overview file is in build/changes." 107 108linkcheck: BUILDER = linkcheck 109linkcheck: 110 @$(MAKE) build BUILDER=$(BUILDER) || { \ 111 echo "Link check complete; look for any errors in the above output" \ 112 "or in build/$(BUILDER)/output.txt"; \ 113 false; } 114 115suspicious: BUILDER = suspicious 116suspicious: 117 @$(MAKE) build BUILDER=$(BUILDER) || { \ 118 echo "Suspicious check complete; look for any errors in the above output" \ 119 "or in build/$(BUILDER)/suspicious.csv. If all issues are false" \ 120 "positives, append that file to tools/susp-ignored.csv."; \ 121 false; } 122 @echo "⚠ make suspicious is deprecated and will be removed soon." 123 @echo "⚠ Use:" 124 @echo "⚠ make check" 125 @echo "⚠ instead." 126 127coverage: BUILDER = coverage 128coverage: build 129 @echo "Coverage finished; see c.txt and python.txt in build/coverage" 130 131doctest: BUILDER = doctest 132doctest: 133 @$(MAKE) build BUILDER=$(BUILDER) || { \ 134 echo "Testing of doctests in the sources finished, look at the" \ 135 "results in build/doctest/output.txt"; \ 136 false; } 137 138pydoc-topics: BUILDER = pydoc-topics 139pydoc-topics: build 140 @echo "Building finished; now run this:" \ 141 "cp build/pydoc-topics/topics.py ../Lib/pydoc_data/topics.py" 142 143htmlview: html 144 $(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))" 145 146clean: clean-venv 147 -rm -rf build/* 148 149clean-venv: 150 rm -rf $(VENVDIR) 151 152venv: 153 @if [ -d $(VENVDIR) ] ; then \ 154 echo "venv already exists."; \ 155 echo "To recreate it, remove it first with \`make clean-venv'."; \ 156 else \ 157 $(PYTHON) -m venv $(VENVDIR); \ 158 $(VENVDIR)/bin/python3 -m pip install --upgrade pip; \ 159 $(VENVDIR)/bin/python3 -m pip install -r $(REQUIREMENTS); \ 160 echo "The venv has been created in the $(VENVDIR) directory"; \ 161 fi 162 163dist: 164 rm -rf dist 165 mkdir -p dist 166 167 # archive the HTML 168 make html 169 cp -pPR build/html dist/python-$(DISTVERSION)-docs-html 170 tar -C dist -cf dist/python-$(DISTVERSION)-docs-html.tar python-$(DISTVERSION)-docs-html 171 bzip2 -9 -k dist/python-$(DISTVERSION)-docs-html.tar 172 (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-html.zip python-$(DISTVERSION)-docs-html) 173 rm -r dist/python-$(DISTVERSION)-docs-html 174 rm dist/python-$(DISTVERSION)-docs-html.tar 175 176 # archive the text build 177 make text 178 cp -pPR build/text dist/python-$(DISTVERSION)-docs-text 179 tar -C dist -cf dist/python-$(DISTVERSION)-docs-text.tar python-$(DISTVERSION)-docs-text 180 bzip2 -9 -k dist/python-$(DISTVERSION)-docs-text.tar 181 (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-text.zip python-$(DISTVERSION)-docs-text) 182 rm -r dist/python-$(DISTVERSION)-docs-text 183 rm dist/python-$(DISTVERSION)-docs-text.tar 184 185 # archive the A4 latex 186 rm -rf build/latex 187 make latex PAPER=a4 188 -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile 189 (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2) 190 cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip 191 cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2 192 193 # archive the letter latex 194 rm -rf build/latex 195 make latex PAPER=letter 196 -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile 197 (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2) 198 cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip 199 cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2 200 201 # copy the epub build 202 rm -rf build/epub 203 make epub 204 cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub 205 206 # archive the texinfo build 207 rm -rf build/texinfo 208 make texinfo 209 make info --directory=build/texinfo 210 cp -pPR build/texinfo dist/python-$(DISTVERSION)-docs-texinfo 211 tar -C dist -cf dist/python-$(DISTVERSION)-docs-texinfo.tar python-$(DISTVERSION)-docs-texinfo 212 bzip2 -9 -k dist/python-$(DISTVERSION)-docs-texinfo.tar 213 (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-texinfo.zip python-$(DISTVERSION)-docs-texinfo) 214 rm -r dist/python-$(DISTVERSION)-docs-texinfo 215 rm dist/python-$(DISTVERSION)-docs-texinfo.tar 216 217check: 218 # Check the docs and NEWS files with sphinx-lint. 219 # Ignore the tools and venv dirs and check that the default role is not used. 220 $(SPHINXLINT) -i tools -i $(VENVDIR) --enable default-role 221 $(SPHINXLINT) --enable default-role ../Misc/NEWS.d/next/ 222 223serve: 224 @echo "The serve target was removed, use htmlview instead (see bpo-36329)" 225 226# Targets for daily automated doc build 227# By default, Sphinx only rebuilds pages where the page content has changed. 228# This means it doesn't always pick up changes to preferred link targets, etc 229# To ensure such changes are picked up, we build the published docs with 230# `-E` (to ignore the cached environment) and `-a` (to ignore already existing 231# output files) 232 233# for development releases: always build 234autobuild-dev: 235 make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1' 236 237# for quick rebuilds (HTML only) 238autobuild-dev-html: 239 make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1' 240 241# for stable releases: only build if not in pre-release stage (alpha, beta) 242# release candidate downloads are okay, since the stable tree can be in that stage 243autobuild-stable: 244 @case $(DISTVERSION) in *[ab]*) \ 245 echo "Not building; $(DISTVERSION) is not a release version."; \ 246 exit 1;; \ 247 esac 248 @make autobuild-dev 249 250autobuild-stable-html: 251 @case $(DISTVERSION) in *[ab]*) \ 252 echo "Not building; $(DISTVERSION) is not a release version."; \ 253 exit 1;; \ 254 esac 255 @make autobuild-dev-html 256