DOC, MAINT: Update master after 1.17.0 release.

- Update .mailmap
- Update 1.17.0-notes.rst
- Update 1.17.0-changelog.rst

[ci skip]

3 files changed, 194 insertions, 134 deletions

diff --git a/.mailmap b/.mailmap
index c30a2fc0a..d36594212 100644
--- a/.mailmap
+++ b/.mailmap
@@ -30,6 +30,7 @@ Alyssa Quek <alyssaquek@gmail.com> alyssaq <alyssaquek@gmail.com>
 Amir Sarabadani <ladsgroup@gmail.com> amir <ladsgroup@gmail.com>
 Anatoly Techtonik <techtonik@gmail.com> anatoly techtonik <techtonik@gmail.com>
 Andras Deak <deak.andris@gmail.com> adeak <adeak@users.noreply.github.com>
+Andrea Pattori <andrea.pattori@gmail.com> patto90 <andrea.pattori@gmail.com>
 Andrei Kucharavy <ank@andreikucharavy.com> chiffa <ank@andreikucharavy.com>
 Anne Archibald <peridot.faceted@gmail.com> aarchiba <peridot.faceted@gmail.com>
 Anne Archibald <peridot.faceted@gmail.com> Anne Archibald <archibald@astron.nl>
@@ -122,6 +123,7 @@ Jeffrey Yancey <jeffrey@octane5.com> Jeff <3820914+jeffyancey@users.noreply.gith
 Jeremy Lay <jlay80@gmail.com> jeremycl01 <jlay80@gmail.com>
 Jérémie du Boisberranger <jeremie.du-boisberranger@inria.fr> jeremiedbb <34657725+jeremiedbb@users.noreply.github.com>
 Jerome Kelleher <jerome.kelleher@ed.ac.uk> jeromekelleher <jerome.kelleher@ed.ac.uk>
+Johannes Hampp <johannes.hampp@zeu.uni-giessen.de> euronion <42553970+euronion@users.noreply.github.com>
 Johannes Schönberger <hannesschoenberger@gmail.com> Johannes Schönberger <jschoenberger@demuc.de>
 John Darbyshire <24256554+attack68@users.noreply.github.com> attack68 <24256554+attack68@users.noreply.github.com>
 Joseph Fox-Rabinovitz <jfoxrabinovitz@gmail.com> Joseph Fox-Rabinovitz <joseph.r.fox-rabinovitz@nasa.gov>
@@ -133,10 +135,11 @@ Julian Taylor <juliantaylor108@gmail.com> Julian Taylor <juliantaylor108@googlem
 Julien Lhermitte <jrmlhermitte@gmail.com> Julien Lhermitte <lhermitte@bnl.gov>
 Julien Schueller <julien.schueller@gmail.com> jschueller <julien.schueller@gmail.com>
 Kai Striega <kaistriega@gmail.com> kai <kaistriega@gmail.com>
+Kai Striega <kaistriega@gmail.com> kai-striega <kaistriega@gmail.com>
 Kai Striega <kaistriega@gmail.com> kai-striega <kaistriega+github@gmail.com>
 Khaled Ben Abdallah Okuda <khaled.ben.okuda@gmail.com> KhaledTo <khaled.ben.okuda@gmail.com>
-Kiko Correoso <kikocorreoso@gmail.com> kikocorreoso <kikocorreoso@gmail.com>
-Kiko Correoso <kikocorreoso@gmail.com> <kikocorreoso@users.noreply.github.com>
+Kiko Correoso <kachine@protonmail.com> kikocorreoso <kikocorreoso@gmail.com>
+Kiko Correoso <kachine@protonmail.com> kikocorreoso <kikocorreoso@users.noreply.github.com>
 Konrad Kapp <k_kapp@yahoo.com> k_kapp@yahoo.com <k_kapp@yahoo.com>
 Kriti Singh <kritisingh1.ks@gmail.com> kritisingh1 <kritisingh1.ks@gmail.com>
 Lars Buitinck <larsmans@gmail.com> Lars Buitinck <l.buitinck@esciencecenter.nl>
diff --git a/doc/changelog/1.17.0-changelog.rst b/doc/changelog/1.17.0-changelog.rst
index 7b55f395a..debfb6f5b 100644
--- a/doc/changelog/1.17.0-changelog.rst
+++ b/doc/changelog/1.17.0-changelog.rst
@@ -2,7 +2,7 @@
 Contributors
 ============
 
-A total of 142 people contributed to this release.  People with a "+" by their
+A total of 150 people contributed to this release.  People with a "+" by their
 names contributed a patch for the first time.
 
 * Aaron Voelker +
@@ -18,6 +18,7 @@ names contributed a patch for the first time.
 * Allan Haldane
 * Ander Ustarroz +
 * Andras Deak
+* Andrea Pattori +
 * Andreas Schwab
 * Andrew Naguib +
 * Andy Scholand +
@@ -37,6 +38,8 @@ names contributed a patch for the first time.
 * Christoph Gohlke
 * Christopher Whelan +
 * Chuanzhu Xu +
