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 |
Guido van Rossum | da27fd2 | 2007-08-17 00:24:54 +0000 | [diff] [blame] | 8 | SVNROOT = http://svn.python.org/projects |
| 9 | SPHINXOPTS = |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 10 | PAPER = |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 11 | SOURCES = |
Benjamin Peterson | 9203501 | 2008-12-27 16:00:54 +0000 | [diff] [blame] | 12 | DISTVERSION = $(shell $(PYTHON) tools/sphinxext/patchlevel.py) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 14 | ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \ |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 15 | $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 17 | .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 Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | |
| 21 | help: |
| 22 | @echo "Please use \`make <target>' where <target> is one of" |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 23 | @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 Brandl | 183fe81 | 2011-01-05 11:00:25 +0000 | [diff] [blame] | 29 | @echo " epub to make EPUB files" |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 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" |
Benjamin Peterson | 28d88b4 | 2009-01-09 03:03:23 +0000 | [diff] [blame] | 36 | @echo " suspicious to check for suspicious markup in output text" |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 37 | @echo " check to run a check for frequent markup errors" |
| 38 | @echo " serve to serve the documentation on the localhost (8000)" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | |
Georg Brandl | 5617db8 | 2009-04-27 16:28:57 +0000 | [diff] [blame] | 40 | # Note: if you update versions here, do the same in make.bat and README.txt |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 41 | checkout: |
| 42 | @if [ ! -d tools/sphinx ]; then \ |
| 43 | echo "Checking out Sphinx..."; \ |
Georg Brandl | 6dc50f3 | 2011-01-15 16:45:03 +0000 | [diff] [blame^] | 44 | svn checkout $(SVNROOT)/external/Sphinx-1.0.7/sphinx tools/sphinx; \ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 45 | fi |
| 46 | @if [ ! -d tools/docutils ]; then \ |
| 47 | echo "Checking out Docutils..."; \ |
Georg Brandl | d94b4a7 | 2010-03-13 10:56:09 +0000 | [diff] [blame] | 48 | svn checkout $(SVNROOT)/external/docutils-0.6/docutils tools/docutils; \ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 49 | fi |
Benjamin Peterson | 28d88b4 | 2009-01-09 03:03:23 +0000 | [diff] [blame] | 50 | @if [ ! -d tools/jinja2 ]; then \ |
Benjamin Peterson | d860762 | 2008-04-13 23:11:15 +0000 | [diff] [blame] | 51 | echo "Checking out Jinja..."; \ |
Georg Brandl | d94b4a7 | 2010-03-13 10:56:09 +0000 | [diff] [blame] | 52 | svn checkout $(SVNROOT)/external/Jinja-2.3.1/jinja2 tools/jinja2; \ |
Benjamin Peterson | d860762 | 2008-04-13 23:11:15 +0000 | [diff] [blame] | 53 | fi |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 54 | @if [ ! -d tools/pygments ]; then \ |
| 55 | echo "Checking out Pygments..."; \ |
Georg Brandl | d94b4a7 | 2010-03-13 10:56:09 +0000 | [diff] [blame] | 56 | svn checkout $(SVNROOT)/external/Pygments-1.3.1/pygments tools/pygments; \ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | fi |
| 58 | |
Éric Araujo | 716ac38 | 2010-09-06 01:31:11 +0000 | [diff] [blame] | 59 | update: clean checkout |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
Éric Araujo | 716ac38 | 2010-09-06 01:31:11 +0000 | [diff] [blame] | 61 | build: checkout |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 62 | mkdir -p build/$(BUILDER) build/doctrees |
| 63 | $(PYTHON) tools/sphinx-build.py $(ALLSPHINXOPTS) |
| 64 | @echo |
| 65 | |
| 66 | html: BUILDER = html |
| 67 | html: build |
| 68 | @echo "Build finished. The HTML pages are in build/html." |
| 69 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 70 | htmlhelp: BUILDER = htmlhelp |
| 71 | htmlhelp: build |
| 72 | @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] | 73 | "build/htmlhelp/pydoc.hhp project file." |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 75 | latex: BUILDER = latex |
| 76 | latex: build |
| 77 | @echo "Build finished; the LaTeX files are in build/latex." |
Christian Heimes | 2c18161 | 2007-12-17 20:04:13 +0000 | [diff] [blame] | 78 | @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ |
| 79 | "run these through (pdf)latex." |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 80 | |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 81 | text: BUILDER = text |
| 82 | text: build |
| 83 | @echo "Build finished; the text files are in build/text." |
| 84 | |
Georg Brandl | 183fe81 | 2011-01-05 11:00:25 +0000 | [diff] [blame] | 85 | epub: BUILDER = epub |
| 86 | epub: build |
| 87 | @echo "Build finished; the epub files are in build/epub." |
| 88 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 89 | changes: BUILDER = changes |
| 90 | changes: build |
| 91 | @echo "The overview file is in build/changes." |
| 92 | |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 93 | linkcheck: BUILDER = linkcheck |
| 94 | linkcheck: build |
Georg Brandl | 19b3e00 | 2010-10-06 10:35:24 +0000 | [diff] [blame] | 95 | @echo "Link check complete; look for any errors in the above output" \ |
Christian Heimes | 292d351 | 2008-02-03 16:51:08 +0000 | [diff] [blame] | 96 | "or in build/$(BUILDER)/output.txt" |
| 97 | |
Benjamin Peterson | 28d88b4 | 2009-01-09 03:03:23 +0000 | [diff] [blame] | 98 | suspicious: BUILDER = suspicious |
| 99 | suspicious: build |
Georg Brandl | 19b3e00 | 2010-10-06 10:35:24 +0000 | [diff] [blame] | 100 | @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 Peterson | 28d88b4 | 2009-01-09 03:03:23 +0000 | [diff] [blame] | 103 | |
Christian Heimes | d3eb5a15 | 2008-02-24 00:38:49 +0000 | [diff] [blame] | 104 | coverage: BUILDER = coverage |
| 105 | coverage: build |
| 106 | @echo "Coverage finished; see c.txt and python.txt in build/coverage" |
| 107 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 108 | doctest: BUILDER = doctest |
| 109 | doctest: build |
Georg Brandl | 19b3e00 | 2010-10-06 10:35:24 +0000 | [diff] [blame] | 110 | @echo "Testing of doctests in the sources finished, look at the" \ |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 111 | "results in build/doctest/output.txt" |
| 112 | |
Georg Brandl | 6b38daa | 2008-06-01 21:05:17 +0000 | [diff] [blame] | 113 | pydoc-topics: BUILDER = pydoc-topics |
| 114 | pydoc-topics: build |
Georg Brandl | 19b3e00 | 2010-10-06 10:35:24 +0000 | [diff] [blame] | 115 | @echo "Building finished; now copy build/pydoc-topics/topics.py" \ |
Georg Brandl | 5617db8 | 2009-04-27 16:28:57 +0000 | [diff] [blame] | 116 | "to Lib/pydoc_data/topics.py" |
Georg Brandl | 6b38daa | 2008-06-01 21:05:17 +0000 | [diff] [blame] | 117 | |
Benjamin Peterson | 4118174 | 2008-07-02 20:22:54 +0000 | [diff] [blame] | 118 | htmlview: html |
| 119 | $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')" |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 120 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | clean: |
| 122 | -rm -rf build/* |
| 123 | -rm -rf tools/sphinx |
Benjamin Peterson | b05e73d | 2009-12-31 03:35:15 +0000 | [diff] [blame] | 124 | -rm -rf tools/pygments |
| 125 | -rm -rf tools/jinja2 |
| 126 | -rm -rf tools/docutils |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 127 | |
| 128 | dist: |
Georg Brandl | 38557f2 | 2010-08-03 12:36:57 +0000 | [diff] [blame] | 129 | rm -rf dist |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 130 | mkdir -p dist |
| 131 | |
| 132 | # archive the HTML |
| 133 | make html |
Benjamin Peterson | 9203501 | 2008-12-27 16:00:54 +0000 | [diff] [blame] | 134 | 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 Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 140 | |
| 141 | # archive the text build |
| 142 | make text |
Benjamin Peterson | 9203501 | 2008-12-27 16:00:54 +0000 | [diff] [blame] | 143 | 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 Brandl | 5617db8 | 2009-04-27 16:28:57 +0000 | [diff] [blame] | 149 | |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 150 | # archive the A4 latex |
Georg Brandl | 38557f2 | 2010-08-03 12:36:57 +0000 | [diff] [blame] | 151 | rm -rf build/latex |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 152 | make latex PAPER=a4 |
Georg Brandl | 692b3f8 | 2010-07-11 08:33:16 +0000 | [diff] [blame] | 153 | -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 154 | (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] | 155 | 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 Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 157 | |
| 158 | # archive the letter latex |
Georg Brandl | 38557f2 | 2010-08-03 12:36:57 +0000 | [diff] [blame] | 159 | rm -rf build/latex |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 160 | make latex PAPER=letter |
Georg Brandl | 692b3f8 | 2010-07-11 08:33:16 +0000 | [diff] [blame] | 161 | -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 162 | (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] | 163 | 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 Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 165 | |
Georg Brandl | 183fe81 | 2011-01-05 11:00:25 +0000 | [diff] [blame] | 166 | # 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 Brandl | 45f5337 | 2009-01-03 21:15:20 +0000 | [diff] [blame] | 177 | check: |
Georg Brandl | d509788 | 2009-01-03 21:30:40 +0000 | [diff] [blame] | 178 | $(PYTHON) tools/rstlint.py -i tools |
R. David Murray | e821cb6 | 2010-03-08 17:48:38 +0000 | [diff] [blame] | 179 | |
| 180 | serve: |
| 181 | ../Tools/scripts/serve.py build/html |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 182 | |
Georg Brandl | 49f4718 | 2010-03-13 13:42:16 +0000 | [diff] [blame] | 183 | # Targets for daily automated doc build |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 184 | |
| 185 | # for development releases: always build |
| 186 | autobuild-dev: |
| 187 | make update |
Georg Brandl | 49f4718 | 2010-03-13 13:42:16 +0000 | [diff] [blame] | 188 | make dist SPHINXOPTS='-A daily=1' |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 189 | |
Georg Brandl | 49f4718 | 2010-03-13 13:42:16 +0000 | [diff] [blame] | 190 | # for stable releases: only build if not in pre-release stage (alpha, beta, rc) |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 191 | autobuild-stable: |
| 192 | @case $(DISTVERSION) in *[abc]*) \ |
Georg Brandl | 49f4718 | 2010-03-13 13:42:16 +0000 | [diff] [blame] | 193 | echo "Not building; $(DISTVERSION) is not a release version."; \ |
| 194 | exit 1;; \ |
Georg Brandl | fe427fe | 2010-03-13 11:02:07 +0000 | [diff] [blame] | 195 | esac |
| 196 | @make autobuild-dev |