Debian Codegraph @

doc/Makefile

raw
1 # Makefile for Sphinx documentation
2 #
3
4 # PYVER needs to be major.minor, just "3" doesn't work - it will result in
5 # issues with the amendments to PYTHONPATH and install paths (see DIST_VARS).
6
7 # Use explicit "version_info" indexing since make cannot handle colon characters, and
8 # evaluate it now to allow easier debugging when printing the variable
9
10 PYVER:=$(shell python3 -c 'from sys import version_info as v; print("{0}.{1}".format(v[0], v[1]))')
11 PYTHON = python$(PYVER)
12
13 # You can set these variables from the command line.
14 SPHINXOPTS ?= -W
15 SPHINXBUILD ?= LANG=C sphinx-build
16 PAPER ?=
17 DOXYGEN ?= doxygen
18 # For merging a documentation archive into a git checkout of numpy/doc
19 # Turn a tag like v1.18.0 into 1.18
20 # Use sed -n -e 's/pattern/match/p' to return a blank value if no match
21 TAG ?= $(shell git describe --tag | sed -n -e's,v\([1-9]\.[0-9]*\)\.[0-9].*,\1,p')
22
23 FILES=
24
25 # Internal variables.
26 PAPEROPT_a4 = -D latex_paper_size=a4
27 PAPEROPT_letter = -D latex_paper_size=letter
28 ALLSPHINXOPTS = -T --keep-going -d build/doctrees $(PAPEROPT_$(PAPER)) \
29 $(SPHINXOPTS) source
30
31 .PHONY: help clean html web htmlhelp latex changes linkcheck \
32 dist dist-build gitwash-update version-check html-build latex-build \
33 merge-doc show docenv
34
35 #------------------------------------------------------------------------------
36
37 help:
38 @echo "Please use \`make <target>' where <target> is one of"
39 @echo " clean to remove generated doc files and start fresh"
40 @echo " docenv make a virtual environment in which to build docs"
41 @echo " html to make standalone HTML files"
42 @echo " htmlhelp to make HTML files and a HTML help project"
43 @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
44 @echo " changes to make an overview over all changed/added/deprecated items"
45 @echo " linkcheck to check all external links for integrity"
46 @echo " dist PYVER=... to make a distribution-ready tree"
47 @echo " gitwash-update GITWASH=path/to/gitwash update gitwash developer docs"
48 @echo " merge-doc TAG=... to clone numpy/doc and archive documentation into it"
49 @echo " show to show the html output in a browser"
50
51 clean:
52 -rm -rf build/*
53 -rm -rf source/.jupyterlite.doit.db
54 -rm -rf source/contents/*.ipynb
55 find . -name generated -type d -prune -exec rm -rf "{}" ";"
56
57 gitwash-update:
58 rm -rf source/dev/gitwash
59 install -d source/dev/gitwash
60 python $(GITWASH)/gitwash_dumper.py source/dev NumPy \
61 --repo-name=numpy \
62 --github-user=numpy
63 cat source/dev/gitwash_links.txt >> source/dev/gitwash/git_links.inc
64
65 #------------------------------------------------------------------------------
66 # Automated generation of all documents
67 #------------------------------------------------------------------------------
68
69 # Build the current numpy version, and extract docs from it.
70 # We have to be careful of some issues:
71 #
72 # - Everything must be done using the same Python version
73 #
74
75 #SPHINXBUILD="LANG=C sphinx-build"
76 NUMPYVER:=$(shell $(PYTHON) -c "import numpy; print(numpy.version.git_revision[:7])" 2>/dev/null)
77 GITVER ?= $(shell (cd ..; set -o pipefail && git rev-parse HEAD 2>/dev/null | cut -c1-7) || echo Unknown)
78
79 version-check:
80 ifeq "$(GITVER)" "Unknown"
81 # @echo sdist build with unlabeled sources
82 else ifeq ("", "$(NUMPYVER)")
83 @echo numpy not found, cannot build documentation without successful \"import numpy\"
84 @echo Try overriding the makefile PYTHON variable with '"make PYTHON=python $(MAKECMDGOALS)"'
85 @exit 1
86 else ifneq ($(NUMPYVER),$(GITVER))
87 @echo installed numpy $(NUMPYVER) != current repo git version \'$(GITVER)\'
88 @echo use '"make dist"' or '"GITVER=$(NUMPYVER) make $(MAKECMDGOALS) ..."'
89 @exit 1
90 else
91 # for testing
92 # @echo installed numpy $(NUMPYVER) matches git version $(GITVER); exit 1
93 endif
94
95
96 dist: build/dist.tar.gz
97
98 build/dist.tar.gz: real-dist
99
100 real-dist: html-build
101 cp -r build/html build/dist
102 cd build/html && zip -9r ../dist/numpy-html.zip .
103 cd build/dist && tar czf ../dist.tar.gz *
104 chmod ug=rwX,o=rX -R build/dist
105 find build/dist -type d -print0 | xargs -0r chmod g+s
106
107 merge-doc: build/dist.tar.gz
108 ifeq "$(TAG)" ""
109 echo tag "$(TAG)" not of the form 1.18;
110 exit 1;
111 endif
112 @# Only clone if the directory does not exist
113 @if ! test -d build/merge; then \
114 git clone https://github.com/numpy/doc build/merge; \
115 fi;
116 @# Remove any old content and copy in the new, add it to git
117 -rm -rf build/merge/$(TAG)/*
118 -mkdir -p build/merge/$(TAG)
119 @# -C changes working directory
120 tar -C build/merge/$(TAG) -xf build/dist.tar.gz
121 git -C build/merge add $(TAG)
122 @# For now, the user must do this. If it is onerous, automate it and change
123 @# the instructions in doc/RELEASE_WALKTHROUGH.rst
124 @echo " "
125 @echo New documentation archive added to ./build/merge.
126 @echo Now add/modify the appropriate section after
127 @echo " <!-- insert here -->"
128 @echo in build/merge/index.html,
129 @echo change _static/versions.json,
130 @echo and run \"python3 update.py\"
131 @echo then \"git commit\", \"git push\"
132
133
134 #------------------------------------------------------------------------------
135 # Basic Sphinx generation rules for different formats
136 #------------------------------------------------------------------------------
137
138 generate: build/generate-stamp
139 build/generate-stamp: $(wildcard source/reference/*.rst)
140 mkdir -p build
141 touch build/generate-stamp
142
143 html: version-check html-build
144 html-build: generate
145 mkdir -p build/html build/doctrees
146 $(PYTHON) preprocess.py
147 ifeq (, $(shell which $(DOXYGEN)))
148 @echo "Unable to find 'Doxygen:$(DOXYGEN)', skip generating C/C++ API from comment blocks."
149 else
150 $(DOXYGEN) build/doxygen/Doxyfile
151 endif
152 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html $(FILES)
153 $(PYTHON) postprocess.py html build/html/*.html
154 @echo
155 @echo "Build finished. The HTML pages are in build/html."
156
157 htmlhelp: generate version-check
158 mkdir -p build/htmlhelp build/doctrees
159 $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp $(FILES)
160 @echo
161 @echo "Build finished; now you can run HTML Help Workshop with the" \
162 ".hhp project file in build/htmlhelp."
163
164 htmlhelp-build: htmlhelp build/htmlhelp/numpy.chm
165 %.chm: %.hhp
166 -hhc.exe $^
167
168 qthelp: generate version-check
169 mkdir -p build/qthelp build/doctrees
170 $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp $(FILES)
171
172 latex: version-check latex-build
173 latex-build: generate
174 mkdir -p build/latex build/doctrees
175 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex $(FILES)
176 $(PYTHON) postprocess.py tex build/latex/*.tex
177 perl -pi -e 's/LATEXOPTS =/LATEXOPTS ?= --halt-on-error/' build/latex/Makefile
178 @echo
179 @echo "Build finished; the LaTeX files are in build/latex."
180 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
181 "run these through (pdf)latex."
182
183 coverage: build version-check
184 mkdir -p build/coverage build/doctrees
185 $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) build/coverage $(FILES)
186 @echo "Coverage finished; see c.txt and python.txt in build/coverage"
187
188 changes: generate version-check
189 mkdir -p build/changes build/doctrees
190 $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes $(FILES)
191 @echo
192 @echo "The overview file is in build/changes."
193
194 linkcheck: generate version-check
195 mkdir -p build/linkcheck build/doctrees
196 $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck $(FILES)
197 @echo
198 @echo "Link check complete; look for any errors in the above output " \
199 "or in build/linkcheck/output.txt."
200 texinfo:
201 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) build/texinfo
202 @echo
203 @echo "Build finished. The Texinfo files are in build/texinfo."
204 @echo "Run \`make' in that directory to run these through makeinfo" \
205 "(use \`make info' here to do that automatically)."
206
207 info:
208 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) build/texinfo
209 @echo "Running Texinfo files through makeinfo..."
210 make -C build/texinfo info
211 @echo "makeinfo finished; the Info files are in build/texinfo."
212
213
214 show:
215 @python -c "import webbrowser; webbrowser.open_new_tab('file://$(PWD)/build/html/index.html')"