+* Colin Snyder +
+* Dan Allan +
 * Daniel Hrisca
 * Daniel Lawrence +
 * Debsankha Manik +
@@ -50,14 +53,17 @@ names contributed a patch for the first time.
 * Gary Gurlaskie +
 * Gregory Lee +
 * Gregory R. Lee
+* Guillaume Horel +
 * Hameer Abbasi
 * Haoyu Sun +
+* Harmon +
 * He Jia +
 * Hunter Damron +
 * Ian Sanders +
 * Ilja +
 * Isaac Virshup +
 * Isaiah Norton +
+* Jackie Leng +
 * Jaime Fernandez
 * Jakub Wilk
 * Jan S. (Milania1) +
@@ -67,6 +73,7 @@ names contributed a patch for the first time.
 * Jim Turner +
 * Jingbei Li +
 * Joachim Hereth +
+* Johannes Hampp +
 * John Belmonte +
 * John Kirkham
 * John Law +
@@ -84,6 +91,7 @@ names contributed a patch for the first time.
 * Kiko Correoso +
 * Kriti Singh +
 * Lars Grueter +
+* Luis Pedro Coelho
 * Maksim Shabunin +
 * Manvi07 +
 * Mark Harfouche
@@ -125,6 +133,7 @@ names contributed a patch for the first time.
 * Shekhar Prasad Rajak +
 * Stefan van der Walt
 * Stephan Hoyer
+* Steve Stagg +
 * SuryaChand P +
 * Søren Rasmussen +
 * Thibault Hallouin +
@@ -143,7 +152,6 @@ names contributed a patch for the first time.
 * Yu Kobayashi +
 * Yury Kirienko +
 * aashuli +
-* euronion +
 * luzpaz
 * parul +
 * spacescientist +
@@ -151,7 +159,7 @@ names contributed a patch for the first time.
 Pull requests merged
 ====================
 
-A total of 505 pull requests were merged for this release.
+A total of 531 pull requests were merged for this release.
 
 * `#4808 <https://github.com/numpy/numpy/pull/4808>`__: ENH: Make the `mode` parameter of np.pad default to 'constant'
 * `#8131 <https://github.com/numpy/numpy/pull/8131>`__: BUG: Fix help() formatting for deprecated functions.
@@ -598,7 +606,7 @@ A total of 505 pull requests were merged for this release.
 * `#13720 <https://github.com/numpy/numpy/pull/13720>`__: MAINT/BUG: Manage more files with with statements
 * `#13721 <https://github.com/numpy/numpy/pull/13721>`__: MAINT,BUG: More ufunc exception cleanup
 * `#13724 <https://github.com/numpy/numpy/pull/13724>`__: MAINT: fix use of cache_dim
-* `#13725 <https://github.com/numpy/numpy/pull/13725>`__: BUG: fix compilation of 3rdparty modules with Py_LIMITED_API...
+* `#13725 <https://github.com/numpy/numpy/pull/13725>`__: BUG: fix compilation of 3rd party modules with Py_LIMITED_API...
 * `#13726 <https://github.com/numpy/numpy/pull/13726>`__: MAINT: Update PCG jump sizes
 * `#13729 <https://github.com/numpy/numpy/pull/13729>`__: DOC: Merge together DISTUTILS.rst.txt#template-files" and distutils.r…
 * `#13730 <https://github.com/numpy/numpy/pull/13730>`__: MAINT: Change keyword from reserved word
@@ -658,3 +666,29 @@ A total of 505 pull requests were merged for this release.
 * `#13869 <https://github.com/numpy/numpy/pull/13869>`__: DOC: Prepare for 1.17.0rc1 release
 * `#13870 <https://github.com/numpy/numpy/pull/13870>`__: MAINT,BUG: Use nbytes to also catch empty descr during allocation
 * `#13873 <https://github.com/numpy/numpy/pull/13873>`__: ENH: Rename default_gen -> default_rng
