MAINT,DOC: Update release guide

4 files changed, 106 insertions, 110 deletions

diff --git a/doc/BRANCH_WALKTHROUGH.rst b/doc/BRANCH_WALKTHROUGH.rst
index 95de5464b..2d26eebc2 100644
--- a/doc/BRANCH_WALKTHROUGH.rst
+++ b/doc/BRANCH_WALKTHROUGH.rst
@@ -1,9 +1,10 @@
-This file contains a walkthrough of branching NumPy 1.21.x on Linux.  The
+This guide contains a walkthrough of branching NumPy 1.21.x on Linux.  The
 commands can be copied into the command line, but be sure to replace 1.21 and
 1.22 by the correct versions. It is good practice to make ``.mailmap`` as
 current as possible before making the branch, that may take several weeks.
 
-This should be read together with the general directions in `releasing`.
+This should be read together with the
+:ref:`general release guide <prepare_release>`.
 
 Branching
 =========
diff --git a/doc/HOWTO_RELEASE.rst b/doc/HOWTO_RELEASE.rst
index 830e86791..d1b073206 100644
--- a/doc/HOWTO_RELEASE.rst
+++ b/doc/HOWTO_RELEASE.rst
@@ -1,33 +1,25 @@
-This file gives an overview of what is necessary to build binary releases for
-NumPy.
+These instructions give an overview of what is necessary to build binary
+releases for NumPy.
 
 Current build and release info
 ==============================
-The current info on building and releasing NumPy and SciPy is scattered in
-several places. It should be summarized in one place, updated, and where
-necessary described in more detail. The sections below list all places where
-useful info can be found.
 
+Useful info can be found in the following locations:
 
-Source tree
------------
-- INSTALL.rst
-- pavement.py
+* **Source tree**
 
+  - `INSTALL.rst <https://github.com/numpy/numpy/blob/main/INSTALL.rst>`_
+  - `pavement.py <https://github.com/numpy/numpy/blob/main/pavement.py>`_
 
-NumPy Docs
-----------
-- https://github.com/numpy/numpy/blob/main/doc/HOWTO_RELEASE.rst
+* **NumPy docs**
 
+  - https://github.com/numpy/numpy/blob/main/doc/HOWTO_RELEASE.rst
+  - https://github.com/numpy/numpy/blob/main/doc/RELEASE_WALKTHROUGH.rst
+  - https://github.com/numpy/numpy/blob/main/doc/BRANCH_WALKTHROUGH.rst
 
-SciPy.org wiki
---------------
-- https://www.scipy.org/Installing_SciPy and links on that page.
+* **Release scripts**
 
-
-Release Scripts
----------------
-- https://github.com/numpy/numpy-vendor
+  - https://github.com/numpy/numpy-vendor
 
 
 Supported platforms and versions
@@ -37,33 +29,29 @@ are supported; For the first half of 2020, this will be Python >= 3.6. We test
 NumPy against all these versions every time we merge code to main.  Binary
 installers may be available for a subset of these versions (see below).
 
-OS X
-----
-OS X versions >= 10.9 are supported, for Python version support see
-:ref:`NEP 29 <NEP29>`. We build binary wheels for
-OSX that are compatible with Python.org Python, system Python, homebrew and
-macports - see this `OSX wheel building summary
-<https://github.com/MacPython/wiki/wiki/Spinning-wheels>`_ for details.
+* **OS X**
 
+  OS X versions >= 10.9 are supported, for Python version support see
+  :ref:`NEP 29 <NEP29>`. We build binary wheels for OSX that are compatible with
+  Python.org Python, system Python, homebrew and macports - see this
+  `OSX wheel building summary <https://github.com/MacPython/wiki/wiki/Spinning-wheels>`_
+  for details.
 
-Windows
--------
-We build 32- and 64-bit wheels on Windows. Windows 7, 8 and 10 are supported.
-We build NumPy using the `mingw-w64 toolchain`_ on Appveyor.
+* **Windows**
 
