Merge pull request #14573 from rgommers/remove-info-files

DOC: update submodule docstrings, remove info.py files

12 files changed, 109 insertions, 360 deletions

diff --git a/numpy/core/__init__.py b/numpy/core/__init__.py
index ce443bb22..c3b3f0392 100644
--- a/numpy/core/__init__.py
+++ b/numpy/core/__init__.py
@@ -1,6 +1,13 @@
+"""
+Contains the core of NumPy: ndarray, ufuncs, dtypes, etc.
+
+Please note that this module is private.  All functions and objects
+are available in the main ``numpy`` namespace - use that instead.
+
+"""
+
 from __future__ import division, absolute_import, print_function
 
-from .info import __doc__
 from numpy.version import version as __version__
 
 import os
diff --git a/numpy/core/info.py b/numpy/core/info.py
deleted file mode 100644
index c6f7bbcf2..000000000
--- a/numpy/core/info.py
+++ /dev/null
@@ -1,87 +0,0 @@
-"""Defines a multi-dimensional array and useful procedures for Numerical computation.
-
-Functions
-
--   array                      - NumPy Array construction
--   zeros                      - Return an array of all zeros
--   empty                      - Return an uninitialized array
--   shape                      - Return shape of sequence or array
--   rank                       - Return number of dimensions
--   size                       - Return number of elements in entire array or a
-                                 certain dimension
--   fromstring                 - Construct array from (byte) string
--   take                       - Select sub-arrays using sequence of indices
--   put                        - Set sub-arrays using sequence of 1-D indices
--   putmask                    - Set portion of arrays using a mask
--   reshape                    - Return array with new shape
--   repeat                     - Repeat elements of array
--   choose                     - Construct new array from indexed array tuple
--   correlate                  - Correlate two 1-d arrays
--   searchsorted               - Search for element in 1-d array
--   sum                        - Total sum over a specified dimension
--   average                    - Average, possibly weighted, over axis or array.
--   cumsum                     - Cumulative sum over a specified dimension
--   product                    - Total product over a specified dimension
--   cumproduct                 - Cumulative product over a specified dimension
--   alltrue                    - Logical and over an entire axis
--   sometrue                   - Logical or over an entire axis
--   allclose                   - Tests if sequences are essentially equal
-
-More Functions:
-
--   arange                     - Return regularly spaced array
--   asarray                    - Guarantee NumPy array
--   convolve                   - Convolve two 1-d arrays
--   swapaxes                   - Exchange axes
--   concatenate                - Join arrays together
--   transpose                  - Permute axes
--   sort                       - Sort elements of array
--   argsort                    - Indices of sorted array
--   argmax                     - Index of largest value
--   argmin                     - Index of smallest value
--   inner                      - Innerproduct of two arrays
--   dot                        - Dot product (matrix multiplication)
--   outer                      - Outerproduct of two arrays
--   resize                     - Return array with arbitrary new shape
--   indices                    - Tuple of indices
--   fromfunction               - Construct array from universal function
--   diagonal                   - Return diagonal array
--   trace                      - Trace of array
--   dump                       - Dump array to file object (pickle)
--   dumps                      - Return pickled string representing data
--   load                       - Return array stored in file object
--   loads                      - Return array from pickled string
--   ravel                      - Return array as 1-D
--   nonzero                    - Indices of nonzero elements for 1-D array
--   shape                      - Shape of array
--   where                      - Construct array from binary result
--   compress                   - Elements of array where condition is true
--   clip                       - Clip array between two values
--   ones                       - Array of all ones
--   identity                   - 2-D identity array (matrix)
-
-(Universal) Math Functions
-
-       add                    logical_or             exp
-       subtract               logical_xor            log
-       multiply               logical_not            log10
-       divide                 maximum                sin
-       divide_safe            minimum                sinh
-       conjugate              bitwise_and            sqrt
-       power                  bitwise_or             tan
-       absolute               bitwise_xor            tanh
-       negative               invert                 ceil
-       greater                left_shift             fabs
-       greater_equal          right_shift            floor
-       less                   arccos                 arctan2
-       less_equal             arcsin                 fmod
-       equal                  arctan                 hypot
-       not_equal              cos                    around
-       logical_and            cosh                   sign
-       arccosh                arcsinh                arctanh
-
-"""
-from __future__ import division, absolute_import, print_function
-
-depends = ['testing']
-global_symbols = ['*']
diff --git a/numpy/distutils/__init__.py b/numpy/distutils/__init__.py
index a6f804bdc..8dbb63b28 100644
--- a/numpy/distutils/__init__.py
+++ b/numpy/distutils/__init__.py
@@ -1,12 +1,31 @@
+"""
+An enhanced distutils, providing support for Fortran compilers, for BLAS,
+LAPACK and other common libraries for numerical computing, and more.
+
+Public submodules are::
+
+    misc_util
+    system_info
+    cpu_info
+    log
+    exec_command
+
+For details, please see the *Packaging* and *NumPy Distutils User Guide*
+sections of the NumPy Reference Guide.
+
+For configuring the preference for and location of libraries like BLAS and
+LAPACK, and for setting include paths and similar build options, please see
+``site.cfg.example`` in the root of the NumPy repository or sdist.
+
+"""
+
 from __future__ import division, absolute_import, print_function
 