+* `#13893 <https://github.com/numpy/numpy/pull/13893>`__: DOC: fix links in 1.17 release note
+* `#13897 <https://github.com/numpy/numpy/pull/13897>`__: DOC: Use Cython >= 0.29.11 for Python 3.8 support.
+* `#13932 <https://github.com/numpy/numpy/pull/13932>`__: MAINT,BUG,DOC: Fix errors in _add_newdocs
+* `#13963 <https://github.com/numpy/numpy/pull/13963>`__: ENH, BUILD: refactor all OpenBLAS downloads into a single, testable...
+* `#13971 <https://github.com/numpy/numpy/pull/13971>`__: DOC: emphasize random API changes
+* `#13972 <https://github.com/numpy/numpy/pull/13972>`__: MAINT: Rewrite Floyd algorithm
+* `#13992 <https://github.com/numpy/numpy/pull/13992>`__: BUG: Do not crash on recursive `.dtype` attribute lookup.
+* `#13993 <https://github.com/numpy/numpy/pull/13993>`__: DEP: Speed up WarnOnWrite deprecation in buffer interface
+* `#13995 <https://github.com/numpy/numpy/pull/13995>`__: BLD: Remove Trusty dist in Travis CI build
+* `#13996 <https://github.com/numpy/numpy/pull/13996>`__: BUG: Handle weird bytestrings in dtype()
+* `#13997 <https://github.com/numpy/numpy/pull/13997>`__: BUG: i0 Bessel function regression on array-likes supporting...
+* `#13998 <https://github.com/numpy/numpy/pull/13998>`__: BUG: Missing warnings import in polyutils.
+* `#13999 <https://github.com/numpy/numpy/pull/13999>`__: DOC: Document array_function at a higher level.
+* `#14001 <https://github.com/numpy/numpy/pull/14001>`__: DOC: Show workaround for Generator.integers backward compatibility
+* `#14021 <https://github.com/numpy/numpy/pull/14021>`__: DOC: Prepare 1.17.0rc2 release.
+* `#14040 <https://github.com/numpy/numpy/pull/14040>`__: DOC: Improve quickstart documentation of new random Generator.
+* `#14041 <https://github.com/numpy/numpy/pull/14041>`__: TST, MAINT: expand OpenBLAS version checking
+* `#14080 <https://github.com/numpy/numpy/pull/14080>`__: BUG, DOC: add new recfunctions to `__all__`
+* `#14081 <https://github.com/numpy/numpy/pull/14081>`__: BUG: fix build issue on icc 2016
+* `#14082 <https://github.com/numpy/numpy/pull/14082>`__: BUG: Fix file-like object check when saving arrays
+* `#14109 <https://github.com/numpy/numpy/pull/14109>`__: REV: "ENH: Improved performance of PyArray_FromAny for sequences...
+* `#14126 <https://github.com/numpy/numpy/pull/14126>`__: BUG, TEST: Adding validation test suite to validate float32 exp
+* `#14127 <https://github.com/numpy/numpy/pull/14127>`__: DOC: Add blank line above doctest for intersect1d
+* `#14128 <https://github.com/numpy/numpy/pull/14128>`__: MAINT: adjustments to test_ufunc_noncontigous
+* `#14129 <https://github.com/numpy/numpy/pull/14129>`__: MAINT: Use equality instead of identity check with literal
+* `#14133 <https://github.com/numpy/numpy/pull/14133>`__: MAINT: Update mailmap and changelog for 1.17.0
diff --git a/doc/release/1.17.0-notes.rst b/doc/release/1.17.0-notes.rst
index 303f02464..8d69e36d9 100644
--- a/doc/release/1.17.0-notes.rst
+++ b/doc/release/1.17.0-notes.rst
@@ -1,3 +1,5 @@
+.. currentmodule:: numpy
+
 ==========================
 NumPy 1.17.0 Release Notes
 ==========================
@@ -5,10 +7,10 @@ NumPy 1.17.0 Release Notes
 This NumPy release contains a number of new features that should substantially
 improve its performance and usefulness, see Highlights below for a summary. The
 Python versions supported are 3.5-3.7, note that Python 2.7 has been dropped.
-Python 3.8b1 should work with the released source packages, but there are no
+Python 3.8b2 should work with the released source packages, but there are no
 future guarantees.
 
-Downstream developers should use Cython >= 0.29.10 for Python 3.8 support and
+Downstream developers should use Cython >= 0.29.11 for Python 3.8 support and
 OpenBLAS >= 3.7 (not currently out) to avoid problems on the Skylake
 architecture. The NumPy wheels on PyPI are built from the OpenBLAS development
 branch in order to avoid those problems.
@@ -17,17 +19,19 @@ branch in order to avoid those problems.
 Highlights
 ==========
 
-* A new extensible random module along with four selectable random number
-  generators and improved seeding designed for use in parallel processes has
-  been added. The currently available bit generators are MT19937, PCG64,
-  Philox, and SFC64. See below under New Features.
+* A new extensible `random` module along with four selectable `random number
+  generators <random.BitGenerators>` and improved seeding designed for use in parallel
+  processes has been added. The currently available bit generators are `MT19937
+  <random.mt19937.MT19937>`, `PCG64 <random.pcg64.PCG64>`, `Philox
+  <random.philox.Philox>`, and `SFC64 <random.sfc64.SFC64>`. See below under
+  New Features.
 
-* NumPy's FFT implementation was changed from fftpack to pocketfft, resulting
-  in faster, more accurate transforms and better handling of datasets of
-  prime length. See below under Improvements.
+* NumPy's `FFT <fft>` implementation was changed from fftpack to pocketfft,
+  resulting in faster, more accurate transforms and better handling of datasets
+  of prime length. See below under Improvements.
 
 * New radix sort and timsort sorting methods. It is currently not possible to
-  choose which will be used, but they are hardwired to the datatype and used
+  choose which will be used. They are hardwired to the datatype and used
   when either ``stable`` or ``mergesort`` is passed as the method. See below
   under Improvements.
 
@@ -44,8 +48,8 @@ New functions
 Deprecations
 ============
 
