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