Merge pull request #6501 from rgommers/doc-makefile

REL: add "make upload" command for built docs, update "make dist".

3 files changed, 45 insertions, 27 deletions

diff --git a/doc/HOWTO_BUILD_DOCS.rst.txt b/doc/HOWTO_BUILD_DOCS.rst.txt
index 79d76fb7d..8107aaa81 100644
--- a/doc/HOWTO_BUILD_DOCS.rst.txt
+++ b/doc/HOWTO_BUILD_DOCS.rst.txt
@@ -57,7 +57,7 @@ To build the PDF documentation, do instead::
 
 You will need to have Latex installed for this.
 
-In addition to the above, you can also do::
+Instead of the above, you can also do::
 
    make dist
 
@@ -65,14 +65,19 @@ which will rebuild Numpy, install it to a temporary location, and
 build the documentation in all formats. This will most likely again
 only work on Unix platforms.
 
+The documentation for Numpy distributed at http://docs.scipy.org in html and
+pdf format is also built with ``make dist``.  See `HOWTO RELEASE`_ for details on
+how to update http://docs.scipy.org.
+
 .. _Matplotlib: http://matplotlib.org/
+.. _HOWTO RELEASE: https://github.com/numpy/numpy/blob/master/doc/HOWTO_RELEASE.rst.txt
 
 Sphinx extensions
 -----------------
 
 Numpy's documentation uses several custom extensions to Sphinx.  These
-are shipped in the ``sphinxext/`` directory, and are automatically
-enabled when building Numpy's documentation.
+are shipped in the ``sphinxext/`` directory (as git submodules, as discussed
+above), and are automatically enabled when building Numpy's documentation.
 
 If you want to make use of these extensions in third-party
 projects, they are available on PyPi_ as the numpydoc_ package.
diff --git a/doc/HOWTO_RELEASE.rst.txt b/doc/HOWTO_RELEASE.rst.txt
index 5fed523c1..b77a6c25c 100644
--- a/doc/HOWTO_RELEASE.rst.txt
+++ b/doc/HOWTO_RELEASE.rst.txt
@@ -32,7 +32,7 @@ Doc wiki
 
 Release Scripts
 ---------------
-* https://github.com/certik/numpy-vendor
+* https://github.com/numpy/numpy-vendor
 
 
 Supported platforms and versions
@@ -217,7 +217,9 @@ Do::
     cd doc/
     make dist
 
-to check that the documentation is in a buildable state.
+to check that the documentation is in a buildable state.  See
+doc/HOWTO_BUILD_DOCS.rst.txt for more details and for how to update
+http://docs.scipy.org.
 
 Check deprecations
 ------------------
@@ -292,9 +294,11 @@ Now, set ``release=True`` in setup.py, then
 ::
 
     git commit -m "REL: Release." setup.py
-    git tag <version>
+    git tag -s <version>
     git push origin <version>
 
+Note: ``git tag -s`` creates a signed tag - make sure your PGP key is public.
+
 Apply patch to fix bogus strides
 --------------------------------
 NPY_RELAXED_STRIDE_CHECKING was made the default in Numpy 1.10 and bogus
@@ -336,32 +340,24 @@ works.
 
 Update docs.scipy.org
 ---------------------
-Do the following (or ask the doc people to take care of it):
-
-Rebuild and upload documentation:
+All documentation for a release can be updated on http://docs.scipy.org/ with:
 
-- ``cd numpy/doc``
-- ``make dist``
-- Check that the built documentation is OK.
-- ``touch output-is-fine``
-- ``make upload UPLOAD_TARGET=USERNAME@docs.scipy.org:/home/docserver/www-root/doc/numpy-1.5.x/``
+    make dist
+    make upload USERNAME=<yourname> RELEASE=1.11.0
 
-where USERNAME should be replaced by your account on
-``docs.scipy.org``, and ``numpy-1.5.x`` by the version number of the
-*release series*. For instance, for Numpy 1.5.1, it should be
-``numpy-1.5.x`` and for Numpy 2.0.0 ``numpy-2.0.x``.
+Note that ``<username>`` must have SSH credentials on the server.  If you don't
+have those, ask someone who does (the list currently includes @rgommers,
+@juliantaylor and @pv).
 
-Rebuild and upload ``docs.scipy.org`` front page, if the release
-series is a new one. The front page sources are located in the Scipy
-repository:
+Also rebuild and upload ``docs.scipy.org`` front page, if the release
+series is a new one. The front page sources have their own repo:
+https://github.com/scipy/docs.scipy.org.  Do the following:
 
-- ``cd scipy/doc/frontpage``
-- Edit ``_templates/indexcontent.html`` to add links to the new release series.
+- Update ``index.rst`` for the new version.
 - ``make dist``
 - Check that the built documentation is OK.
 - ``touch output-is-fine``
-- ``make upload USER=USERNAME``
-
+- ``make upload USERNAME=<username> RELEASE=1.x.y``
 
 Update scipy.org
 ----------------
diff --git a/doc/Makefile b/doc/Makefile
index d8c1ab918..b52933e14 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -32,6 +32,7 @@ help:
 	@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"
 
 clean:
 	-rm -rf build/* source/reference/generated
@@ -59,6 +60,7 @@ gitwash-update:
 
 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)" SPHINXOPTS="$(SPHINXOPTS)"
 
@@ -72,8 +74,8 @@ real-dist: dist-build html html-scipyorg
 	-rm -rf build/dist
 	cp -r build/html-scipyorg build/dist
 	cd build/html && zip -9r ../dist/numpy-html.zip .
-	cp build/latex/numpy-*.pdf build/dist
-	-zip build/dist/numpy-chm.zip build/htmlhelp/numpy.chm
+	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
@@ -84,6 +86,21 @@ dist-build:
 	install -d $(subst :, ,$(INSTALL_PPH))
 	$(PYTHON) `which easy_install` --prefix=$(INSTALL_DIR) ../dist/*.egg
 
+upload:
+	# 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)@new.scipy.org mkdir $(UPLOAD_DIR)
+	scp build/dist.tar.gz $(USERNAME)@new.scipy.org:$(UPLOAD_DIR)
+	ssh $(USERNAME)@new.scipy.org tar xvC $(UPLOAD_DIR) \
+	    -zf $(UPLOAD_DIR)/dist.tar.gz
+	ssh $(USERNAME)@new.scipy.org mv $(UPLOAD_DIR)/numpy-ref.pdf \
+	    $(UPLOAD_DIR)/numpy-ref-$(RELEASE).pdf
+	ssh $(USERNAME)@new.scipy.org mv $(UPLOAD_DIR)/numpy-user.pdf \
+	    $(UPLOAD_DIR)/numpy-user-$(RELEASE).pdf
+	ssh $(USERNAME)@new.scipy.org mv $(UPLOAD_DIR)/numpy-html.zip \
+	    $(UPLOAD_DIR)/numpy-html-$(RELEASE).zip
+	ssh $(USERNAME)@new.scipy.org /srv/bin/fixperm-scipy_org.sh
 
 #------------------------------------------------------------------------------
 # Basic Sphinx generation rules for different formats