-``np.polynomial`` functions warn when passed ``float`` in place of ``int``
---------------------------------------------------------------------------
+`numpy.polynomial` functions warn when passed ``float`` in place of ``int``
+---------------------------------------------------------------------------
 Previously functions in this module would accept ``float`` values provided they
 were integral (``1.0``, ``2.0``, etc). For consistency with the rest of numpy,
 doing so is now deprecated, and in future will raise a ``TypeError``.
@@ -53,11 +57,11 @@ doing so is now deprecated, and in future will raise a ``TypeError``.
 Similarly, passing a float like ``0.5`` in place of an integer will now raise a
 ``TypeError`` instead of the previous ``ValueError``.
 
-Deprecate ``numpy.distutils.exec_command`` and ``numpy.distutils.temp_file_name``
----------------------------------------------------------------------------------
+Deprecate `numpy.distutils.exec_command` and ``temp_file_name``
+---------------------------------------------------------------
 The internal use of these functions has been refactored and there are better
-alternatives. Relace ``exec_command`` with `subprocess.Popen` and
-``temp_file_name`` with `tempfile.mkstemp`.
+alternatives. Replace ``exec_command`` with `subprocess.Popen` and
+`temp_file_name <numpy.distutils.exec_command>` with `tempfile.mkstemp`.
 
 Writeable flag of C-API wrapped arrays
 --------------------------------------
@@ -71,10 +75,11 @@ a manner are very rare in practice and only available through the NumPy C-API.
 
 `numpy.nonzero` should no longer be called on 0d arrays
 -------------------------------------------------------
-The behavior of nonzero on 0d arrays was surprising, making uses of it almost
-always incorrect. If the old behavior was intended, it can be preserved without
-a warning by using ``nonzero(atleast_1d(arr))`` instead of ``nonzero(arr)``.
-In a future release, it is most likely this will raise a `ValueError`.
+The behavior of `numpy.nonzero` on 0d arrays was surprising, making uses of it
+almost always incorrect. If the old behavior was intended, it can be preserved
+without a warning by using ``nonzero(atleast_1d(arr))`` instead of
+``nonzero(arr)``.  In a future release, it is most likely this will raise a
+``ValueError``.
 
 Writing to the result of `numpy.broadcast_arrays` will warn
 -----------------------------------------------------------
@@ -91,6 +96,12 @@ produce the deprecation warning. To help alleviate confusion, an additional
 `FutureWarning` will be emitted when accessing the ``writeable`` flag state to
 clarify the contradiction.
 
+Note that for the C-side buffer protocol such an array will return a
+readonly buffer immediately unless a writable buffer is requested. If
+a writeable buffer is requested a warning will be given. When using
+cython, the ``const`` qualifier should be used with such arrays to avoid
+the warning (e.g. ``cdef const double[::1] view``).
+
 
 Future Changes
 ==============
