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