1 # 2 # Makefile for Python documentation 3 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4 # 5 6 # You can set these variables from the command line. 7 PYTHON = python3 8 SPHINXBUILD = sphinx-build 9 PAPER = 10 SOURCES = 11 DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py) 12 13 ALLSPHINXOPTS = -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 20 help: 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 40 build: 41 $(SPHINXBUILD) $(ALLSPHINXOPTS) 42 @echo 43 44 html: BUILDER = html 45 html: build 46 @echo "Build finished. The HTML pages are in build/html." 47 48 htmlhelp: BUILDER = htmlhelp 49 htmlhelp: build 50 @echo "Build finished; now you can run HTML Help Workshop with the" \ 51 "build/htmlhelp/pydoc.hhp project file." 52 53 latex: BUILDER = latex 54 latex: 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 59 text: BUILDER = text 60 text: build 61 @echo "Build finished; the text files are in build/text." 62 63 epub: BUILDER = epub 64 epub: build 65 @echo "Build finished; the epub files are in build/epub." 66 67 changes: BUILDER = changes 68 changes: build 69 @echo "The overview file is in build/changes." 70 71 linkcheck: BUILDER = linkcheck 72 linkcheck: 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 78 suspicious: BUILDER = suspicious 79 suspicious: 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 86 coverage: BUILDER = coverage 87 coverage: build 88 @echo "Coverage finished; see c.txt and python.txt in build/coverage" 89 90 doctest: BUILDER = doctest 91 doctest: 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 97 pydoc-topics: BUILDER = pydoc-topics 98 pydoc-topics: build 99 @echo "Building finished; now run this:" \ 100 "cp build/pydoc-topics/topics.py ../Lib/pydoc_data/topics.py" 101 102 htmlview: html 103 $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')" 104 105 clean: 106 -rm -rf build/* venv/* 107 108 venv: 109 $(PYTHON) -m venv venv 110 ./venv/bin/python3 -m pip install -U Sphinx 111 112 dist: 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 155 check: 156 $(PYTHON) tools/rstlint.py -i tools -i venv -i README.rst 157 158 serve: 159 ../Tools/scripts/serve.py build/html 160 161 # Targets for daily automated doc build 162 163 # for development releases: always build 164 autobuild-dev: 165 make dist SPHINXOPTS='$(SPHINXOPTS) -A daily=1 -A versionswitcher=1' 166 -make suspicious 167 168 # for quick rebuilds (HTML only) 169 autobuild-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 174 autobuild-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 181 autobuild-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