@@ -110,15 +121,15 @@ dtype, (1,))]`` or ``"(1,)type"`` (consistently with ``[(name, dtype, n)]``
 Compatibility notes
 ===================
 
-float16 subnormal rounding
---------------------------
-Casting from a different floating point precision to float16 used incorrect
+``float16`` subnormal rounding
+------------------------------
+Casting from a different floating point precision to ``float16`` used incorrect
 rounding in some edge cases. This means in rare cases, subnormal results will
 now be rounded up instead of down, changing the last bit (ULP) of the result.
 
 Signed zero when using divmod
 -----------------------------
-Starting in version 1.12.0, numpy incorrectly returned a negatively signed zero
+Starting in version `1.12.0`, numpy incorrectly returned a negatively signed zero
 when using the ``divmod`` and ``floor_divide`` functions when the result was
 zero. For example::
 
@@ -134,8 +145,9 @@ zero::
 ``MaskedArray.mask`` now returns a view of the mask, not the mask itself
 ------------------------------------------------------------------------
 Returning the mask itself was unsafe, as it could be reshaped in place which
-would violate expectations of the masked array code. It's behavior is now
-consistent with the ``.data`` attribute, which also returns a view.
+would violate expectations of the masked array code. The behavior of `mask
+<ma.MaskedArray.mask>` is now consistent with `data <ma.MaskedArray.data>`,
+which also returns a view.
 
 The underlying mask can still be accessed with ``._mask`` if it is needed.
 Tests that contain ``assert x.mask is not y.mask`` or similar will need to be
@@ -147,30 +159,36 @@ Looking up ``__buffer__`` attribute in `numpy.frombuffer` was undocumented and
 non-functional. This code was removed. If needed, use
 ``frombuffer(memoryview(obj), ...)`` instead.
 
-``out``is buffered for memory overlaps in ``np.take``, ``np.choose``, ``np.put``
---------------------------------------------------------------------------------
+``out`` is buffered for memory overlaps in `take`, `choose`, `put`
+------------------------------------------------------------------
 If the out argument to these functions is provided and has memory overlap with
 the other arguments, it is now buffered to avoid order-dependent behavior.
 
 Unpickling while loading requires explicit opt-in
 -------------------------------------------------
-The functions ``np.load``, and ``np.lib.format.read_array`` take an
+The functions `load`, and ``lib.format.read_array`` take an
 ``allow_pickle`` keyword which now defaults to ``False`` in response to
 `CVE-2019-6446 <https://nvd.nist.gov/vuln/detail/CVE-2019-6446>`_.
 
+
+.. currentmodule:: numpy.random.mtrand
+
 Potential changes to the random stream in old random module
 -----------------------------------------------------------
-Due to bugs in the application of log to random floating point numbers,
-the stream may change when sampling from ``np.random.beta``, ``np.random.binomial``,
-``np.random.laplace``, ``np.random.logistic``, ``np.random.logseries`` or
-``np.random.multinomial`` if a 0 is generated in the underlying MT19937 random stream.
-There is a 1 in :math:`10^{53}` chance of this occurring, and so the probability that
-the stream changes for any given seed is extremely small. If a 0 is encountered in the
-underlying generator, then the incorrect value produced (either ``np.inf``
-or ``np.nan``) is now dropped.
-
-``i0`` now always returns a result with the same shape as the input
--------------------------------------------------------------------
+Due to bugs in the application of ``log`` to random floating point numbers,
+the stream may change when sampling from `~RandomState.beta`, `~RandomState.binomial`,
+`~RandomState.laplace`, `~RandomState.logistic`, `~RandomState.logseries` or
+`~RandomState.multinomial` if a ``0`` is generated in the underlying `MT19937
+<~numpy.random.mt11937.MT19937>` random stream.  There is a ``1`` in
+:math:`10^{53}` chance of this occurring, so the probability that the stream
+changes for any given seed is extremely small. If a ``0`` is encountered in the
+underlying generator, then the incorrect value produced (either `numpy.inf` or
+`numpy.nan`) is now dropped.
+
+.. currentmodule:: numpy
+
+`i0` now always returns a result with the same shape as the input
+-----------------------------------------------------------------
 Previously, the output was squeezed, such that, e.g., input with just a single
 element would lead to an array scalar being returned, and inputs with shapes
 such as ``(10, 1)`` would yield results that would not broadcast against the
@@ -179,19 +197,20 @@ input.
 Note that we generally recommend the SciPy implementation over the numpy one:
 it is a proper ufunc written in C, and more than an order of magnitude faster.
 
-``np.can_cast`` no longer assumes all unsafe casting is allowed
----------------------------------------------------------------
-Previously, ``can_cast`` returned `True` for almost all inputs for
+`can_cast` no longer assumes all unsafe casting is allowed
+----------------------------------------------------------
+Previously, `can_cast` returned `True` for almost all inputs for
 ``casting='unsafe'``, even for cases where casting was not possible, such as
 from a structured dtype to a regular one.  This has been fixed, making it
-more consistent with actual casting using, e.g., the ``.astype`` method.
+more consistent with actual casting using, e.g., the `.astype <ndarray.astype>`
+method.
 
-``arr.writeable`` can be switched to true slightly more often
--------------------------------------------------------------
+``ndarray.flags.writeable`` can be switched to true slightly more often
+-----------------------------------------------------------------------
 
 In rare cases, it was not possible to switch an array from not writeable
 to writeable, although a base array is writeable. This can happen if an
-intermediate ``arr.base`` object is writeable. Previously, only the deepest
+intermediate `ndarray.base` object is writeable. Previously, only the deepest
 base object was considered for this decision. However, in rare cases this
 object does not have the necessary information. In that case switching to
 writeable was never allowed. This has now been fixed.
@@ -214,16 +233,21 @@ This change is backwards compatible, but now allows code like::
 New Features
 ============
 
-New extensible random module with selectable random number generators
----------------------------------------------------------------------
-A new extensible random module along with four selectable random number
+.. currentmodule:: numpy.random
+
+New extensible `numpy.random` module with selectable random number generators
+-----------------------------------------------------------------------------
+A new extensible `numpy.random` module along with four selectable random number
 generators and improved seeding designed for use in parallel processes has been
-added. The currently available bit generators are MT19937, PCG64, Philox, and
-SFC64. PCG64 is the new default while MT19937 is retained for backwards
+added. The currently available :ref:`Bit Generators <bit_generator>` are
+`~mt19937.MT19937`, `~pcg64.PCG64`, `~philox.Philox`, and `~sfc64.SFC64`.
+``PCG64`` is the new default while ``MT19937`` is retained for backwards
 compatibility. Note that the legacy random module is unchanged and is now
-frozen, your current results will not change. Extensive documentation for the
-new module is available online at
-`NumPy devdocs <http://www.numpy.org/devdocs/reference/random/index.html>`_.
+frozen, your current results will not change. More information is available in
+the :ref:`API change description <new-or-different>` and in the `top-level view
+<numpy.random>` documentation.
+
+.. currentmodule:: numpy
 
 libFLAME
 --------
@@ -233,7 +257,7 @@ implementation, see
 
 User-defined BLAS detection order
 ---------------------------------
-``numpy.distutils`` now uses an environment variable, comma-separated and case
+`distutils` now uses an environment variable, comma-separated and case
 insensitive, to determine the detection order for BLAS libraries.
 By default ``NPY_BLAS_ORDER=mkl,blis,openblas,atlas,accelerate,blas``.
 However, to force the use of OpenBLAS simply do::
@@ -248,7 +272,7 @@ User-defined LAPACK detection order
 -----------------------------------
 ``numpy.distutils`` now uses an environment variable, comma-separated and case
 insensitive, to determine the detection order for LAPACK libraries.
-By default ``NPY_BLAS_ORDER=mkl,openblas,flame,atlas,accelerate,lapack``.
+By default ``NPY_LAPACK_ORDER=mkl,openblas,flame,atlas,accelerate,lapack``.
 However, to force the use of OpenBLAS simply do::
 
    NPY_LAPACK_ORDER=openblas python setup.py build
@@ -257,14 +281,14 @@ which forces the use of OpenBLAS.
 This may be helpful for users which have a MKL installation but wishes to try
 out different implementations.
 
-``np.ufunc.reduce`` and related functions now accept a ``where`` mask
----------------------------------------------------------------------
-``np.ufunc.reduce``, ``np.sum``, ``np.prod``, ``np.min``, ``np.max`` all
+`ufunc.reduce` and related functions now accept a ``where`` mask
+----------------------------------------------------------------
+`ufunc.reduce`, `sum`, `prod`, `min`, `max` all
 now accept a ``where`` keyword argument, which can be used to tell which
 elements to include in the reduction.  For reductions that do not have an
 identity, it is necessary to also pass in an initial value (e.g.,
-``initial=np.inf`` for ``np.min``).  For instance, the equivalent of
-``nansum`` would be, ``np.sum(a, where=~np.isnan(a))``.
+``initial=np.inf`` for `min`).  For instance, the equivalent of
+`nansum` would be ``np.sum(a, where=~np.isnan(a))``.
 
 Timsort and radix sort have replaced mergesort for stable sorting
 -----------------------------------------------------------------
