| 1 | #
|
|---|
| 2 | # Makefile for Python documentation
|
|---|
| 3 | # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|---|
| 4 | #
|
|---|
| 5 |
|
|---|
| 6 | # You can set these variables from the command line.
|
|---|
| 7 | PYTHON = python
|
|---|
| 8 | SVNROOT = http://svn.python.org/projects
|
|---|
| 9 | SPHINXOPTS =
|
|---|
| 10 | PAPER =
|
|---|
| 11 | SOURCES =
|
|---|
| 12 | DISTVERSION = $(shell $(PYTHON) tools/sphinxext/patchlevel.py)
|
|---|
| 13 |
|
|---|
| 14 | ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \
|
|---|
| 15 | $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES)
|
|---|
| 16 |
|
|---|
| 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
|
|---|
| 20 |
|
|---|
| 21 | help:
|
|---|
| 22 | @echo "Please use \`make <target>' where <target> is one of"
|
|---|
| 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"
|
|---|
| 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 | # Note: if you update versions here, do the same in make.bat and README.txt
|
|---|
| 40 | checkout:
|
|---|
| 41 | @if [ ! -d tools/sphinx ]; then \
|
|---|
| 42 | echo "Checking out Sphinx..."; \
|
|---|
| 43 | svn checkout $(SVNROOT)/external/Sphinx-1.0.7/sphinx tools/sphinx; \
|
|---|
| 44 | fi
|
|---|
| 45 | @if [ ! -d tools/docutils ]; then \
|
|---|
| 46 | echo "Checking out Docutils..."; \
|
|---|
| 47 | svn checkout $(SVNROOT)/external/docutils-0.6/docutils tools/docutils; \
|
|---|
| 48 | fi
|
|---|
| 49 | @if [ ! -d tools/jinja2 ]; then \
|
|---|
| 50 | echo "Checking out Jinja..."; \
|
|---|
| 51 | svn checkout $(SVNROOT)/external/Jinja-2.3.1/jinja2 tools/jinja2; \
|
|---|
| 52 | fi
|
|---|
| 53 | @if [ ! -d tools/pygments ]; then \
|
|---|
| 54 | echo "Checking out Pygments..."; \
|
|---|
| 55 | svn checkout $(SVNROOT)/external/Pygments-1.3.1/pygments tools/pygments; \
|
|---|
| 56 | fi
|
|---|
| 57 |
|
|---|
| 58 | update: clean checkout
|
|---|
| 59 |
|
|---|
| 60 | build: checkout
|
|---|
| 61 | mkdir -p build/$(BUILDER) build/doctrees
|
|---|
| 62 | $(PYTHON) tools/sphinx-build.py $(ALLSPHINXOPTS)
|
|---|
| 63 | @echo
|
|---|
| 64 |
|
|---|
| 65 | html: BUILDER = html
|
|---|
| 66 | html: build
|
|---|
| 67 | @echo "Build finished. The HTML pages are in build/html."
|
|---|
| 68 |
|
|---|
| 69 | htmlhelp: BUILDER = htmlhelp
|
|---|
| 70 | htmlhelp: build
|
|---|
| 71 | @echo "Build finished; now you can run HTML Help Workshop with the" \
|
|---|
| 72 | "build/htmlhelp/pydoc.hhp project file."
|
|---|
| 73 |
|
|---|
| 74 | latex: BUILDER = latex
|
|---|
| 75 | latex: build
|
|---|
| 76 | @echo "Build finished; the LaTeX files are in build/latex."
|
|---|
| 77 | @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
|
|---|
| 78 | "run these through (pdf)latex."
|
|---|
| 79 |
|
|---|
| 80 | text: BUILDER = text
|
|---|
| 81 | text: build
|
|---|
| 82 | @echo "Build finished; the text files are in build/text."
|
|---|
| 83 |
|
|---|
| 84 | changes: BUILDER = changes
|
|---|
| 85 | changes: build
|
|---|
| 86 | @echo "The overview file is in build/changes."
|
|---|
| 87 |
|
|---|
| 88 | linkcheck: BUILDER = linkcheck
|
|---|
| 89 | linkcheck: build
|
|---|
| 90 | @echo "Link check complete; look for any errors in the above output" \
|
|---|
| 91 | "or in build/$(BUILDER)/output.txt"
|
|---|
| 92 |
|
|---|
| 93 | suspicious: BUILDER = suspicious
|
|---|
| 94 | suspicious: build
|
|---|
| 95 | @echo "Suspicious check complete; look for any errors in the above output" \
|
|---|
| 96 | "or in build/$(BUILDER)/suspicious.csv. If all issues are false" \
|
|---|
| 97 | "positives, append that file to tools/sphinxext/susp-ignored.csv."
|
|---|
| 98 |
|
|---|
| 99 | coverage: BUILDER = coverage
|
|---|
| 100 | coverage: build
|
|---|
| 101 | @echo "Coverage finished; see c.txt and python.txt in build/coverage"
|
|---|
| 102 |
|
|---|
| 103 | doctest: BUILDER = doctest
|
|---|
| 104 | doctest: build
|
|---|
| 105 | @echo "Testing of doctests in the sources finished, look at the" \
|
|---|
| 106 | "results in build/doctest/output.txt"
|
|---|
| 107 |
|
|---|
| 108 | pydoc-topics: BUILDER = pydoc-topics
|
|---|
| 109 | pydoc-topics: build
|
|---|
| 110 | @echo "Building finished; now copy build/pydoc-topics/topics.py" \
|
|---|
| 111 | "to Lib/pydoc_data/topics.py"
|
|---|
| 112 |
|
|---|
| 113 | htmlview: html
|
|---|
| 114 | $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')"
|
|---|
| 115 |
|
|---|
| 116 | clean:
|
|---|
| 117 | -rm -rf build/*
|
|---|
| 118 | -rm -rf tools/sphinx
|
|---|
| 119 | -rm -rf tools/pygments
|
|---|
| 120 | -rm -rf tools/jinja2
|
|---|
| 121 | -rm -rf tools/docutils
|
|---|
| 122 |
|
|---|
| 123 | dist:
|
|---|
| 124 | rm -rf dist
|
|---|
| 125 | mkdir -p dist
|
|---|
| 126 |
|
|---|
| 127 | # archive the HTML
|
|---|
| 128 | make html
|
|---|
| 129 | cp -pPR build/html dist/python-$(DISTVERSION)-docs-html
|
|---|
| 130 | tar -C dist -cf dist/python-$(DISTVERSION)-docs-html.tar python-$(DISTVERSION)-docs-html
|
|---|
| 131 | bzip2 -9 -k dist/python-$(DISTVERSION)-docs-html.tar
|
|---|
| 132 | (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-html.zip python-$(DISTVERSION)-docs-html)
|
|---|
| 133 | rm -r dist/python-$(DISTVERSION)-docs-html
|
|---|
| 134 | rm dist/python-$(DISTVERSION)-docs-html.tar
|
|---|
| 135 |
|
|---|
| 136 | # archive the text build
|
|---|
| 137 | make text
|
|---|
| 138 | cp -pPR build/text dist/python-$(DISTVERSION)-docs-text
|
|---|
| 139 | tar -C dist -cf dist/python-$(DISTVERSION)-docs-text.tar python-$(DISTVERSION)-docs-text
|
|---|
| 140 | bzip2 -9 -k dist/python-$(DISTVERSION)-docs-text.tar
|
|---|
| 141 | (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-text.zip python-$(DISTVERSION)-docs-text)
|
|---|
| 142 | rm -r dist/python-$(DISTVERSION)-docs-text
|
|---|
| 143 | rm dist/python-$(DISTVERSION)-docs-text.tar
|
|---|
| 144 |
|
|---|
| 145 | # archive the A4 latex
|
|---|
| 146 | rm -rf build/latex
|
|---|
| 147 | make latex PAPER=a4
|
|---|
| 148 | -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
|
|---|
| 149 | (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
|
|---|
| 150 | cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
|
|---|
| 151 | cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
|
|---|
| 152 |
|
|---|
| 153 | # archive the letter latex
|
|---|
| 154 | rm -rf build/latex
|
|---|
| 155 | make latex PAPER=letter
|
|---|
| 156 | -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
|
|---|
| 157 | (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
|
|---|
| 158 | cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
|
|---|
| 159 | cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2
|
|---|
| 160 |
|
|---|
| 161 | check:
|
|---|
| 162 | $(PYTHON) tools/rstlint.py -i tools
|
|---|
| 163 |
|
|---|
| 164 | serve:
|
|---|
| 165 | ../Tools/scripts/serve.py build/html
|
|---|
| 166 |
|
|---|
| 167 | # Targets for daily automated doc build
|
|---|
| 168 |
|
|---|
| 169 | # for development releases: always build
|
|---|
| 170 | autobuild-dev:
|
|---|
| 171 | make update
|
|---|
| 172 | make dist SPHINXOPTS='-A daily=1 -A versionswitcher=1'
|
|---|
| 173 |
|
|---|
| 174 | # for quick rebuilds (HTML only)
|
|---|
| 175 | autobuild-html:
|
|---|
| 176 | make html SPHINXOPTS='-A daily=1 -A versionswitcher=1'
|
|---|
| 177 |
|
|---|
| 178 | # for stable releases: only build if not in pre-release stage (alpha, beta, rc)
|
|---|
| 179 | autobuild-stable:
|
|---|
| 180 | @case $(DISTVERSION) in *[abc]*) \
|
|---|
| 181 | echo "Not building; $(DISTVERSION) is not a release version."; \
|
|---|
| 182 | exit 1;; \
|
|---|
| 183 | esac
|
|---|
| 184 | @make autobuild-dev
|
|---|
| 185 |
|
|---|
