blob: a774aad0aa328e69927433c3e15a997bc681fa7a [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001#
2# Makefile for Python documentation
3# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4#
5
6# You can set these variables from the command line.
Benjamin Peterson62f71b02009-03-03 22:55:55 +00007PYTHON = python
Guido van Rossumda27fd22007-08-17 00:24:54 +00008SVNROOT = http://svn.python.org/projects
9SPHINXOPTS =
Christian Heimes2c181612007-12-17 20:04:13 +000010PAPER =
Christian Heimesfe337bf2008-03-23 21:54:12 +000011SOURCES =
Benjamin Peterson92035012008-12-27 16:00:54 +000012DISTVERSION = $(shell $(PYTHON) tools/sphinxext/patchlevel.py)
Georg Brandl116aa622007-08-15 14:28:22 +000013
Christian Heimes2c181612007-12-17 20:04:13 +000014ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \
Christian Heimesfe337bf2008-03-23 21:54:12 +000015 $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES)
Georg Brandl116aa622007-08-15 14:28:22 +000016
Georg Brandlfe427fe2010-03-13 11:02:07 +000017.PHONY: help checkout update build html htmlhelp latex text changes linkcheck \
18 suspicious coverage doctest pydoc-topics htmlview clean dist check serve \
19 autobuild-dev autobuild-stable
Georg Brandl116aa622007-08-15 14:28:22 +000020
21help:
22 @echo "Please use \`make <target>' where <target> is one of"
Georg Brandlfe427fe2010-03-13 11:02:07 +000023 @echo " clean to remove build files"
24 @echo " update to update build tools"
25 @echo " html to make standalone HTML files"
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"
Georg Brandl183fe812011-01-05 11:00:25 +000029 @echo " epub to make EPUB files"
Georg Brandlfe427fe2010-03-13 11:02:07 +000030 @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"
Benjamin Peterson28d88b42009-01-09 03:03:23 +000036 @echo " suspicious to check for suspicious markup in output text"
Georg Brandlfe427fe2010-03-13 11:02:07 +000037 @echo " check to run a check for frequent markup errors"
38 @echo " serve to serve the documentation on the localhost (8000)"
Georg Brandl116aa622007-08-15 14:28:22 +000039
Georg Brandl5617db82009-04-27 16:28:57 +000040# Note: if you update versions here, do the same in make.bat and README.txt
Georg Brandl116aa622007-08-15 14:28:22 +000041checkout:
42 @if [ ! -d tools/sphinx ]; then \
43 echo "Checking out Sphinx..."; \
Georg Brandl6dc50f32011-01-15 16:45:03 +000044 svn checkout $(SVNROOT)/external/Sphinx-1.0.7/sphinx tools/sphinx; \
Georg Brandl116aa622007-08-15 14:28:22 +000045 fi
46 @if [ ! -d tools/docutils ]; then \
47 echo "Checking out Docutils..."; \
Georg Brandld94b4a72010-03-13 10:56:09 +000048 svn checkout $(SVNROOT)/external/docutils-0.6/docutils tools/docutils; \
Georg Brandl116aa622007-08-15 14:28:22 +000049 fi
Benjamin Peterson28d88b42009-01-09 03:03:23 +000050 @if [ ! -d tools/jinja2 ]; then \
Benjamin Petersond8607622008-04-13 23:11:15 +000051 echo "Checking out Jinja..."; \
Georg Brandld94b4a72010-03-13 10:56:09 +000052 svn checkout $(SVNROOT)/external/Jinja-2.3.1/jinja2 tools/jinja2; \
Benjamin Petersond8607622008-04-13 23:11:15 +000053 fi
Georg Brandl116aa622007-08-15 14:28:22 +000054 @if [ ! -d tools/pygments ]; then \
55 echo "Checking out Pygments..."; \
Georg Brandl0472bc82012-09-30 18:00:50 +020056 svn checkout $(SVNROOT)/external/Pygments-1.5dev-20120930/pygments tools/pygments; \
Georg Brandl116aa622007-08-15 14:28:22 +000057 fi
58
Éric Araujo716ac382010-09-06 01:31:11 +000059update: clean checkout
Georg Brandl116aa622007-08-15 14:28:22 +000060
Éric Araujo716ac382010-09-06 01:31:11 +000061build: checkout
Georg Brandl116aa622007-08-15 14:28:22 +000062 mkdir -p build/$(BUILDER) build/doctrees
63 $(PYTHON) tools/sphinx-build.py $(ALLSPHINXOPTS)
64 @echo
65
66html: BUILDER = html
67html: build
68 @echo "Build finished. The HTML pages are in build/html."
69
Georg Brandl116aa622007-08-15 14:28:22 +000070htmlhelp: BUILDER = htmlhelp
71htmlhelp: build
72 @echo "Build finished; now you can run HTML Help Workshop with the" \
Guido van Rossumda27fd22007-08-17 00:24:54 +000073 "build/htmlhelp/pydoc.hhp project file."
Georg Brandl116aa622007-08-15 14:28:22 +000074
Christian Heimesd8654cf2007-12-02 15:22:16 +000075latex: BUILDER = latex
76latex: build
77 @echo "Build finished; the LaTeX files are in build/latex."
Christian Heimes2c181612007-12-17 20:04:13 +000078 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
79 "run these through (pdf)latex."
Christian Heimesd8654cf2007-12-02 15:22:16 +000080
Georg Brandl0c77a822008-06-10 16:37:50 +000081text: BUILDER = text
82text: build
83 @echo "Build finished; the text files are in build/text."
84
Georg Brandl183fe812011-01-05 11:00:25 +000085epub: BUILDER = epub
86epub: build
87 @echo "Build finished; the epub files are in build/epub."
88
Christian Heimes5b5e81c2007-12-31 16:14:33 +000089changes: BUILDER = changes
90changes: build
91 @echo "The overview file is in build/changes."
92
Christian Heimes292d3512008-02-03 16:51:08 +000093linkcheck: BUILDER = linkcheck
94linkcheck: build
Georg Brandl19b3e002010-10-06 10:35:24 +000095 @echo "Link check complete; look for any errors in the above output" \
Christian Heimes292d3512008-02-03 16:51:08 +000096 "or in build/$(BUILDER)/output.txt"
97
Benjamin Peterson28d88b42009-01-09 03:03:23 +000098suspicious: BUILDER = suspicious
99suspicious: build
Georg Brandl19b3e002010-10-06 10:35:24 +0000100 @echo "Suspicious check complete; look for any errors in the above output" \
101 "or in build/$(BUILDER)/suspicious.csv. If all issues are false" \
102 "positives, append that file to tools/sphinxext/susp-ignored.csv."
Benjamin Peterson28d88b42009-01-09 03:03:23 +0000103
Christian Heimesd3eb5a152008-02-24 00:38:49 +0000104coverage: BUILDER = coverage
105coverage: build
106 @echo "Coverage finished; see c.txt and python.txt in build/coverage"
107
Christian Heimesfe337bf2008-03-23 21:54:12 +0000108doctest: BUILDER = doctest
109doctest: build
Georg Brandl19b3e002010-10-06 10:35:24 +0000110 @echo "Testing of doctests in the sources finished, look at the" \
Christian Heimesfe337bf2008-03-23 21:54:12 +0000111 "results in build/doctest/output.txt"
112
Georg Brandl6b38daa2008-06-01 21:05:17 +0000113pydoc-topics: BUILDER = pydoc-topics
114pydoc-topics: build
Georg Brandl19b3e002010-10-06 10:35:24 +0000115 @echo "Building finished; now copy build/pydoc-topics/topics.py" \
Georg Brandl7f3cd982011-07-03 09:30:42 +0200116 "to ../Lib/pydoc_data/topics.py"
Georg Brandl6b38daa2008-06-01 21:05:17 +0000117
Benjamin Peterson41181742008-07-02 20:22:54 +0000118htmlview: html
119 $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')"
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000120
Georg Brandl116aa622007-08-15 14:28:22 +0000121clean:
122 -rm -rf build/*
123 -rm -rf tools/sphinx
Benjamin Petersonb05e73d2009-12-31 03:35:15 +0000124 -rm -rf tools/pygments
125 -rm -rf tools/jinja2
126 -rm -rf tools/docutils
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000127
128dist:
Georg Brandl38557f22010-08-03 12:36:57 +0000129 rm -rf dist
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000130 mkdir -p dist
131
132 # archive the HTML
133 make html
Benjamin Peterson92035012008-12-27 16:00:54 +0000134 cp -pPR build/html dist/python-$(DISTVERSION)-docs-html
135 tar -C dist -cf dist/python-$(DISTVERSION)-docs-html.tar python-$(DISTVERSION)-docs-html
136 bzip2 -9 -k dist/python-$(DISTVERSION)-docs-html.tar
137 (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-html.zip python-$(DISTVERSION)-docs-html)
138 rm -r dist/python-$(DISTVERSION)-docs-html
139 rm dist/python-$(DISTVERSION)-docs-html.tar
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000140
141 # archive the text build
142 make text
Benjamin Peterson92035012008-12-27 16:00:54 +0000143 cp -pPR build/text dist/python-$(DISTVERSION)-docs-text
144 tar -C dist -cf dist/python-$(DISTVERSION)-docs-text.tar python-$(DISTVERSION)-docs-text
145 bzip2 -9 -k dist/python-$(DISTVERSION)-docs-text.tar
146 (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-text.zip python-$(DISTVERSION)-docs-text)
147 rm -r dist/python-$(DISTVERSION)-docs-text
148 rm dist/python-$(DISTVERSION)-docs-text.tar
Georg Brandl5617db82009-04-27 16:28:57 +0000149
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000150 # archive the A4 latex
Georg Brandl38557f22010-08-03 12:36:57 +0000151 rm -rf build/latex
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000152 make latex PAPER=a4
Georg Brandl692b3f82010-07-11 08:33:16 +0000153 -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000154 (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
Benjamin Peterson92035012008-12-27 16:00:54 +0000155 cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
156 cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000157
158 # archive the letter latex
Georg Brandl38557f22010-08-03 12:36:57 +0000159 rm -rf build/latex
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000160 make latex PAPER=letter
Georg Brandl692b3f82010-07-11 08:33:16 +0000161 -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000162 (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
Benjamin Peterson92035012008-12-27 16:00:54 +0000163 cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
164 cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000165
Georg Brandl183fe812011-01-05 11:00:25 +0000166 # archive the epub build
167 rm -rf build/epub
168 make epub
169 mkdir -p dist/python-$(DISTVERSION)-docs-epub
170 cp -pPR build/epub/*.epub dist/python-$(DISTVERSION)-docs-epub/
171 tar -C dist -cf dist/python-$(DISTVERSION)-docs-epub.tar python-$(DISTVERSION)-docs-epub
172 bzip2 -9 -k dist/python-$(DISTVERSION)-docs-epub.tar
173 (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-epub.zip python-$(DISTVERSION)-docs-epub)
174 rm -r dist/python-$(DISTVERSION)-docs-epub
175 rm dist/python-$(DISTVERSION)-docs-epub.tar
176
Georg Brandl45f53372009-01-03 21:15:20 +0000177check:
Georg Brandld5097882009-01-03 21:30:40 +0000178 $(PYTHON) tools/rstlint.py -i tools
R. David Murraye821cb62010-03-08 17:48:38 +0000179
180serve:
181 ../Tools/scripts/serve.py build/html
Georg Brandlfe427fe2010-03-13 11:02:07 +0000182
Georg Brandl49f47182010-03-13 13:42:16 +0000183# Targets for daily automated doc build
Georg Brandlfe427fe2010-03-13 11:02:07 +0000184
185# for development releases: always build
186autobuild-dev:
187 make update
Ezio Melotti58864b32012-10-27 22:28:48 +0300188 make dist SPHINXOPTS='-A daily=1 -A versionswitcher=1'
Georg Brandlfe427fe2010-03-13 11:02:07 +0000189
Georg Brandl01f47e82012-10-28 08:09:02 +0100190# for quick rebuilds (HTML only)
191autobuild-html:
192 make html SPHINXOPTS='-A daily=1 -A versionswitcher=1'
193
Georg Brandl49f47182010-03-13 13:42:16 +0000194# for stable releases: only build if not in pre-release stage (alpha, beta, rc)
Georg Brandlfe427fe2010-03-13 11:02:07 +0000195autobuild-stable:
196 @case $(DISTVERSION) in *[abc]*) \
Georg Brandl49f47182010-03-13 13:42:16 +0000197 echo "Not building; $(DISTVERSION) is not a release version."; \
198 exit 1;; \
Georg Brandlfe427fe2010-03-13 11:02:07 +0000199 esac
200 @make autobuild-dev
Georg Brandl01f47e82012-10-28 08:09:02 +0100201