@@ -275,44 +299,50 @@ each other with the actual sort implementation depending on the array type.
 Radix sort is used for small integer types of 16 bits or less and timsort for
 the remaining types.  Timsort features improved performace on data containing
 already or nearly sorted data and performs like mergesort on random data and
-requires O(n/2) working space.  Details of the timsort algorithm can be found
-at
-`CPython listsort.txt <https://github.com/python/cpython/blob/3.7/Objects/listsort.txt>`_.
+requires :math:`O(n/2)` working space.  Details of the timsort algorithm can be
+found at `CPython listsort.txt
+<https://github.com/python/cpython/blob/3.7/Objects/listsort.txt>`_.
+
+`packbits` and `unpackbits` accept an ``order`` keyword
+-------------------------------------------------------
+The ``order`` keyword defaults to ``big``, and will order the **bits**
+accordingly. For ``'order=big'`` 3 will become ``[0, 0, 0, 0, 0, 0, 1, 1]``,
+and ``[1, 1, 0, 0, 0, 0, 0, 0]`` for ``order=little``
 
-``np.unpackbits`` now accepts a ``count`` parameter
----------------------------------------------------
+`unpackbits` now accepts a ``count`` parameter
+----------------------------------------------
 ``count`` allows subsetting the number of bits that will be unpacked up-front,
-rather than reshaping and subsetting later, making the ``packbits`` operation
+rather than reshaping and subsetting later, making the `packbits` operation
 invertible, and the unpacking less wasteful. Counts larger than the number of
 available bits add zero padding. Negative counts trim bits off the end instead
 of counting from the beginning. None counts implement the existing behavior of
 unpacking everything.
 
-``np.linalg.svd`` and ``np.linalg.pinv`` can be faster on hermitian inputs
---------------------------------------------------------------------------
+`linalg.svd` and `linalg.pinv` can be faster on hermitian inputs
+----------------------------------------------------------------
 These functions now accept a ``hermitian`` argument, matching the one added
-to ``np.linalg.matrix_rank`` in 1.14.0.
+to `linalg.matrix_rank` in 1.14.0.
 
 divmod operation is now supported for two ``timedelta64`` operands
 ------------------------------------------------------------------
-The divmod operator now handles two ``np.timedelta64`` operands, with
-type signature mm->qm.
+The divmod operator now handles two ``timedelta64`` operands, with
+type signature ``mm->qm``.
 
-``np.fromfile`` now takes an ``offset`` argument
-------------------------------------------------
+`fromfile` now takes an ``offset`` argument
+-------------------------------------------
 This function now takes an ``offset`` keyword argument for binary files,
 which specifics the offset (in bytes) from the file's current position.
-Defaults to 0.
+Defaults to ``0``.
 
-New mode "empty" for ``np.pad``
--------------------------------
+New mode "empty" for `pad`
+--------------------------
 This mode pads an array to a desired shape without initializing the new
 entries.
 