-from .__version__ import version as __version__
 # Must import local ccompiler ASAP in order to get
 # customized CCompiler.spawn effective.
 from . import ccompiler
 from . import unixccompiler
 
-from .info import __doc__
 from .npy_pkg_config import *
 
 # If numpy is installed, add distutils.test()
diff --git a/numpy/distutils/__version__.py b/numpy/distutils/__version__.py
deleted file mode 100644
index 969decbba..000000000
--- a/numpy/distutils/__version__.py
+++ /dev/null
@@ -1,6 +0,0 @@
-from __future__ import division, absolute_import, print_function
-
-major = 0
-minor = 4
-micro = 0
-version = '%(major)d.%(minor)d.%(micro)d' % (locals())
diff --git a/numpy/distutils/info.py b/numpy/distutils/info.py
deleted file mode 100644
index 2f5310665..000000000
--- a/numpy/distutils/info.py
+++ /dev/null
@@ -1,6 +0,0 @@
-"""
-Enhanced distutils with Fortran compilers support and more.
-"""
-from __future__ import division, absolute_import, print_function
-
-postpone_import = True
diff --git a/numpy/f2py/info.py b/numpy/f2py/info.py
deleted file mode 100644
index c895c5de2..000000000
--- a/numpy/f2py/info.py
+++ /dev/null
@@ -1,6 +0,0 @@
-"""Fortran to Python Interface Generator.
-
-"""
-from __future__ import division, absolute_import, print_function
-
-postpone_import = True
diff --git a/numpy/lib/__init__.py b/numpy/lib/__init__.py
index 906bede37..2db12d9a4 100644
--- a/numpy/lib/__init__.py
+++ b/numpy/lib/__init__.py
@@ -1,8 +1,20 @@
+"""
+**Note:** almost all functions in the ``numpy.lib`` namespace
+are also present in the main ``numpy`` namespace.  Please use the
+functions as ``np.<funcname>`` where possible.
+
+``numpy.lib`` is mostly a space for implementing functions that don't
+belong in core or in another NumPy submodule with a clear purpose
+(e.g. ``random``, ``fft``, ``linalg``, ``ma``).
+
+Most contains basic functions that are used by several submodules and are
+useful to have in the main name-space.
+
+"""
 from __future__ import division, absolute_import, print_function
 
 import math
 
-from .info import __doc__
 from numpy.version import version as __version__
 
 # Public submodules