+  We build 32- and 64-bit wheels on Windows. Windows 7, 8 and 10 are supported.
+  We build NumPy using the `mingw-w64 toolchain`_ on Appveyor.
 
-Linux
------
-We build and ship `manylinux1 <https://www.python.org/dev/peps/pep-0513>`_
-wheels for NumPy.  Many Linux distributions include their own binary builds
-of NumPy.
+* **Linux**
 
+  We build and ship `manylinux1 <https://www.python.org/dev/peps/pep-0513>`_
+  wheels for NumPy.  Many Linux distributions include their own binary builds
+  of NumPy.
 
-BSD / Solaris
--------------
-No binaries are provided, but successful builds on Solaris and BSD have been
-reported.
+* **BSD / Solaris**
 
+  No binaries are provided, but successful builds on Solaris and BSD have been
+  reported.
 
 Tool chain
 ==========
@@ -91,7 +79,8 @@ files in the NumPy distribution to ``.c`` files.
 .. _mingw-w64 toolchain : https://mingwpy.github.io
 
 OpenBLAS
-------------
+--------
+
 All the wheels link to a version of OpenBLAS_ supplied via the openblas-libs_ repo.
 The shared object (or DLL) is shipped with in the wheel, renamed to prevent name
 collisions with other OpenBLAS shared objects that may exist in the filesystem.
@@ -128,7 +117,7 @@ twine keyring_  documentation for how to do that.
 .. _keyring: https://twine.readthedocs.io/en/stable/#keyring-support
 
 
-Generating author/pr lists
+Generating author/PR lists
 --------------------------
 You will need a personal access token
 `<https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/>`_
@@ -138,33 +127,21 @@ so that scripts can access the github NumPy repository.
 - pygithub (pip)
 
 
-Virtualenv
-----------
-Virtualenv is a very useful tool to keep several versions of packages around.
-It is also used when building the documentation.
-
-
 What is released
 ================
 
-Wheels
-------
-We currently support Python 3.8-3.10 on Windows, OSX, and Linux
-
-* Windows: 32-bit and 64-bit wheels built using Github actions;
-* OSX: x64_86 and arm64 OSX wheels built using Github actions;
-* Linux: x64_86 and aarch64 Manylinux2014 wheels built using Github actions.
-
+* **Wheels**
+  We currently support Python 3.8-3.10 on Windows, OSX, and Linux.
 
-Other
------
-- Release Notes
-- Changelog
+  * Windows: 32-bit and 64-bit wheels built using Github actions;
+  * OSX: x64_86 and arm64 OSX wheels built using Github actions;
+  * Linux: x64_86 and aarch64 Manylinux2014 wheels built using Github actions.
 
+* **Other**
+  Release notes and changelog
 
-Source distribution
--------------------
-We build source releases in the .tar.gz format.
+* **Source distribution**
+  We build source releases in the .tar.gz format.
 
 
 Release process
@@ -199,10 +176,10 @@ Step-by-Step Directions below.
 
 Check deprecations
 ------------------
-Before the release branch is made, it should be checked that all deprecated
-code that should be removed is actually removed, and all new deprecations say
-in the docstring or deprecation warning at what version the code will be
-removed.
+Before :ref:`the release branch is made <branching>`, it should be checked that
+all deprecated code that should be removed is actually removed, and all new
+deprecations say in the docstring or deprecation warning at what version the
+code will be removed.
 
 Check the C API version number
 ------------------------------
diff --git a/doc/RELEASE_WALKTHROUGH.rst b/doc/RELEASE_WALKTHROUGH.rst
index 863b6dab3..b48697159 100644
--- a/doc/RELEASE_WALKTHROUGH.rst
+++ b/doc/RELEASE_WALKTHROUGH.rst
@@ -1,10 +1,12 @@
-This file contains a walkthrough of the NumPy 1.21.0 release on Linux, modified
-for building on azure and uploading to anaconda.org The commands can be copied
-into the command line, but be sure to replace 1.21.0 by the correct version.
-This should be read together with the general directions in `releasing`.
+This is a walkthrough of the NumPy 1.21.0 release on Linux, modified for
+building on azure and uploading to `anaconda.org`_. The commands can be
+copied into the command line, but be sure to replace 1.21.0 by the correct
+version. This should be read together with the
+:ref:`general release guide <prepare_release>`.
 