-``np.empty_like`` and related functions now accept a ``shape`` argument
------------------------------------------------------------------------
-``np.empty_like``, ``np.full_like``, ``np.ones_like`` and ``np.zeros_like`` now
-accept a ``shape`` keyword argument, which can be used to create a new array
+`empty_like` and related functions now accept a ``shape`` argument
+------------------------------------------------------------------
+`empty_like`, `full_like`, `ones_like` and `zeros_like` now accept a ``shape``
+keyword argument, which can be used to create a new array
 as the prototype, overriding its shape as well. This is particularly useful
 when combined with the ``__array_function__`` protocol, allowing the creation
 of new arbitrary-shape arrays from NumPy-like libraries when such an array
@@ -340,12 +370,6 @@ equivalent.
 A new format version of 3.0 has been introduced, which enables structured types
 with non-latin1 field names. This is used automatically when needed.
 
-`numpy.packbits` and `numpy.unpackbits` accept an ``order`` keyword
--------------------------------------------------------------------
-The ``order`` keyword defaults to ``big``, and will order the **bits**
-accordingly. For ``'big'`` 3 will become ``[0, 0, 0, 0, 0, 0, 1, 1]``, and
-``[1, 1, 0, 0, 0, 0, 0, 0]`` for ``little``
-
 
 Improvements
 ============
@@ -353,25 +377,25 @@ Improvements
 Array comparison assertions include maximum differences
 -------------------------------------------------------
 Error messages from array comparison tests such as
-`np.testing.assert_allclose` now include "max absolute difference" and
+`testing.assert_allclose` now include "max absolute difference" and
 "max relative difference," in addition to the previous "mismatch" percentage.
 This information makes it easier to update absolute and relative error
 tolerances.
 
-Replacement of the fftpack based FFT module by the pocketfft library
---------------------------------------------------------------------
+Replacement of the fftpack based `fft` module by the pocketfft library
+----------------------------------------------------------------------
 Both implementations have the same ancestor (Fortran77 FFTPACK by Paul N.
 Swarztrauber), but pocketfft contains additional modifications which improve
 both accuracy and performance in some circumstances. For FFT lengths containing
 large prime factors, pocketfft uses Bluestein's algorithm, which maintains
-``O(N log N)`` run time complexity instead of deteriorating towards ``O(N*N)``
-for prime lengths. Also, accuracy for real valued FFTs with near prime lengths
-has improved and is on par with complex valued FFTs.
+:math:`O(N log N)` run time complexity instead of deteriorating towards
+:math:`O(N*N)` for prime lengths. Also, accuracy for real valued FFTs with near
+prime lengths has improved and is on par with complex valued FFTs.
 
 Further improvements to ``ctypes`` support in `numpy.ctypeslib`
 ---------------------------------------------------------------
 A new `numpy.ctypeslib.as_ctypes_type` function has been added, which can be
-used to converts a ``dtype`` into a best-guess ``ctypes`` type. Thanks to this
+used to converts a `dtype` into a best-guess `ctypes` type. Thanks to this
 new function, `numpy.ctypeslib.as_ctypes` now supports a much wider range of
 array types, including structures, booleans, and integers of non-native
 endianness.
@@ -383,7 +407,7 @@ Currently, if you have a function like::
     def foo():
         pass
 
-and you want to wrap the whole thing in ``errstate``, you have to rewrite it
+and you want to wrap the whole thing in `errstate`, you have to rewrite it
 like so::
 
     def foo():
@@ -400,9 +424,9 @@ thereby saving a level of indentation
 
 `numpy.exp` and `numpy.log` speed up for float32 implementation
 ---------------------------------------------------------------
-float32 implementation of numpy.exp and numpy.log now benefit from AVX2/AVX512
-instruction set which are detected during runtime. numpy.exp has a max ulp
-error of 2.52 and numpy.log has a max ulp error or 3.83.
+float32 implementation of `exp` and `log` now benefit from AVX2/AVX512
+instruction set which are detected during runtime. `exp` has a max ulp
+error of 2.52 and `log` has a max ulp error or 3.83.
 
 Improve performance of `numpy.pad`
 ----------------------------------
@@ -412,28 +436,28 @@ concatenation.
 
 `numpy.interp` handles infinities more robustly
 -----------------------------------------------
-In some cases where ``np.interp`` would previously return ``np.nan``, it now
+In some cases where `interp` would previously return `nan`, it now
 returns an appropriate infinity.
 
-Pathlib support for ``np.fromfile``, ``ndarray.tofile`` and ``ndarray.dump``
-----------------------------------------------------------------------------
-``np.fromfile``, ``np.ndarray.tofile`` and ``np.ndarray.dump`` now support
+Pathlib support for `fromfile`, `tofile` and `ndarray.dump`
+-----------------------------------------------------------
+`fromfile`, `ndarray.ndarray.tofile` and `ndarray.dump` now support
 the `pathlib.Path` type for the ``file``/``fid`` parameter.
 