diff --git a/numpy/lib/info.py b/numpy/lib/info.py
deleted file mode 100644
index 8815a52f0..000000000
--- a/numpy/lib/info.py
+++ /dev/null
@@ -1,160 +0,0 @@
-"""
-Basic functions used by several sub-packages and
-useful to have in the main name-space.
-
-Type Handling
--------------
-================ ===================
-iscomplexobj     Test for complex object, scalar result
-isrealobj        Test for real object, scalar result
-iscomplex        Test for complex elements, array result
-isreal           Test for real elements, array result
-imag             Imaginary part
-real             Real part
-real_if_close    Turns complex number with tiny imaginary part to real
-isneginf         Tests for negative infinity, array result
-isposinf         Tests for positive infinity, array result
-isnan            Tests for nans, array result
-isinf            Tests for infinity, array result
-isfinite         Tests for finite numbers, array result
-isscalar         True if argument is a scalar
-nan_to_num       Replaces NaN's with 0 and infinities with large numbers
-cast             Dictionary of functions to force cast to each type
-common_type      Determine the minimum common type code for a group
-                 of arrays
-mintypecode      Return minimal allowed common typecode.
-================ ===================
-
-Index Tricks
-------------
-================ ===================
-mgrid            Method which allows easy construction of N-d
-                 'mesh-grids'
-``r_``           Append and construct arrays: turns slice objects into
-                 ranges and concatenates them, for 2d arrays appends rows.
-index_exp        Konrad Hinsen's index_expression class instance which
-                 can be useful for building complicated slicing syntax.
-================ ===================
-
-Useful Functions
-----------------
-================ ===================
-select           Extension of where to multiple conditions and choices
-extract          Extract 1d array from flattened array according to mask
-insert           Insert 1d array of values into Nd array according to mask
-linspace         Evenly spaced samples in linear space
-logspace         Evenly spaced samples in logarithmic space
-fix              Round x to nearest integer towards zero
-mod              Modulo mod(x,y) = x % y except keeps sign of y
-amax             Array maximum along axis
-amin             Array minimum along axis
-ptp              Array max-min along axis
-cumsum           Cumulative sum along axis
-prod             Product of elements along axis
-cumprod          Cumluative product along axis
-diff             Discrete differences along axis
-angle            Returns angle of complex argument
-unwrap           Unwrap phase along given axis (1-d algorithm)
-sort_complex     Sort a complex-array (based on real, then imaginary)
-trim_zeros       Trim the leading and trailing zeros from 1D array.
-vectorize        A class that wraps a Python function taking scalar
-                 arguments into a generalized function which can handle
-                 arrays of arguments using the broadcast rules of
-                 numerix Python.
-================ ===================
-
-Shape Manipulation
-------------------
-================ ===================
-squeeze          Return a with length-one dimensions removed.
-atleast_1d       Force arrays to be >= 1D
-atleast_2d       Force arrays to be >= 2D
-atleast_3d       Force arrays to be >= 3D
-vstack           Stack arrays vertically (row on row)
-hstack           Stack arrays horizontally (column on column)
-column_stack     Stack 1D arrays as columns into 2D array
-dstack           Stack arrays depthwise (along third dimension)
-stack            Stack arrays along a new axis
-split            Divide array into a list of sub-arrays
-hsplit           Split into columns
-vsplit           Split into rows
-dsplit           Split along third dimension
-================ ===================
-
-Matrix (2D Array) Manipulations
--------------------------------
-================ ===================
-fliplr           2D array with columns flipped
-flipud           2D array with rows flipped
-rot90            Rotate a 2D array a multiple of 90 degrees
-eye              Return a 2D array with ones down a given diagonal
-diag             Construct a 2D array from a vector, or return a given
-                 diagonal from a 2D array.
-mat              Construct a Matrix
-bmat             Build a Matrix from blocks
-================ ===================
-
-Polynomials
------------
-================ ===================
-poly1d           A one-dimensional polynomial class
-poly             Return polynomial coefficients from roots
-roots            Find roots of polynomial given coefficients
-polyint          Integrate polynomial
-polyder          Differentiate polynomial
-polyadd          Add polynomials
-polysub          Subtract polynomials
-polymul          Multiply polynomials
-polydiv          Divide polynomials
-polyval          Evaluate polynomial at given argument
-================ ===================
-
-Iterators
----------
-================ ===================
-Arrayterator     A buffered iterator for big arrays.
-================ ===================
-
-Import Tricks
--------------
-================ ===================
-ppimport         Postpone module import until trying to use it
-ppimport_attr    Postpone module import until trying to use its attribute
-ppresolve        Import postponed module and return it.
-================ ===================
-
-Machine Arithmetics
--------------------
-================ ===================
-machar_single    Single precision floating point arithmetic parameters
-machar_double    Double precision floating point arithmetic parameters
-================ ===================
-
-Threading Tricks
-----------------
-================ ===================
-ParallelExec     Execute commands in parallel thread.
-================ ===================
-
-Array Set Operations
------------------------
-Set operations for numeric arrays based on sort() function.
-
-================ ===================
-unique           Unique elements of an array.
-isin             Test whether each element of an ND array is present 
-                 anywhere within a second array.
-ediff1d          Array difference (auxiliary function).
-intersect1d      Intersection of 1D arrays with unique elements.
-setxor1d         Set exclusive-or of 1D arrays with unique elements.
-in1d             Test whether elements in a 1D array are also present in
-                 another array.
-union1d          Union of 1D arrays with unique elements.
-setdiff1d        Set difference of 1D arrays with unique elements.
-================ ===================
-
-"""
-from __future__ import division, absolute_import, print_function
-
-depends = ['core', 'testing']
-global_symbols = ['*']
diff --git a/numpy/linalg/__init__.py b/numpy/linalg/__init__.py
index 4b696c883..55560815d 100644
--- a/numpy/linalg/__init__.py
+++ b/numpy/linalg/__init__.py
@@ -1,53 +1,77 @@
 """
-Core Linear Algebra Tools
-=========================
-
-=============== ==========================================================
-Linear algebra basics
-==========================================================================
-norm            Vector or matrix norm
-inv             Inverse of a square matrix
-solve           Solve a linear system of equations
-det             Determinant of a square matrix
-slogdet         Logarithm of the determinant of a square matrix
-lstsq           Solve linear least-squares problem
-pinv            Pseudo-inverse (Moore-Penrose) calculated using a singular
-                value decomposition
-matrix_power    Integer power of a square matrix
-matrix_rank     Calculate matrix rank using an SVD-based method
-=============== ==========================================================
-
-=============== ==========================================================
-Eigenvalues and decompositions
-==========================================================================
-eig             Eigenvalues and vectors of a square matrix
-eigh            Eigenvalues and eigenvectors of a Hermitian matrix
-eigvals         Eigenvalues of a square matrix
-eigvalsh        Eigenvalues of a Hermitian matrix
-qr              QR decomposition of a matrix
-svd             Singular value decomposition of a matrix
-cholesky        Cholesky decomposition of a matrix
-=============== ==========================================================
-
-=============== ==========================================================
-Tensor operations
-==========================================================================
-tensorsolve     Solve a linear tensor equation
-tensorinv       Calculate an inverse of a tensor
-=============== ==========================================================
-
-=============== ==========================================================
+``numpy.linalg``
+================
+
+The NumPy linear algebra functions rely on BLAS and LAPACK to provide efficient
+low level implementations of standard linear algebra algorithms. Those
+libraries may be provided by NumPy itself using C versions of a subset of their
+reference implementations but, when possible, highly optimized libraries that
+take advantage of specialized processor functionality are preferred. Examples
+of such libraries are OpenBLAS, MKL (TM), and ATLAS. Because those libraries
+are multithreaded and processor dependent, environmental variables and external
+packages such as threadpoolctl may be needed to control the number of threads
+or specify the processor architecture.
+
+- OpenBLAS: https://www.openblas.net/
+- threadpoolctl: https://github.com/joblib/threadpoolctl
+
+Please note that the most-used linear algebra functions in NumPy are present in
+the main ``numpy`` namespace rather than in ``numpy.linalg``.  There are:
+``dot``, ``vdot``, ``inner``, ``outer``, ``matmul``, ``tensordot``, ``einsum``,
+``einsum_path`` and ``kron``.
+
+Functions present in numpy.linalg are listed below.
+
+
+Matrix and vector products
+--------------------------
+
+   multi_dot
+   matrix_power
+
+Decompositions
+--------------
+
+   cholesky
+   qr
+   svd
+
+Matrix eigenvalues
+------------------
+
+   eig
+   eigh
+   eigvals
+   eigvalsh
+
+Norms and other numbers
+-----------------------
+
+   norm
+   cond
+   det
+   matrix_rank
+   slogdet
+
+Solving equations and inverting matrices
+----------------------------------------
+
+   solve
+   tensorsolve
+   lstsq
+   inv
+   pinv
+   tensorinv
+
 Exceptions
-==========================================================================
-LinAlgError     Indicates a failed linear algebra operation
-=============== ==========================================================
+----------
+
+   LinAlgError
 
 """
 from __future__ import division, absolute_import, print_function
 
 # To get sub-modules
