blob: 202e8e1de3aecd8bf485686b26e5789a6d5b22c9 [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
Georg Brandlf7b2f362014-02-16 09:46:36 +01008SPHINXBUILD = sphinx-build
Christian Heimes2c181612007-12-17 20:04:13 +00009PAPER =
Christian Heimesfe337bf2008-03-23 21:54:12 +000010SOURCES =
Benjamin Peterson82c05a52014-12-10 11:04:17 -050011DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py)
Georg Brandl116aa622007-08-15 14:28:22 +000012
Christian Heimes2c181612007-12-17 20:04:13 +000013ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \
Christian Heimesfe337bf2008-03-23 21:54:12 +000014 $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES)
Georg Brandl116aa622007-08-15 14:28:22 +000015
Éric Araujof446d7a2014-03-13 19:30:43 -040016.PHONY: help build html htmlhelp latex text changes linkcheck \
Georg Brandlfe427fe2010-03-13 11:02:07 +000017 suspicious coverage doctest pydoc-topics htmlview clean dist check serve \
Brett Cannond5ea39d2014-12-05 15:17:31 -050018 autobuild-dev autobuild-stable venv
Georg Brandl116aa622007-08-15 14:28:22 +000019
20help:
21 @echo "Please use \`make <target>' where <target> is one of"
Georg Brandlfe427fe2010-03-13 11:02:07 +000022 @echo " clean to remove build files"
Brett Cannond5ea39d2014-12-05 15:17:31 -050023 @echo " venv to create a venv with necessary tools"
Georg Brandlfe427fe2010-03-13 11:02:07 +000024 @echo " html to make standalone HTML files"
Zachary Ware9393fff2014-04-29 09:24:40 -050025 @echo " htmlview to open the index page built by the html target in your browser"
Georg Brandlfe427fe2010-03-13 11:02:07 +000026 @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
Éric Araujof446d7a2014-03-13 19:30:43 -040040build:
Georg Brandlf7b2f362014-02-16 09:46:36 +010041 $(SPHINXBUILD) $(ALLSPHINXOPTS)
Georg Brandl116aa622007-08-15 14:28:22 +000042 @echo
43
44html: BUILDER = html
45html: build
46 @echo "Build finished. The HTML pages are in build/html."
47
Georg Brandl116aa622007-08-15 14:28:22 +000048htmlhelp: BUILDER = htmlhelp
49htmlhelp: build
50 @echo "Build finished; now you can run HTML Help Workshop with the" \
Guido van Rossumda27fd22007-08-17 00:24:54 +000051 "build/htmlhelp/pydoc.hhp project file."
Georg Brandl116aa622007-08-15 14:28:22 +000052
Christian Heimesd8654cf2007-12-02 15:22:16 +000053latex: BUILDER = latex
54latex: build
55 @echo "Build finished; the LaTeX files are in build/latex."
Christian Heimes2c181612007-12-17 20:04:13 +000056 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
57 "run these through (pdf)latex."
Christian Heimesd8654cf2007-12-02 15:22:16 +000058
Georg Brandl0c77a822008-06-10 16:37:50 +000059text: BUILDER = text
60text: build
61 @echo "Build finished; the text files are in build/text."
62
Georg Brandl183fe812011-01-05 11:00:25 +000063epub: BUILDER = epub
64epub: build
65 @echo "Build finished; the epub files are in build/epub."
66
Christian Heimes5b5e81c2007-12-31 16:14:33 +000067changes: BUILDER = changes
68changes: build
69 @echo "The overview file is in build/changes."
70
Christian Heimes292d3512008-02-03 16:51:08 +000071linkcheck: BUILDER = linkcheck
Serhiy Storchaka17f5f812014-07-22 10:24:25 +030072linkcheck:
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; }
Christian Heimes292d3512008-02-03 16:51:08 +000077
Benjamin Peterson28d88b42009-01-09 03:03:23 +000078suspicious: BUILDER = suspicious
Serhiy Storchaka17f5f812014-07-22 10:24:25 +030079suspicious:
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" \
Georg Brandl61bd1dc2014-09-30 22:56:38 +020083 "positives, append that file to tools/susp-ignored.csv."; \
Serhiy Storchaka17f5f812014-07-22 10:24:25 +030084 false; }
Benjamin Peterson28d88b42009-01-09 03:03:23 +000085
Christian Heimesd3eb5a152008-02-24 00:38:49 +000086coverage: BUILDER = coverage
87coverage: build
88 @echo "Coverage finished; see c.txt and python.txt in build/coverage"
89
Christian Heimesfe337bf2008-03-23 21:54:12 +000090doctest: BUILDER = doctest
Serhiy Storchaka17f5f812014-07-22 10:24:25 +030091doctest:
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; }
Christian Heimesfe337bf2008-03-23 21:54:12 +000096
Georg Brandl6b38daa2008-06-01 21:05:17 +000097pydoc-topics: BUILDER = pydoc-topics
98pydoc-topics: build
Larry Hastingse8ff0ca2015-05-30 16:58:27 -070099 @echo "Building finished; now run this:" \
100 "cp build/pydoc-topics/topics.py ../Lib/pydoc_data/topics.py"
Georg Brandl6b38daa2008-06-01 21:05:17 +0000101
Benjamin Peterson41181742008-07-02 20:22:54 +0000102htmlview: html
103 $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')"
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000104
Georg Brandl116aa622007-08-15 14:28:22 +0000105clean:
Brett Cannond5ea39d2014-12-05 15:17:31 -0500106 -rm -rf build/* venv/*
107
108venv:
109 $(PYTHON) -m venv venv
110 ./venv/bin/python3 -m pip install -U Sphinx
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000111
112dist:
Georg Brandl38557f22010-08-03 12:36:57 +0000113 rm -rf dist
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000114 mkdir -p dist
115
116 # archive the HTML
117 make html
Benjamin Peterson92035012008-12-27 16:00:54 +0000118 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
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000124
125 # archive the text build
126 make text
Benjamin Peterson92035012008-12-27 16:00:54 +0000127 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
Georg Brandl5617db82009-04-27 16:28:57 +0000133
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000134 # archive the A4 latex
Georg Brandl38557f22010-08-03 12:36:57 +0000135 rm -rf build/latex
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000136 make latex PAPER=a4
Georg Brandl692b3f82010-07-11 08:33:16 +0000137 -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000138 (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
Benjamin Peterson92035012008-12-27 16:00:54 +0000139 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
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000141
142 # archive the letter latex
Georg Brandl38557f22010-08-03 12:36:57 +0000143 rm -rf build/latex
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000144 make latex PAPER=letter
Georg Brandl692b3f82010-07-11 08:33:16 +0000145 -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000146 (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
Benjamin Peterson92035012008-12-27 16:00:54 +0000147 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
Benjamin Peterson9bc93512008-09-22 22:10:59 +0000149
Georg Brandl865bdbf2014-03-28 19:48:55 +0100150 # copy the epub build
Georg Brandl183fe812011-01-05 11:00:25 +0000151 rm -rf build/epub
152 make epub
Georg Brandl865bdbf2014-03-28 19:48:55 +0100153 cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub
Georg Brandl183fe812011-01-05 11:00:25 +0000154
Georg Brandl45f53372009-01-03 21:15:20 +0000155check:
Zachary Warebfba2cd2016-03-24 22:44:41 -0500156 $(PYTHON) tools/rstlint.py -i tools -i venv
R. David Murraye821cb62010-03-08 17:48:38 +0000157
158serve:
159 ../Tools/scripts/serve.py build/html
Georg Brandlfe427fe2010-03-13 11:02:07 +0000160
Georg Brandl49f47182010-03-13 13:42:16 +0000161# Targets for daily automated doc build
Georg Brandlfe427fe2010-03-13 11:02:07 +0000162
163# for development releases: always build
164autobuild-dev:
Ezio Melotti58864b32012-10-27 22:28:48 +0300165 make dist SPHINXOPTS='-A daily=1 -A versionswitcher=1'
Georg Brandl44d24292013-11-24 16:17:54 +0100166 -make suspicious
Georg Brandlfe427fe2010-03-13 11:02:07 +0000167
Georg Brandl01f47e82012-10-28 08:09:02 +0100168# for quick rebuilds (HTML only)
Georg Brandl4b9e75b2016-06-15 08:57:32 +0200169autobuild-dev-html:
Georg Brandl01f47e82012-10-28 08:09:02 +0100170 make html SPHINXOPTS='-A daily=1 -A versionswitcher=1'
171
Benjamin Petersonefd713b2014-09-24 20:22:24 -0400172# 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
Georg Brandlfe427fe2010-03-13 11:02:07 +0000174autobuild-stable:
Benjamin Petersonefd713b2014-09-24 20:22:24 -0400175 @case $(DISTVERSION) in *[ab]*) \
Georg Brandl49f47182010-03-13 13:42:16 +0000176 echo "Not building; $(DISTVERSION) is not a release version."; \
177 exit 1;; \
Georg Brandlfe427fe2010-03-13 11:02:07 +0000178 esac
179 @make autobuild-dev
Georg Brandl01f47e82012-10-28 08:09:02 +0100180
Georg Brandl4b9e75b2016-06-15 08:57:32 +0200181autobuild-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