1# 2# Makefile for Python documentation 3# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4# 5 6# You can set these variables from the command line. 7PYTHON = python3 8SPHINXBUILD = sphinx-build 9PAPER = 10SOURCES = 11DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py) 12 13ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_elements.papersize=$(PAPER) \ 14 $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES) 15 16.PHONY: help build html htmlhelp latex text changes linkcheck \ 17 suspicious coverage doctest pydoc-topics htmlview clean dist check serve \ 18 autobuild-dev autobuild-stable venv 19 20help: 21 @echo "Please use \`make <target>' where <target> is one of" 22 @echo " clean to remove build files" 23 @echo " venv to create a venv with necessary tools" 24 @echo " html to make standalone HTML files" 25 @echo " htmlview to open the index page built by the html target in your browser" 26 @echo " htmlhelp to make HTML files and a HTML help project" 27 @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 28 @echo " text to make plain text files" 29 @echo " epub to make EPUB files" 30 @echo " changes to make an overview over all changed/added/deprecated items" 31 @echo " linkcheck to check all external links for integrity" 32 @echo " coverage to check documentation coverage for library and C API" 33 @echo " doctest to run doctests in the documentation" 34 @echo " pydoc-topics to regenerate the pydoc topics file" 35 @echo " dist to create a \"dist\" directory with archived docs for download" 36 @echo " suspicious to check for suspicious markup in output text" 37 @echo " check to run a check for frequent markup errors" 38 @echo " serve to serve the documentation on the localhost (8000)" 39 40build: 41 $(SPHINXBUILD) $(ALLSPHINXOPTS) 42 @echo 43 44html: BUILDER = html 45html: build 46 @echo "Build finished. The HTML pages are in build/html." 47 48htmlhelp: BUILDER = htmlhelp 49htmlhelp: build 50 @echo "Build finished; now you can run HTML Help Workshop with the" \ 51 "build/htmlhelp/pydoc.hhp project file." 52 53latex: BUILDER = latex 54latex: build 55 @echo "Build finished; the LaTeX files are in build/latex." 56 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ 57 "run these through (pdf)latex." 58 59text: BUILDER = text 60text: build 61 @echo "Build finished; the text files are in build/text." 62 63epub: BUILDER = epub 64epub: build 65 @echo "Build finished; the epub files are in build/epub." 66 67changes: BUILDER = changes 68changes: build 69 @echo "The overview file is in build/changes." 70 71linkcheck: BUILDER = linkcheck 72linkcheck: 73 @$(MAKE) build BUILDER=$(BUILDER) || { \ 74 echo "Link check complete; look for any errors in the above output" \ 75 "or in build/$(BUILDER)/output.txt"; \ 76 false; } 77 78suspicious: BUILDER = suspicious 79suspicious: 80 @$(MAKE) build BUILDER=$(BUILDER) || { \ 81 echo "Suspicious check complete; look for any errors in the above output" \ 82 "or in build/$(BUILDER)/suspicious.csv. If all issues are false" \ 83 "positives, append that file to tools/susp-ignored.csv."; \ 84 false; } 85 86coverage: BUILDER = coverage 87coverage: build 88 @echo "Coverage finished; see c.txt and python.txt in build/coverage" 89 90doctest: BUILDER = doctest 91doctest: 92 @$(MAKE) build BUILDER=$(BUILDER) || { \ 93 echo "Testing of doctests in the sources finished, look at the" \ 94 "results in build/doctest/output.txt"; \ 95 false; } 96 97pydoc-topics: BUILDER = pydoc-topics 98pydoc-topics: build 99 @echo "Building finished; now run this:" \ 100 "cp build/pydoc-topics/topics.py ../Lib/pydoc_data/topics.py" 101 102htmlview: html 103 $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')" 104 105clean: 106 -rm -rf build/* venv/* 107 108venv: 109 $(PYTHON) -m venv venv 110 ./venv/bin/python3 -m pip install -U Sphinx 111 112dist: 113 rm -rf dist 114 mkdir -p dist 115 116 # archive the HTML 117 make html 118 cp -pPR build/html dist/python-$(DISTVERSION)-docs-html 119 tar -C dist -cf dist/python-$(DISTVERSION)-docs-html.tar python-$(DISTVERSION)-docs-html 120 bzip2 -9 -k dist/python-$(DISTVERSION)-docs-html.tar 121 (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-html.zip python-$(DISTVERSION)-docs-html) 122 rm -r dist/python-$(DISTVERSION)-docs-html 123 rm dist/python-$(DISTVERSION)-docs-html.tar 124 125 # archive the text build 126 make text 127 cp -pPR build/text dist/python-$(DISTVERSION)-docs-text 128 tar -C dist -cf dist/python-$(DISTVERSION)-docs-text.tar python-$(DISTVERSION)-docs-text 129 bzip2 -9 -k dist/python-$(DISTVERSION)-docs-text.tar 130 (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-text.zip python-$(DISTVERSION)-docs-text) 131 rm -r dist/python-$(DISTVERSION)-docs-text 132 rm dist/python-$(DISTVERSION)-docs-text.tar 133 134 # archive the A4 latex 135 rm -rf build/latex 136 make latex PAPER=a4 137 -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile 138 (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2) 139 cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip 140 cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2 141 142 # archive the letter latex 143 rm -rf build/latex 144 make latex PAPER=letter 145 -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile 146 (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2) 147 cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip 148 cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2 149 150 # copy the epub build 151 rm -rf build/epub 152 make epub 153 cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub 154 155check: 156 $(PYTHON) tools/rstlint.py -i tools -i venv -i README.rst 157 158serve: 159 ../Tools/scripts/serve.py build/html 160 161# Targets for daily automated doc build 162 163# for development releases: always build 164autobuild-dev: 165 make dist SPHINXOPTS='$(SPHINXOPTS) -A daily=1 -A versionswitcher=1' 166 -make suspicious 167 168# for quick rebuilds (HTML only) 169autobuild-dev-html: 170 make html SPHINXOPTS='$(SPHINXOPTS) -A daily=1 -A versionswitcher=1' 171 172# for stable releases: only build if not in pre-release stage (alpha, beta) 173# release candidate downloads are okay, since the stable tree can be in that stage 174autobuild-stable: 175 @case $(DISTVERSION) in *[ab]*) \ 176 echo "Not building; $(DISTVERSION) is not a release version."; \ 177 exit 1;; \ 178 esac 179 @make autobuild-dev 180 181autobuild-stable-html: 182 @case $(DISTVERSION) in *[ab]*) \ 183 echo "Not building; $(DISTVERSION) is not a release version."; \ 184 exit 1;; \ 185 esac 186 @make autobuild-dev-html 187