-from .info import __doc__
-
 from .linalg import *
 
 from numpy._pytesttester import PytestTester
diff --git a/numpy/linalg/info.py b/numpy/linalg/info.py
deleted file mode 100644
index 646ecda04..000000000
--- a/numpy/linalg/info.py
+++ /dev/null
@@ -1,37 +0,0 @@
-"""\
-Core Linear Algebra Tools
--------------------------
-Linear algebra basics:
-
-- norm            Vector or matrix norm
-- inv             Inverse of a square matrix
-- solve           Solve a linear system of equations
-- det             Determinant of a square matrix
-- lstsq           Solve linear least-squares problem
-- pinv            Pseudo-inverse (Moore-Penrose) calculated using a singular
-                  value decomposition
-- matrix_power    Integer power of a square matrix
-
-Eigenvalues and decompositions:
-
-- eig             Eigenvalues and vectors of a square matrix
-- eigh            Eigenvalues and eigenvectors of a Hermitian matrix
-- eigvals         Eigenvalues of a square matrix
-- eigvalsh        Eigenvalues of a Hermitian matrix
-- qr              QR decomposition of a matrix
-- svd             Singular value decomposition of a matrix
-- cholesky        Cholesky decomposition of a matrix
-
-Tensor operations:
-
-- tensorsolve     Solve a linear tensor equation
-- tensorinv       Calculate an inverse of a tensor
-
-Exceptions:
-
-- LinAlgError     Indicates a failed linear algebra operation
-
-"""
-from __future__ import division, absolute_import, print_function
-
-depends = ['core']
diff --git a/numpy/random/info.py b/numpy/random/info.py
deleted file mode 100644
index b9fd7f26a..000000000
--- a/numpy/random/info.py
+++ /dev/null
@@ -1,5 +0,0 @@
-from __future__ import division, absolute_import, print_function
-
-from .. import __doc__
-
-depends = ['core']
diff --git a/numpy/tests/test_public_api.py b/numpy/tests/test_public_api.py
index 6de171dbb..e3621c0fd 100644
--- a/numpy/tests/test_public_api.py
+++ b/numpy/tests/test_public_api.py
@@ -199,7 +199,6 @@ PRIVATE_BUT_PRESENT_MODULES = ['numpy.' + s for s in [
     "core.fromnumeric",
     "core.function_base",
     "core.getlimits",
-    "core.info",
     "core.machar",
     "core.memmap",
     "core.multiarray",
@@ -251,7 +250,6 @@ PRIVATE_BUT_PRESENT_MODULES = ['numpy.' + s for s in [
     "distutils.fcompiler.sun",
     "distutils.fcompiler.vast",
     "distutils.from_template",
-    "distutils.info",
     "distutils.intelccompiler",
     "distutils.lib2def",
     "distutils.line_endings",
@@ -272,7 +270,6 @@ PRIVATE_BUT_PRESENT_MODULES = ['numpy.' + s for s in [
     "f2py.f2py_testing",
     "f2py.f90mod_rules",
     "f2py.func2subr",
-    "f2py.info",
     "f2py.rules",
     "f2py.use_rules",
     "fft.helper",
@@ -283,7 +280,6 @@ PRIVATE_BUT_PRESENT_MODULES = ['numpy.' + s for s in [
     "lib.function_base",
     "lib.histograms",
     "lib.index_tricks",
-    "lib.info",
     "lib.nanfunctions",
     "lib.npyio",
     "lib.polynomial",
@@ -294,7 +290,6 @@ PRIVATE_BUT_PRESENT_MODULES = ['numpy.' + s for s in [
     "lib.ufunclike",
     "lib.user_array",  # note: not in np.lib, but probably should just be deleted
     "lib.utils",
-    "linalg.info",
     "linalg.lapack_lite",
     "linalg.linalg",
     "ma.bench",
@@ -307,7 +302,6 @@ PRIVATE_BUT_PRESENT_MODULES = ['numpy.' + s for s in [
     "random.bounded_integers",
     "random.common",
     "random.generator",
-    "random.info",
     "random.mt19937",
     "random.mtrand",
     "random.pcg64",