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 10PYVER:=$(shell python3 -c 'from sys import version_info as v; print("{0}.{1}".format(v[0], v[1]))') 11PYTHON = python$(PYVER) 12 13# You can set these variables from the command line. 14SPHINXOPTS ?= 15SPHINXBUILD ?= LANG=C sphinx-build 16PAPER ?= 17# For merging a documentation archive into a git checkout of numpy/doc 18# Turn a tag like v1.18.0 into 1.18 19# Use sed -n -e 's/patttern/match/p' to return a blank value if no match 20TAG ?= $(shell git describe --tag | sed -n -e's,v\([1-9]\.[0-9]*\)\.[0-9].*,\1,p') 21 22FILES= 23 24# Internal variables. 25PAPEROPT_a4 = -D latex_paper_size=a4 26PAPEROPT_letter = -D latex_paper_size=letter 27ALLSPHINXOPTS = -WT --keep-going -d build/doctrees $(PAPEROPT_$(PAPER)) \ 28 $(SPHINXOPTS) source 29 30.PHONY: help clean html web pickle htmlhelp latex changes linkcheck \ 31 dist dist-build gitwash-update version-check html-build latex-build \ 32 merge-doc show 33 34#------------------------------------------------------------------------------ 35 36help: 37 @echo "Please use \`make <target>' where <target> is one of" 38 @echo " html to make standalone HTML files" 39 @echo " html-scipyorg to make standalone HTML files with scipy.org theming" 40 @echo " pickle to make pickle files (usable by e.g. sphinx-web)" 41 @echo " htmlhelp to make HTML files and a HTML help project" 42 @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 43 @echo " changes to make an overview over all changed/added/deprecated items" 44 @echo " linkcheck to check all external links for integrity" 45 @echo " dist PYVER=... to make a distribution-ready tree" 46 @echo " gitwash-update GITWASH=path/to/gitwash update gitwash developer docs" 47 @echo " upload USERNAME=... RELEASE=... to upload built docs to docs.scipy.org" 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 51clean: 52 -rm -rf build/* 53 find . -name generated -type d -prune -exec rm -rf "{}" ";" 54 55gitwash-update: 56 rm -rf source/dev/gitwash 57 install -d source/dev/gitwash 58 python $(GITWASH)/gitwash_dumper.py source/dev NumPy \ 59 --repo-name=numpy \ 60 --github-user=numpy 61 cat source/dev/gitwash_links.txt >> source/dev/gitwash/git_links.inc 62 63#------------------------------------------------------------------------------ 64# Automated generation of all documents 65#------------------------------------------------------------------------------ 66 67# Build the current numpy version, and extract docs from it. 68# We have to be careful of some issues: 69# 70# - Everything must be done using the same Python version 71# - We must use eggs (otherwise they might override PYTHONPATH on import). 72# - Different versions of easy_install install to different directories (!) 73# 74 75 76INSTALL_DIR = $(CURDIR)/build/inst-dist 77INSTALL_PPH = $(INSTALL_DIR)/lib/python$(PYVER)/site-packages:$(INSTALL_DIR)/local/lib/python$(PYVER)/site-packages:$(INSTALL_DIR)/lib/python$(PYVER)/dist-packages:$(INSTALL_DIR)/local/lib/python$(PYVER)/dist-packages 78UPLOAD_DIR=/srv/docs_scipy_org/doc/numpy-$(RELEASE) 79 80DIST_VARS=SPHINXBUILD="LANG=C PYTHONPATH=$(INSTALL_PPH) python$(PYVER) `which sphinx-build`" PYTHON="PYTHONPATH=$(INSTALL_PPH) python$(PYVER)" 81 82NUMPYVER:=$(shell $(PYTHON) -c "import numpy; print(numpy.version.git_revision[:10])" 2>/dev/null) 83GITVER ?= $(shell cd ..; $(PYTHON) -c "from setup import git_version; \ 84 print(git_version()[:10])") 85 86version-check: 87ifeq "$(GITVER)" "Unknown" 88 # @echo sdist build with unlabeled sources 89else ifeq ("", "$(NUMPYVER)") 90 @echo numpy not found, cannot build documentation without successful \"import numpy\" 91 @exit 1 92else ifneq ($(NUMPYVER),$(GITVER)) 93 @echo installed numpy $(NUMPYVER) != current repo git version \'$(GITVER)\' 94 @echo use '"make dist"' or '"GITVER=$(NUMPYVER) make $(MAKECMDGOALS) ..."' 95 @exit 1 96else 97 # for testing 98 # @echo installed numpy $(NUMPYVER) matches git version $(GITVER); exit 1 99endif 100 101 102dist: build/dist.tar.gz 103 104build/dist.tar.gz: 105 make $(DIST_VARS) real-dist 106 107real-dist: dist-build html-build 108 test -d build/latex || make latex-build 109 make -C build/latex all-pdf 110 -rm -rf build/dist 111 cp -r build/html build/dist 112 cd build/html && zip -9r ../dist/numpy-html.zip . 113 cp build/latex/numpy-ref.pdf build/dist 114 cp build/latex/numpy-user.pdf build/dist 115 cd build/dist && tar czf ../dist.tar.gz * 116 chmod ug=rwX,o=rX -R build/dist 117 find build/dist -type d -print0 | xargs -0r chmod g+s 118 119dist-build: 120 rm -f ../dist/*.egg 121 cd .. && $(PYTHON) setup.py bdist_egg 122 install -d $(subst :, ,$(INSTALL_PPH)) 123 $(PYTHON) `which easy_install` --prefix=$(INSTALL_DIR) ../dist/*.egg 124 125upload: build/dist.tar.gz 126 # SSH must be correctly configured for this to work. 127 # Assumes that ``make dist`` was already run 128 # Example usage: ``make upload USERNAME=rgommers RELEASE=1.10.1`` 129 ssh $(USERNAME)@docs.scipy.org mkdir $(UPLOAD_DIR) 130 scp build/dist.tar.gz $(USERNAME)@docs.scipy.org:$(UPLOAD_DIR) 131 ssh $(USERNAME)@docs.scipy.org tar xvC $(UPLOAD_DIR) \ 132 -zf $(UPLOAD_DIR)/dist.tar.gz 133 ssh $(USERNAME)@docs.scipy.org mv $(UPLOAD_DIR)/numpy-ref.pdf \ 134 $(UPLOAD_DIR)/numpy-ref-$(RELEASE).pdf 135 ssh $(USERNAME)@docs.scipy.org mv $(UPLOAD_DIR)/numpy-user.pdf \ 136 $(UPLOAD_DIR)/numpy-user-$(RELEASE).pdf 137 ssh $(USERNAME)@docs.scipy.org mv $(UPLOAD_DIR)/numpy-html.zip \ 138 $(UPLOAD_DIR)/numpy-html-$(RELEASE).zip 139 ssh $(USERNAME)@docs.scipy.org rm $(UPLOAD_DIR)/dist.tar.gz 140 ssh $(USERNAME)@docs.scipy.org ln -snf numpy-$(RELEASE) /srv/docs_scipy_org/doc/numpy 141 142 143merge-doc: build/dist.tar.gz 144ifeq "$(TAG)" "" 145 echo tag "$(TAG)" not of the form 1.18; 146 exit 1; 147endif 148 @# Only clone if the directory does not exist 149 @if ! test -d build/merge; then \ 150 git clone https://github.com/numpy/doc build/merge; \ 151 fi; 152 @# Remove any old content and copy in the new, add it to git 153 -rm -rf build/merge/$(TAG)/* 154 -mkdir -p build/merge/$(TAG) 155 @# -C changes working directory 156 tar -C build/merge/$(TAG) -xf build/dist.tar.gz 157 git -C build/merge add $(TAG) 158 @# For now, the user must do this. If it is onerous, automate it and change 159 @# the instructions in doc/HOWTO_RELEASE.rst.txt 160 @echo " " 161 @echo New documentation archive added to ./build/merge. 162 @echo Now add/modify the appropriate section after 163 @echo " <!-- insert here -->" 164 @echo in build/merge/index.html, 165 @echo then \"git commit\", \"git push\" 166 167 168#------------------------------------------------------------------------------ 169# Basic Sphinx generation rules for different formats 170#------------------------------------------------------------------------------ 171 172generate: build/generate-stamp 173build/generate-stamp: $(wildcard source/reference/*.rst) 174 mkdir -p build 175 touch build/generate-stamp 176 177html: version-check html-build 178html-build: generate 179 mkdir -p build/html build/doctrees 180 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html $(FILES) 181 $(PYTHON) postprocess.py html build/html/*.html 182 @echo 183 @echo "Build finished. The HTML pages are in build/html." 184 185html-scipyorg: 186 mkdir -p build/html build/doctrees 187 $(SPHINXBUILD) -t scipyorg -b html $(ALLSPHINXOPTS) build/html-scipyorg $(FILES) 188 @echo 189 @echo "Build finished. The HTML pages are in build/html-scipyorg." 190 191pickle: generate version-check 192 mkdir -p build/pickle build/doctrees 193 $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle $(FILES) 194 @echo 195 @echo "Build finished; now you can process the pickle files or run" 196 @echo " sphinx-web build/pickle" 197 @echo "to start the sphinx-web server." 198 199web: pickle 200 201htmlhelp: generate version-check 202 mkdir -p build/htmlhelp build/doctrees 203 $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp $(FILES) 204 @echo 205 @echo "Build finished; now you can run HTML Help Workshop with the" \ 206 ".hhp project file in build/htmlhelp." 207 208htmlhelp-build: htmlhelp build/htmlhelp/numpy.chm 209%.chm: %.hhp 210 -hhc.exe $^ 211 212qthelp: generate version-check 213 mkdir -p build/qthelp build/doctrees 214 $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp $(FILES) 215 216latex: version-check latex-build 217latex-build: generate 218 mkdir -p build/latex build/doctrees 219 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex $(FILES) 220 $(PYTHON) postprocess.py tex build/latex/*.tex 221 perl -pi -e 's/LATEXOPTS =/LATEXOPTS ?= --halt-on-error/' build/latex/Makefile 222 @echo 223 @echo "Build finished; the LaTeX files are in build/latex." 224 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ 225 "run these through (pdf)latex." 226 227coverage: build version-check 228 mkdir -p build/coverage build/doctrees 229 $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) build/coverage $(FILES) 230 @echo "Coverage finished; see c.txt and python.txt in build/coverage" 231 232changes: generate version-check 233 mkdir -p build/changes build/doctrees 234 $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes $(FILES) 235 @echo 236 @echo "The overview file is in build/changes." 237 238linkcheck: generate version-check 239 mkdir -p build/linkcheck build/doctrees 240 $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck $(FILES) 241 @echo 242 @echo "Link check complete; look for any errors in the above output " \ 243 "or in build/linkcheck/output.txt." 244 245texinfo: 246 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) build/texinfo 247 @echo 248 @echo "Build finished. The Texinfo files are in build/texinfo." 249 @echo "Run \`make' in that directory to run these through makeinfo" \ 250 "(use \`make info' here to do that automatically)." 251 252info: 253 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) build/texinfo 254 @echo "Running Texinfo files through makeinfo..." 255 make -C build/texinfo info 256 @echo "makeinfo finished; the Info files are in build/texinfo." 257 258show: 259 @python -c "import webbrowser; webbrowser.open_new_tab('file://$(PWD)/build/html/index.html')" 260 261