code review iteration

* Give the OS-specific site-packages directories for NumPy's OpenBLAS.
* Include the `pip install numpy --only-binary numpy` variation, but not `:numpy:` since pip install doesn't document that. `pip install --only-binary numpy numpy` also works but that's confusing to parse.
* Drop the sentence on the Accelerate bug on macOS < 11.3 since this isn't the place for it.
  * Also drop the search-order part about Accelerate? This applies to Numpy 1.19 as well as 1.21+.
* Clarify the part about finding external BLAS/LAPACK libs.

Some doc should explain what people need to know about installation. If they need portable, reproducible results, they should probably use the same BLAS/LAPACK libs compiled with the same compiler everywhere.

It's unfortunate to install NumPy + SciPy linked to Accelerate, along with more pips, only to discover that NumPy won't load on their Mac and have to start over. Or will SciPy reject the older LAPACK API and have problems using different BLAS/LAPACK libs?

Installing pips in Docker takes over an hour (vs. 15 minutes) if linking NumPy and SciPy to an external BLAS/LAPACK (and another pip conditionally compiles from source if NumPy did).

Worse to have to debug CI failures because their CI on Linux computes different output than Accelerate.

Should this also explain how to tell which release of OpenBLAS is included in a NumPy installation? (What got us into installing NumPy from source was needing an OpenBLAS bug fix release.)

Author: 1fish2

numpy/distutils/misc_util.py

@@ -2364,26 +2364,27 @@ def show():
 
                 NumPy BLAS/LAPACK Installation Notes
                 ------------------------------------
-                Installing a numpy wheel (e.g. ``pip install numpy``) includes
+                Installing a numpy wheel (``pip install numpy`` or force it
+                via ``pip install numpy --only-binary numpy``) includes
                 an OpenBLAS implementation of the BLAS and LAPACK linear algebra
-                APIs. In this case, ``library_dirs`` reports the build time
-                configuration; the OpenBLAS library is actually in
-                ``site-packages/numpy.libs/`` or
-                ``site-packages/numpy/.dylibs/`` and it's compiled with
-                gcc/gfortran.
-
-                Installing numpy from source (e.g.
-                ``pip install numpy --no-binary numpy``) looks for BLAS and
-                LAPACK dynamic link libraries at build time. This search is
-                influenced by the environment variables
-                NPY_BLAS_ORDER/NPY_LAPACK_ORDER, if set, and the file
-                ``~/.numpy-site.cfg``, if present.
+                APIs. In this case, ``library_dirs`` reports the original build
+                time configuration as compiled with gcc/gfortran; at run time
+                the OpenBLAS library is in
+                ``site-packages/numpy.libs/`` (linux), or
+                ``site-packages/numpy/.dylibs/`` (macOS), or
+                ``site-packages/numpy/.libs/`` (windows).
+
+                Installing numpy from source
+                (``pip install numpy --no-binary numpy``) searches for BLAS and
+                LAPACK dynamic link libraries at build time as influenced by
+                environment variables NPY_BLAS_LIBS, NPY_CBLAS_LIBS, and
+                NPY_LAPACK_LIBS; or NPY_BLAS_ORDER and NPY_LAPACK_ORDER;
+                or the optional file ``~/.numpy-site.cfg``.
+                NumPy remembers those locations and expects to load the same
+                libraries at run-time.
                 On macOS, 'accelerate' (Apple's Accelerate BLAS library) is in
-                the default search order (but not in numpy 1.20) after
-                'openblas'.
-                Loading a numpy library that's linked to Accelerate on
-                macOS < 11.3 will detect an Accelerate bug and raise a
-                RuntimeError.
+                the default build-time search order -- except in numpy 1.20 --
+                after 'openblas'.
 
                 Examples
                 --------