| 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')" |