MAINT: Update the documentation Makefile

This does several things

- Uses a virtual environment for the documentent build. This allows
  installing the proper NumPy version with pip and works with all
  recent Python versions.
- Installs the dependencies current in the {doc|test}requirements files.
  That makes it easier to insure that the proper versions are used.
- Removes the latex/pdf builds. Those builds are currently buggy and
  hard to maintain and we have chosen to remove the pdf documents until
  that is fixed. Removing them cleans up the file to some extent.

This all makes it easier to document how to build the docs.  I was
editing the Makefile on the fly before this, and that sort of knowledge
is tricky to pass on to new maintainers.

.gitignore

@@ -68,6 +68,7 @@ _build
 # setup.py dist directory
 dist
 doc/build
+doc/docenv
 doc/cdoc/build
 # Egg metadata
 *.egg-info

doc/Makefile

@@ -26,33 +26,42 @@ FILES=
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -WT --keep-going -d build/doctrees $(PAPEROPT_$(PAPER)) \
-  $(SPHINXOPTS) source
+                  $(SPHINXOPTS) source
 
-.PHONY: help clean html web pickle htmlhelp latex changes linkcheck \
-		dist dist-build gitwash-update version-check html-build latex-build \
-		merge-doc show
+.PHONY: help clean html web htmlhelp latex changes linkcheck \
+	dist dist-build gitwash-update version-check html-build latex-build \
+	merge-doc show docenv
 
 #------------------------------------------------------------------------------
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  clean     to remove generated doc files and start fresh"
+	@echo "  docenv    make a virtual environment in which to build docs"
 	@echo "  html      to make standalone HTML files"
-	@echo "  html-scipyorg  to make standalone HTML files with scipy.org theming"
-	@echo "  pickle    to make pickle files (usable by e.g. sphinx-web)"
 	@echo "  htmlhelp  to make HTML files and a HTML help project"
 	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  changes   to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck to check all external links for integrity"
 	@echo "  dist PYVER=... to make a distribution-ready tree"
 	@echo "  gitwash-update GITWASH=path/to/gitwash  update gitwash developer docs"