+.. _anaconda.org : https://anaconda.org
 
-Facility Preparation
+Facility preparation
 ====================
 
 Before beginning to make a release, use the ``*_requirements.txt`` files to
@@ -20,7 +22,7 @@ token (PAT) to push the documentation. There are a few ways to streamline things
   online twine documentation for details.
 
 
-Release Preparation
+Release preparation
 ===================
 
 Backport Pull Requests
@@ -30,7 +32,7 @@ Changes that have been marked for this release must be backported to the
 maintenance/1.21.x branch.
 
 
-Update Release documentation
+Update release documentation
 ----------------------------
 
 Four documents usually need to be updated or created before making a release:
@@ -76,17 +78,17 @@ done. Note that the ``:orphan:`` markup at the top, if present, will need
 changing to ``.. currentmodule:: numpy`` and the ``doc/source/release.rst``
 index file will need updating.
 
-Check the pavement.py file
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Check the ``pavement.py`` file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Check that the pavement.py file points to the correct release notes. It should
 have been updated after the last release, but if not, fix it now::
 
-    $gvim pavement.py
+    $ gvim pavement.py
 
 
-Release  Walkthrough
-====================
+Release walkthrough
+===================
 
 Note that in the code snippets below, ``upstream`` refers to the root repository on
 GitHub and ``origin`` to its fork in your personal GitHub repositories. You may
@@ -94,8 +96,8 @@ need to make adjustments if you have not forked the repository but simply
 cloned it locally. You can also edit ``.git/config`` and add ``upstream`` if it
 isn't already present.
 
-Prepare the release commit
---------------------------
+1. Prepare the release commit
+-----------------------------
 
 Checkout the branch for the release, make sure it is up to date, and clean the
 repository::
@@ -115,8 +117,12 @@ repository::
     $ git tag -a -s v1.21.0 -m"NumPy 1.21.0 release"
     $ git push upstream v1.21.0
 
+2. Build wheels
+---------------
+
 Build wheels via cibuildwheel (preferred)
------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Tagging the build at the beginning of this process will trigger a wheel build
 via cibuildwheel and upload wheels and an sdist to the staging area. The CI run
 on github actions (for all x86-based and macOS arm64 wheels) takes about 1 1/4
@@ -133,10 +139,10 @@ If you wish to manually trigger a wheel build, you can do so:
 .. _travis : https://app.travis-ci.com/github/numpy/numpy
 
 Build wheels with multibuild (outdated)
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Build source releases
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
 
 Paver is used to build the source releases. It will create the ``release`` and
 ``release/installers`` directories and put the ``*.zip`` and ``*.tar.gz``
@@ -146,7 +152,7 @@ source releases in the latter. ::
 
 
 Build wheels via MacPython/numpy-wheels
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Trigger the wheels build by pointing the numpy-wheels repository at this
 commit. This can take up to an hour. The numpy-wheels repository is cloned from
@@ -182,8 +188,8 @@ Note that sometimes builds, like tests, fail for unrelated reasons and you will
 need to rerun them. You will need to be logged in under 'numpy' to do this
 on azure.
 
-Download wheels
----------------
+3. Download wheels
+------------------
 
 When the wheels have all been successfully built and staged, download them from the
 Anaconda staging directory using the ``tools/download-wheels.py`` script::
@@ -192,8 +198,8 @@ Anaconda staging directory using the ``tools/download-wheels.py`` script::
     $ python3 tools/download-wheels.py 1.21.0
 
 
-Generate the README files
--------------------------
+4. Generate the README files
+----------------------------
 
 This needs to be done after all installers are downloaded, but before the pavement
 file is updated for continued development::
@@ -201,8 +207,8 @@ file is updated for continued development::
     $ paver write_release
 
 
