Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | # |
| 2 | # Makefile for Python documentation |
| 3 | # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 4 | # |
| 5 | |
| 6 | # You can set these variables from the command line. |
Benjamin Peterson | 62f71b0 | 2009-03-03 22:55:55 +0000 | [diff] [blame] | 7 | PYTHON = python |
Georg Brandl | f7b2f36 | 2014-02-16 09:46:36 +0100 | [diff] [blame] | 8 | SPHINXBUILD = sphinx-build |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 9 | PAPER = |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 10 | SOURCES = |
Georg Brandl | 61bd1dc | 2014-09-30 22:56:38 +0200 | [diff] [blame] | 11 | DISTVERSION = $(shell $(PYTHON) tools/patchlevel.py) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 12 | |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 13 | ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \ |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 14 | $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 15 | |
Éric Araujo | f446d7a | 2014-03-13 19:30:43 -0400 | [diff] [blame] | 16 | .PHONY: help build html htmlhelp latex text changes linkcheck \ |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 17 | suspicious coverage doctest pydoc-topics htmlview clean dist check serve \ |
| 18 | autobuild-dev autobuild-stable |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 19 | |
| 20 | help: |
| 21 | @echo "Please use \`make <target>' where <target> is one of" |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 22 | @echo " clean to remove build files" |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 23 | @echo " html to make standalone HTML files" |
Zachary Ware | 9393fff | 2014-04-29 09:24:40 -0500 | [diff] [blame] | 24 | @echo " htmlview to open the index page built by the html target in your browser" |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 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" |
Georg Brandl | 183fe81 | 2011-01-05 11:00:25 +0000 | [diff] [blame] | 28 | @echo " epub to make EPUB files" |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 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" |
Benjamin Peterson | 28d88b4 | 2009-01-09 03:03:23 +0000 | [diff] [blame] | 35 | @echo " suspicious to check for suspicious markup in output text" |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 36 | @echo " check to run a check for frequent markup errors" |
| 37 | @echo " serve to serve the documentation on the localhost (8000)" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 38 | |
Éric Araujo | f446d7a | 2014-03-13 19:30:43 -0400 | [diff] [blame] | 39 | build: |
Georg Brandl | f7b2f36 | 2014-02-16 09:46:36 +0100 | [diff] [blame] | 40 | $(SPHINXBUILD) $(ALLSPHINXOPTS) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 41 | @echo |
| 42 | |
| 43 | html: BUILDER = html |
| 44 | html: build |
| 45 | @echo "Build finished. The HTML pages are in build/html." |
| 46 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 47 | htmlhelp: BUILDER = htmlhelp |
| 48 | htmlhelp: build |
| 49 | @echo "Build finished; now you can run HTML Help Workshop with the" \ |
Guido van Rossum | da27fd2 | 2007-08-17 00:24:54 +0000 | [diff] [blame] | 50 | "build/htmlhelp/pydoc.hhp project file." |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 51 | |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 52 | latex: BUILDER = latex |
| 53 | latex: build |
| 54 | @echo "Build finished; the LaTeX files are in build/latex." |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 55 | @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ |
| 56 | "run these through (pdf)latex." |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 57 | |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 58 | text: BUILDER = text |
| 59 | text: build |
| 60 | @echo "Build finished; the text files are in build/text." |
| 61 | |
Georg Brandl | 183fe81 | 2011-01-05 11:00:25 +0000 | [diff] [blame] | 62 | epub: BUILDER = epub |
| 63 | epub: build |
| 64 | @echo "Build finished; the epub files are in build/epub." |
| 65 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 66 | changes: BUILDER = changes |
| 67 | changes: build |
| 68 | @echo "The overview file is in build/changes." |
| 69 | |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 70 | linkcheck: BUILDER = linkcheck |
Serhiy Storchaka | 17f5f81 | 2014-07-22 10:24:25 +0300 | [diff] [blame] | 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; } |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 76 | |
Benjamin Peterson | 28d88b4 | 2009-01-09 03:03:23 +0000 | [diff] [blame] | 77 | suspicious: BUILDER = suspicious |
Serhiy Storchaka | 17f5f81 | 2014-07-22 10:24:25 +0300 | [diff] [blame] | 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" \ |
Georg Brandl | 61bd1dc | 2014-09-30 22:56:38 +0200 | [diff] [blame] | 82 | "positives, append that file to tools/susp-ignored.csv."; \ |
Serhiy Storchaka | 17f5f81 | 2014-07-22 10:24:25 +0300 | [diff] [blame] | 83 | false; } |
Benjamin Peterson | 28d88b4 | 2009-01-09 03:03:23 +0000 | [diff] [blame] | 84 | |
Christian Heimes | d3eb5a15 | 2008-02-24 00:38:49 +0000 | [diff] [blame] | 85 | coverage: BUILDER = coverage |
| 86 | coverage: build |
| 87 | @echo "Coverage finished; see c.txt and python.txt in build/coverage" |
| 88 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 89 | doctest: BUILDER = doctest |
Serhiy Storchaka | 17f5f81 | 2014-07-22 10:24:25 +0300 | [diff] [blame] | 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; } |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 95 | |
Georg Brandl | 6b38daa | 2008-06-01 21:05:17 +0000 | [diff] [blame] | 96 | pydoc-topics: BUILDER = pydoc-topics |
| 97 | pydoc-topics: build |
Georg Brandl | 19b3e00 | 2010-10-06 10:35:24 +0000 | [diff] [blame] | 98 | @echo "Building finished; now copy build/pydoc-topics/topics.py" \ |
Georg Brandl | 7f3cd98 | 2011-07-03 09:30:42 +0200 | [diff] [blame] | 99 | "to ../Lib/pydoc_data/topics.py" |
Georg Brandl | 6b38daa | 2008-06-01 21:05:17 +0000 | [diff] [blame] | 100 | |
Benjamin Peterson | 4118174 | 2008-07-02 20:22:54 +0000 | [diff] [blame] | 101 | htmlview: html |
| 102 | $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')" |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 103 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 104 | clean: |
| 105 | -rm -rf build/* |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 106 | |
| 107 | dist: |
Georg Brandl | 38557f2 | 2010-08-03 12:36:57 +0000 | [diff] [blame] | 108 | rm -rf dist |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 109 | mkdir -p dist |
| 110 | |
| 111 | # archive the HTML |
| 112 | make html |
Benjamin Peterson | 9203501 | 2008-12-27 16:00:54 +0000 | [diff] [blame] | 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 |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 119 | |
| 120 | # archive the text build |
| 121 | make text |
Benjamin Peterson | 9203501 | 2008-12-27 16:00:54 +0000 | [diff] [blame] | 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 |
Georg Brandl | 5617db8 | 2009-04-27 16:28:57 +0000 | [diff] [blame] | 128 | |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 129 | # archive the A4 latex |
Georg Brandl | 38557f2 | 2010-08-03 12:36:57 +0000 | [diff] [blame] | 130 | rm -rf build/latex |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 131 | make latex PAPER=a4 |
Georg Brandl | 692b3f8 | 2010-07-11 08:33:16 +0000 | [diff] [blame] | 132 | -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 133 | (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2) |
Benjamin Peterson | 9203501 | 2008-12-27 16:00:54 +0000 | [diff] [blame] | 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 |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 136 | |
| 137 | # archive the letter latex |
Georg Brandl | 38557f2 | 2010-08-03 12:36:57 +0000 | [diff] [blame] | 138 | rm -rf build/latex |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 139 | make latex PAPER=letter |
Georg Brandl | 692b3f8 | 2010-07-11 08:33:16 +0000 | [diff] [blame] | 140 | -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 141 | (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2) |
Benjamin Peterson | 9203501 | 2008-12-27 16:00:54 +0000 | [diff] [blame] | 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 |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 144 | |
Georg Brandl | 865bdbf | 2014-03-28 19:48:55 +0100 | [diff] [blame] | 145 | # copy the epub build |
Georg Brandl | 183fe81 | 2011-01-05 11:00:25 +0000 | [diff] [blame] | 146 | rm -rf build/epub |
| 147 | make epub |
Georg Brandl | 865bdbf | 2014-03-28 19:48:55 +0100 | [diff] [blame] | 148 | cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub |
Georg Brandl | 183fe81 | 2011-01-05 11:00:25 +0000 | [diff] [blame] | 149 | |
Georg Brandl | 45f5337 | 2009-01-03 21:15:20 +0000 | [diff] [blame] | 150 | check: |
Georg Brandl | d509788 | 2009-01-03 21:30:40 +0000 | [diff] [blame] | 151 | $(PYTHON) tools/rstlint.py -i tools |
R. David Murray | e821cb6 | 2010-03-08 17:48:38 +0000 | [diff] [blame] | 152 | |
| 153 | serve: |
| 154 | ../Tools/scripts/serve.py build/html |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 155 | |
Georg Brandl | 49f4718 | 2010-03-13 13:42:16 +0000 | [diff] [blame] | 156 | # Targets for daily automated doc build |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 157 | |
| 158 | # for development releases: always build |
| 159 | autobuild-dev: |
Ezio Melotti | 58864b3 | 2012-10-27 22:28:48 +0300 | [diff] [blame] | 160 | make dist SPHINXOPTS='-A daily=1 -A versionswitcher=1' |
Georg Brandl | 44d2429 | 2013-11-24 16:17:54 +0100 | [diff] [blame] | 161 | -make suspicious |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 162 | |
Georg Brandl | 01f47e8 | 2012-10-28 08:09:02 +0100 | [diff] [blame] | 163 | # for quick rebuilds (HTML only) |
| 164 | autobuild-html: |
| 165 | make html SPHINXOPTS='-A daily=1 -A versionswitcher=1' |
| 166 | |
Benjamin Peterson | efd713b | 2014-09-24 20:22:24 -0400 | [diff] [blame] | 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 |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 169 | autobuild-stable: |
Benjamin Peterson | efd713b | 2014-09-24 20:22:24 -0400 | [diff] [blame] | 170 | @case $(DISTVERSION) in *[ab]*) \ |
Georg Brandl | 49f4718 | 2010-03-13 13:42:16 +0000 | [diff] [blame] | 171 | echo "Not building; $(DISTVERSION) is not a release version."; \ |
| 172 | exit 1;; \ |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 173 | esac |
| 174 | @make autobuild-dev |
Georg Brandl | 01f47e8 | 2012-10-28 08:09:02 +0100 | [diff] [blame] | 175 | |