-	@echo "  upload USERNAME=... RELEASE=... to upload built docs to docs.scipy.org"
 	@echo "  merge-doc TAG=... to clone numpy/doc and archive documentation into it"
 	@echo "  show      to show the html output in a browser"
 
 clean:
 	-rm -rf build/*
 	find . -name generated -type d -prune -exec rm -rf "{}" ";"
 
+docenv:
+	$(PYTHON) -mvenv docenv
+	( \
+            . docenv/bin/activate; \
+            pip install -q --upgrade pip; \
+            pip install -q  -r ../test_requirements.txt; \
+            pip install -q  -r ../doc_requirements.txt; \
+            pip install -q ..; \
+	)
+
 gitwash-update:
 	rm -rf source/dev/gitwash
 	install -d source/dev/gitwash
@@ -69,17 +78,9 @@ gitwash-update:
 # We have to be careful of some issues:
 #
 # - Everything must be done using the same Python version
-# - We must use eggs (otherwise they might override PYTHONPATH on import).
-# - Different versions of easy_install install to different directories (!)
 #
 
-
-INSTALL_DIR = $(CURDIR)/build/inst-dist
-INSTALL_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
-UPLOAD_DIR=/srv/docs_scipy_org/doc/numpy-$(RELEASE)
-
-DIST_VARS=SPHINXBUILD="LANG=C PYTHONPATH=$(INSTALL_PPH) python$(PYVER) `which sphinx-build`" PYTHON="PYTHONPATH=$(INSTALL_PPH) python$(PYVER)"
-
+#SPHINXBUILD="LANG=C sphinx-build"
 NUMPYVER:=$(shell $(PYTHON) -c "import numpy; print(numpy.version.git_revision[:10])" 2>/dev/null)
 GITVER ?= $(shell cd ..; $(PYTHON) -c "import versioneer as v; print(v.get_versions()['full-revisionid'][:10])")
 
@@ -102,45 +103,15 @@ endif
 
 dist: build/dist.tar.gz
 
-build/dist.tar.gz:
-	make $(DIST_VARS) real-dist
+build/dist.tar.gz: real-dist
 
-real-dist: dist-build html-build
-	test -d build/latex || make latex-build
-	make -C build/latex all-pdf
-	-rm -rf build/dist
+real-dist: html-build
 	cp -r build/html build/dist
 	cd build/html && zip -9r ../dist/numpy-html.zip .
-	cp build/latex/numpy-ref.pdf build/dist
-	cp build/latex/numpy-user.pdf build/dist
 	cd build/dist && tar czf ../dist.tar.gz *
 	chmod ug=rwX,o=rX -R build/dist
 	find build/dist -type d -print0 | xargs -0r chmod g+s
 
-dist-build:
-	rm -f ../dist/*.egg
-	cd .. && $(PYTHON) setup.py bdist_egg
-	install -d $(subst :, ,$(INSTALL_PPH))
-	$(PYTHON) `which easy_install` --prefix=$(INSTALL_DIR) ../dist/*.egg
-
-upload: build/dist.tar.gz
-	# SSH must be correctly configured for this to work.
-	# Assumes that ``make dist`` was already run
-	# Example usage: ``make upload USERNAME=rgommers RELEASE=1.10.1``
-	ssh $(USERNAME)@docs.scipy.org mkdir $(UPLOAD_DIR)
-	scp build/dist.tar.gz $(USERNAME)@docs.scipy.org:$(UPLOAD_DIR)
-	ssh $(USERNAME)@docs.scipy.org tar xvC $(UPLOAD_DIR) \
-	    -zf $(UPLOAD_DIR)/dist.tar.gz
-	ssh $(USERNAME)@docs.scipy.org mv $(UPLOAD_DIR)/numpy-ref.pdf \
-	    $(UPLOAD_DIR)/numpy-ref-$(RELEASE).pdf
-	ssh $(USERNAME)@docs.scipy.org mv $(UPLOAD_DIR)/numpy-user.pdf \
-	    $(UPLOAD_DIR)/numpy-user-$(RELEASE).pdf
-	ssh $(USERNAME)@docs.scipy.org mv $(UPLOAD_DIR)/numpy-html.zip \
-	    $(UPLOAD_DIR)/numpy-html-$(RELEASE).zip
-	ssh $(USERNAME)@docs.scipy.org rm $(UPLOAD_DIR)/dist.tar.gz
-	ssh $(USERNAME)@docs.scipy.org ln -snf numpy-$(RELEASE) /srv/docs_scipy_org/doc/numpy
-
-
 merge-doc: build/dist.tar.gz
 ifeq "$(TAG)" ""
 	echo tag "$(TAG)" not of the form 1.18;
@@ -189,22 +160,6 @@ endif
 	@echo
 	@echo "Build finished. The HTML pages are in build/html."
 
-html-scipyorg:
-	mkdir -p build/html build/doctrees
-	$(SPHINXBUILD) -t scipyorg -b html $(ALLSPHINXOPTS) build/html-scipyorg $(FILES)
-	@echo
-	@echo "Build finished. The HTML pages are in build/html-scipyorg."
-
-pickle: generate version-check
-	mkdir -p build/pickle build/doctrees
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle $(FILES)
-	@echo
-	@echo "Build finished; now you can process the pickle files or run"
-	@echo "  sphinx-web build/pickle"
-	@echo "to start the sphinx-web server."
-
-web: pickle
-
 htmlhelp: generate version-check
 	mkdir -p build/htmlhelp build/doctrees
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp $(FILES)
@@ -248,7 +203,6 @@ linkcheck: generate version-check
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in build/linkcheck/output.txt."
-
 texinfo:
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) build/texinfo
 	@echo
@@ -262,5 +216,6 @@ info:
 	make -C build/texinfo info
 	@echo "makeinfo finished; the Info files are in build/texinfo."
 
+
 show:
 	@python -c "import webbrowser; webbrowser.open_new_tab('file://$(PWD)/build/html/index.html')"