-Specialized ``np.isnan``, ``np.isinf``, and ``np.isfinite`` ufuncs for bool and int types
------------------------------------------------------------------------------------------
-The boolean and integer types are incapable of storing ``np.nan`` and
-``np.inf`` values, which allows us to provide specialized ufuncs that are up to
-250x faster than the current approach.
+Specialized `isnan`, `isinf`, and `isfinite` ufuncs for bool and int types
+--------------------------------------------------------------------------
+The boolean and integer types are incapable of storing `nan` and `inf` values,
+which allows us to provide specialized ufuncs that are up to 250x faster than
+the previous approach.
 
-``np.isfinite`` supports ``datetime64`` and ``timedelta64`` types
+`isfinite` supports ``datetime64`` and ``timedelta64`` types
 -----------------------------------------------------------------
-Previously, `np.isfinite` used to raise a ``TypeError`` on being used on these
+Previously, `isfinite` used to raise a `TypeError` on being used on these
 two types.
 
-New keywords added to ``np.nan_to_num``
----------------------------------------
-``np.nan_to_num`` now accepts keywords ``nan``, ``posinf`` and ``neginf``
+New keywords added to `nan_to_num`
+----------------------------------
+`nan_to_num` now accepts keywords ``nan``, ``posinf`` and ``neginf``
 allowing the user to define the value to replace the ``nan``, positive and
 negative ``np.inf`` values respectively.
 
@@ -449,14 +473,14 @@ These ufuncs now call the ``__floor__``, ``__ceil__``, and ``__trunc__``
 methods when called on object arrays, making them compatible with
 `decimal.Decimal` and `fractions.Fraction` objects.
 
-``quantile`` now works on ``fraction.Fraction`` and ``decimal.Decimal`` objects
--------------------------------------------------------------------------------
+`quantile` now works on `fraction.Fraction` and `decimal.Decimal` objects
+-------------------------------------------------------------------------
 In general, this handles object arrays more gracefully, and avoids floating-
 point operations if exact arithmetic types are used.
 
-Support of object arrays in ``np.matmul``
------------------------------------------
-It is now possible to use ``np.matmul`` (or the ``@`` operator) with object arrays.
+Support of object arrays in `matmul`
+------------------------------------
+It is now possible to use `matmul` (or the ``@`` operator) with object arrays.
 For instance, it is now possible to do::
 
     from fractions import Fraction
@@ -467,10 +491,10 @@ For instance, it is now possible to do::
 Changes
 =======
 
-``median`` and ``percentile`` family of functions no longer warn about ``nan``
-------------------------------------------------------------------------------
+`median` and `percentile` family of functions no longer warn about ``nan``
+--------------------------------------------------------------------------
 `numpy.median`, `numpy.percentile`, and `numpy.quantile` used to emit a
-``RuntimeWarning`` when encountering an `numpy.nan`. Since they return the
+``RuntimeWarning`` when encountering an `nan`. Since they return the
 ``nan`` value, the warning is redundant and has been removed.
 
 ``timedelta64 % 0`` behavior adjusted to return ``NaT``
@@ -487,16 +511,16 @@ are set, but is now always enabled.
 
 .. _`NEP 18` : http://www.numpy.org/neps/nep-0018-array-function-protocol.html
 
-`numpy.lib.recfunctions.structured_to_unstructured` does not squeeze single-field views
----------------------------------------------------------------------------------------
+``lib.recfunctions.structured_to_unstructured`` does not squeeze single-field views
+-----------------------------------------------------------------------------------
 Previously ``structured_to_unstructured(arr[['a']])`` would produce a squeezed
 result inconsistent with ``structured_to_unstructured(arr[['a', b']])``. This
 was accidental. The old behavior can be retained with
 ``structured_to_unstructured(arr[['a']]).squeeze(axis=-1)`` or far more simply,
 ``arr['a']``.
 
-``clip`` now uses a ufunc under the hood
-----------------------------------------
+`clip` now uses a ufunc under the hood
+--------------------------------------
 This means that registering clip functions for custom dtypes in C via
 ``descr->f->fastclip`` is deprecated - they should use the ufunc registration
 mechanism instead, attaching to the ``np.core.umath.clip`` ufunc.
@@ -524,9 +548,9 @@ Additionally, there are some corner cases with behavior changes:
 ------------------------------------------------------
 The interface may use an ``offset`` value that was mistakenly ignored.
 
-Pickle protocol in ``np.savez`` set to 3 for ``force zip64`` flag
+Pickle protocol in `savez` set to 3 for ``force zip64`` flag
 -----------------------------------------------------------------
-``np.savez`` was not using the ``force_zip64`` flag, which limited the size of
+`savez` was not using the ``force_zip64`` flag, which limited the size of
 the archive to 2GB. But using the flag requires us to use pickle protocol 3 to
 write ``object`` arrays. The protocol used was bumped to 3, meaning the archive
 will be unreadable by Python2.
@@ -536,4 +560,3 @@ Structured arrays indexed with non-existent fields raise ``KeyError`` not ``Valu
 ``arr['bad_field']`` on a structured type raises ``KeyError``, for consistency
 with ``dict['bad_field']``.
 
-.. _`NEP 18` : http://www.numpy.org/neps/nep-0018-array-function-protocol.html