-Reset the maintenance branch into a development state (skip for prereleases)
-----------------------------------------------------------------------------
+5. Reset the maintenance branch into a development state (skip for prereleases)
+-------------------------------------------------------------------------------
 
 Create release notes for next release and edit them to set the version. These
 notes will be a skeleton and have little content::
@@ -212,7 +218,7 @@ notes will be a skeleton and have little content::
     $ git add doc/source/release/1.21.1-notes.rst
 
 Add new release notes to the documentation release list and update the
-``RELEASE_NOTES`` variable in ``pavement.py``.
+``RELEASE_NOTES`` variable in ``pavement.py``::
 
     $ gvim doc/source/release.rst pavement.py
 
@@ -222,8 +228,8 @@ Commit the result::
     $ git push upstream HEAD
 
 
-Upload to PyPI
---------------
+6. Upload to PyPI
+-----------------
 
 Upload to PyPI using ``twine``. A recent version of ``twine`` of is needed
 after recent PyPI changes, version ``3.4.1`` was used here::
@@ -241,8 +247,8 @@ wheel. PyPI only allows a single source distribution, here we have
 chosen the zip archive.
 
 
-Upload files to github
-----------------------
+7. Upload files to github
+-------------------------
 
 Go to `<https://github.com/numpy/numpy/releases>`_, there should be a ``v1.21.0
 tag``, click on it and hit the edit button for that tag. There are two ways to
@@ -261,8 +267,8 @@ may take several tries to get it look right. Then
 - Hit the ``{Publish,Update} release`` button at the bottom.
 
 
-Upload documents to numpy.org (skip for prereleases)
-----------------------------------------------------
+8. Upload documents to numpy.org (skip for prereleases)
+-------------------------------------------------------
 
 .. note:: You will need a GitHub personal access token to push the update.
 
@@ -313,8 +319,8 @@ Once everything seems satisfactory, update, commit and upload the changes::
     $ popd
 
 
-Announce the release on numpy.org (skip for prereleases)
---------------------------------------------------------
+9. Announce the release on numpy.org (skip for prereleases)
+-----------------------------------------------------------
 
 This assumes that you have forked `<https://github.com/numpy/numpy.org>`_::
 
@@ -336,8 +342,8 @@ commit and push::
 
 Go to your Github fork and make a pull request.
 
-Announce to mailing lists
--------------------------
+10. Announce to mailing lists
+-----------------------------
 
 The release should be announced on the numpy-discussion, scipy-devel,
 scipy-user, and python-announce-list mailing lists. Look at previous
@@ -346,8 +352,8 @@ as generated for the release notes above. If you crosspost, make sure that
 python-announce-list is BCC so that replies will not be sent to that list.
 
 
-Post-Release Tasks (skip for prereleases)
------------------------------------------
+11. Post-release tasks (skip for prereleases)
+---------------------------------------------
 
 Checkout main and forward port the documentation changes::
 
@@ -363,8 +369,8 @@ Checkout main and forward port the documentation changes::
 
 Go to GitHub and make a PR.
 
-Update oldest-supported-numpy
------------------------------
+12. Update oldest-supported-numpy
+---------------------------------
 
 If this release is the first one to support a new Python version, or the first
 to provide wheels for a new platform or PyPy version, the version pinnings
diff --git a/doc/source/dev/releasing.rst b/doc/source/dev/releasing.rst
index 1af26f455..f56065088 100644
--- a/doc/source/dev/releasing.rst
+++ b/doc/source/dev/releasing.rst
@@ -2,15 +2,27 @@
 Releasing a version
 ===================
 
+The following guides include detailed information on how to prepare a NumPy
+release. 
+
+.. _prepare_release:
+
 ------------------------
-How to Prepare a Release
+How to prepare a release
 ------------------------
 
 .. include:: ../../HOWTO_RELEASE.rst
 
 -----------------------
-Step-by-Step Directions
+Step-by-step directions
 -----------------------
 
 .. include:: ../../RELEASE_WALKTHROUGH.rst
 
+.. _branching:
+
+------------------
+Branch walkthrough
+------------------
+
+.. include:: ../../BRANCH_WALKTHROUGH.rst
\ No newline at end of file