DOC, API: add numpy.random.__index__.pxd and document numpy.random.* funcs

14 files changed, 415 insertions, 66 deletions

diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst
index d28646df9..48d7a4819 100644
--- a/doc/source/reference/random/index.rst
+++ b/doc/source/reference/random/index.rst
@@ -22,34 +22,41 @@ Since Numpy version 1.17.0 the Generator can be initialized with a
 number of different BitGenerators. It exposes many different probability
 distributions. See `NEP 19 <https://www.numpy.org/neps/
 nep-0019-rng-policy.html>`_ for context on the updated random Numpy number
-routines. The legacy `.RandomState` random number routines are still
+routines. The legacy `RandomState` random number routines are still
 available, but limited to a single BitGenerator.
 
-For convenience and backward compatibility, a single `~.RandomState`
+For convenience and backward compatibility, a single `RandomState`
 instance's methods are imported into the numpy.random namespace, see
 :ref:`legacy` for the complete list.
 
+.. _random-quick-start:
+
 Quick Start
 -----------
 
-By default, `~Generator` uses bits provided by `PCG64` which
-has better statistical properties than the legacy mt19937 random
-number generator in `~.RandomState`.
+Call `default_rng` to get a new instance of a `Generator`, then call its
+methods to obtain samples from different distributions.  By default,
+`Generator` uses bits provided by `PCG64` which has better statistical
+properties than the legacy `MT19937` used in `RandomState`.
 
 .. code-block:: python
 
-  # Uses the old numpy.random.RandomState
+  #Do this
+  from numpy.random import default_rng
+  val = default_rng().standard_normal()
+
+  # instead of this
   from numpy import random
-  random.standard_normal()
+  val = random.standard_normal()
 
-`~Generator` can be used as a replacement for `~.RandomState`. Both class
-instances now hold a internal `BitGenerator` instance to provide the bit
+`Generator` can be used as a replacement for `RandomState`. Both class
+instances hold a internal `BitGenerator` instance to provide the bit
 stream, it is accessible as ``gen.bit_generator``. Some long-overdue API
 cleanup means that legacy and compatibility methods have been removed from
-`~.Generator`
+`Generator`
 
 =================== ============== ============
-`~.RandomState`     `~.Generator`  Notes
+`RandomState`       `Generator`    Notes
 ------------------- -------------- ------------
 ``random_sample``,  ``random``     Compatible with `random.random`
 ``rand``
@@ -58,21 +65,12 @@ cleanup means that legacy and compatibility methods have been removed from
 ``random_integers``
 ------------------- -------------- ------------
 ``tomaxint``        removed        Use ``integers(0, np.iinfo(np.int_).max,``
-                                                 ``endpoint=False)``
+                                   ``endpoint=False)``
 ------------------- -------------- ------------
-``seed``            removed        Use `~.SeedSequence.spawn`
+``seed``            removed        Use `SeedSequence.spawn`
 =================== ============== ============
 
-See `new-or-different` for more information
-
-.. code-block:: python
-
-  # As replacement for RandomState(); default_rng() instantiates Generator with
-  # the default PCG64 BitGenerator.
-  from numpy.random import default_rng
-  rg = default_rng()
-  rg.standard_normal()
-  rg.bit_generator
+See :ref:`new-or-different` for more information
 
 Something like the following code can be used to support both ``RandomState``
 and ``Generator``, with the understanding that the interfaces are slightly
@@ -87,9 +85,9 @@ different
     a = rg_integers(1000)
 
 Seeds can be passed to any of the BitGenerators. The provided value is mixed
-via `~.SeedSequence` to spread a possible sequence of seeds across a wider
-range of initialization states for the BitGenerator. Here `~.PCG64` is used and
-is wrapped with a `~.Generator`.
+via `SeedSequence` to spread a possible sequence of seeds across a wider
+range of initialization states for the BitGenerator. Here `PCG64` is used and
+is wrapped with a `Generator`.
 
 .. code-block:: python
 
@@ -100,7 +98,7 @@ is wrapped with a `~.Generator`.
 Introduction
 ------------
 The new infrastructure takes a different approach to producing random numbers
-from the `~.RandomState` object.  Random number generation is separated into
+from the `RandomState` object.  Random number generation is separated into
 two components, a bit generator and a random generator.
 
 The `BitGenerator` has a limited set of responsibilities. It manages state
@@ -113,8 +111,8 @@ distributions, e.g., simulated normal random values. This structure allows
 alternative bit generators to be used with little code duplication.
 
 The `Generator` is the user-facing object that is nearly identical to
-`.RandomState`. The canonical method to initialize a generator passes a
-`~.PCG64` bit generator as the sole argument.
+`RandomState`. The canonical method to initialize a generator passes a
+`PCG64` bit generator as the sole argument.
 
 .. code-block:: python
 
@@ -139,9 +137,9 @@ What's New or Different
   The Box-Muller method used to produce NumPy's normals is no longer available
   in `Generator`.  It is not possible to reproduce the exact random
   values using Generator for the normal distribution or any other
-  distribution that relies on the normal such as the `.RandomState.gamma` or
-  `.RandomState.standard_t`. If you require bitwise backward compatible
-  streams, use `.RandomState`.
+  distribution that relies on the normal such as the `RandomState.gamma` or
+  `RandomState.standard_t`. If you require bitwise backward compatible
+  streams, use `RandomState`.
 
 * The Generator's normal, exponential and gamma functions use 256-step Ziggurat
   methods which are 2-10 times faster than NumPy's Box-Muller or inverse CDF
@@ -152,20 +150,20 @@ What's New or Different
 * Optional ``out`` argument that allows existing arrays to be filled for
   select distributions
 * All BitGenerators can produce doubles, uint64s and uint32s via CTypes
-  (`~.PCG64.ctypes`) and CFFI (`~.PCG64.cffi`). This allows the bit generators
+  (`PCG64.ctypes`) and CFFI (`PCG64.cffi`). This allows the bit generators
   to be used in numba.
 * The bit generators can be used in downstream projects via
   :ref:`Cython <random_cython>`.
-* `~.Generator.integers` is now the canonical way to generate integer
+* `Generator.integers` is now the canonical way to generate integer
   random numbers from a discrete uniform distribution. The ``rand`` and
-  ``randn`` methods are only available through the legacy `~.RandomState`.
+  ``randn`` methods are only available through the legacy `RandomState`.
   The ``endpoint`` keyword can be used to specify open or closed intervals.
   This replaces both ``randint`` and the deprecated ``random_integers``.
-* `~.Generator.random` is now the canonical way to generate floating-point
-  random numbers, which replaces `.RandomState.random_sample`,
-  `.RandomState.sample`, and `.RandomState.ranf`. This is consistent with
+* `Generator.random` is now the canonical way to generate floating-point
+  random numbers, which replaces `RandomState.random_sample`,
+  `RandomState.sample`, and `RandomState.ranf`. This is consistent with
   Python's `random.random`.
-* All BitGenerators in numpy use `~SeedSequence` to convert seeds into
+* All BitGenerators in numpy use `SeedSequence` to convert seeds into
   initialized states.
 
 See :ref:`new-or-different` for a complete list of improvements and
@@ -202,8 +200,9 @@ Features
    c-api
    Examples of using Numba, Cython, CFFI <extending>
 
-Original Source
-~~~~~~~~~~~~~~~
+Original Source of the Generator and BitGenerators
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This package was developed independently of NumPy and was integrated in version
 1.17.0. The original repo is at https://github.com/bashtage/randomgen.
+
diff --git a/doc/source/reference/random/legacy.rst b/doc/source/reference/random/legacy.rst
index 413a42727..9118fc052 100644
--- a/doc/source/reference/random/legacy.rst
+++ b/doc/source/reference/random/legacy.rst
@@ -121,3 +121,63 @@ Distributions
    ~RandomState.wald
    ~RandomState.weibull
    ~RandomState.zipf
+
+Toplevel `numpy.random` functions
+=================================
+Many of the RandomState methods above are exported as top-level `numpy.random`
+functions. These are:
+
+.. autosummary::
+   :toctree: generated/
+
+    beta
+    binomial
+    bytes
+    chisquare
+    choice
+    dirichlet
+    exponential
+    f
+    gamma
+    geometric
+    get_state
+    gumbel
+    hypergeometric
+    laplace
+    logistic
+    lognormal
+    logseries
+    multinomial
+    multivariate_normal
+    negative_binomial
+    noncentral_chisquare
+    noncentral_f
+    normal
+    pareto
+    permutation
+    poisson
+    power
+    rand
+    randint
+    randn
+    random
+    random_integers
+    random_sample
+    ranf
+    rayleigh
+    sample
+    seed
+    set_state
+    shuffle
+    standard_cauchy
+    standard_exponential
+    standard_gamma
+    standard_normal
+    standard_t
+    triangular
+    uniform
+    vonmises
+    wald
+    weibull
+    zipf
+
diff --git a/numpy/random/__init__.pxd b/numpy/random/__init__.pxd
new file mode 100644
index 000000000..05e073876
--- /dev/null
+++ b/numpy/random/__init__.pxd
@@ -0,0 +1,14 @@
+cimport numpy as np
+from libc.stdint cimport uint32_t, uint64_t
+
+cdef extern from "numpy/random/bitgen.h":
+    struct bitgen:
+        void *state
+        uint64_t (*next_uint64)(void *st) nogil
+        uint32_t (*next_uint32)(void *st) nogil
+        double (*next_double)(void *st) nogil
+        uint64_t (*next_raw)(void *st) nogil
+
+    ctypedef bitgen bitgen_t
+
+from numpy.random._bit_generator cimport BitGenerator, SeedSequence
diff --git a/numpy/random/_bounded_integers.pxd.in b/numpy/random/_bounded_integers.pxd.in
index 320d35774..5ae5a8067 100644
--- a/numpy/random/_bounded_integers.pxd.in
+++ b/numpy/random/_bounded_integers.pxd.in
@@ -4,7 +4,7 @@ import numpy as np
 cimport numpy as np
 ctypedef np.npy_bool bool_t
 
-from ._bit_generator cimport bitgen_t
+from numpy.random cimport bitgen_t
 
 cdef inline uint64_t _gen_mask(uint64_t max_val) nogil:
     """Mask generator for use in bounded random numbers"""
diff --git a/numpy/random/_common.pxd b/numpy/random/_common.pxd
index 74bebca83..588f613ae 100644
--- a/numpy/random/_common.pxd
+++ b/numpy/random/_common.pxd
@@ -5,7 +5,7 @@ from libc.stdint cimport uint32_t, uint64_t, int32_t, int64_t
 import numpy as np
 cimport numpy as np
 
-from ._bit_generator cimport bitgen_t
+from numpy.random cimport bitgen_t
 
 cdef double POISSON_LAM_MAX
 cdef double LEGACY_POISSON_LAM_MAX
diff --git a/numpy/random/_examples/cython/extending.pyx b/numpy/random/_examples/cython/extending.pyx
index d12c0b919..7a0dfe078 100644
--- a/numpy/random/_examples/cython/extending.pyx
+++ b/numpy/random/_examples/cython/extending.pyx
@@ -8,7 +8,7 @@ import numpy as np
 cimport numpy as np
 cimport cython
 
-from numpy.random._bit_generator cimport bitgen_t
+from numpy.random cimport bitgen_t
 from numpy.random import PCG64
 
 np.import_array()
diff --git a/numpy/random/_examples/cython/extending_distributions.pyx b/numpy/random/_examples/cython/extending_distributions.pyx
index 3f342c475..1bef506ef 100644
--- a/numpy/random/_examples/cython/extending_distributions.pyx
+++ b/numpy/random/_examples/cython/extending_distributions.pyx
@@ -8,8 +8,7 @@ cimport numpy as np
 cimport cython
 from cpython.pycapsule cimport PyCapsule_IsValid, PyCapsule_GetPointer
 from libc.stdint cimport uint16_t, uint64_t
-from numpy.random._bit_generator cimport bitgen_t
-
+from numpy.random cimport bitgen_t
 from numpy.random import PCG64
 
 
@@ -72,3 +71,4 @@ def uint10_uniforms(Py_ssize_t n):
 
     randoms = np.asarray(random_values)
     return randoms
+
diff --git a/numpy/random/_generator.pyx b/numpy/random/_generator.pyx
index 2d8455982..64ec73986 100644
--- a/numpy/random/_generator.pyx
+++ b/numpy/random/_generator.pyx
@@ -19,7 +19,7 @@ from ._bounded_integers cimport (_rand_bool, _rand_int32, _rand_int64,
          _rand_uint8, _gen_mask)
 from ._bounded_integers import _integers_types
 from ._pcg64 import PCG64
-from ._bit_generator cimport bitgen_t
+from numpy.random cimport bitgen_t
 from ._common cimport (POISSON_LAM_MAX, CONS_POSITIVE, CONS_NONE,
             CONS_NON_NEGATIVE, CONS_BOUNDED_0_1, CONS_BOUNDED_GT_0_1,
             CONS_GT_1, CONS_POSITIVE_NOT_NAN, CONS_POISSON,
@@ -1004,6 +1004,12 @@ cdef class Generator:
             A floating-point array of shape ``size`` of drawn samples, or a
             single sample if ``size`` was not specified.
 
+        See Also
+        --------
+        normal :
+            Equivalent function with additional ``loc`` and ``scale`` arguments
+            for setting the mean and standard deviation.
+
         Notes
         -----
         For random samples from :math:`N(\\mu, \\sigma^2)`, use one of::
@@ -1011,12 +1017,6 @@ cdef class Generator:
             mu + sigma * gen.standard_normal(size=...)
             gen.normal(mu, sigma, size=...)
 
-        See Also
-        --------
-        normal :
-            Equivalent function with additional ``loc`` and ``scale`` arguments
-            for setting the mean and standard deviation.
-
         Examples
         --------
         >>> rng = np.random.default_rng()
diff --git a/numpy/random/_mt19937.pyx b/numpy/random/_mt19937.pyx
index e99652b73..919a96a4c 100644
--- a/numpy/random/_mt19937.pyx
+++ b/numpy/random/_mt19937.pyx
@@ -4,7 +4,7 @@ import numpy as np
 cimport numpy as np
 
 from libc.stdint cimport uint32_t, uint64_t
-from ._bit_generator cimport BitGenerator, SeedSequence
+from numpy.random cimport BitGenerator, SeedSequence
 
 __all__ = ['MT19937']
 
diff --git a/numpy/random/_pcg64.pyx b/numpy/random/_pcg64.pyx
index 1a5d852a2..05d27db5c 100644
--- a/numpy/random/_pcg64.pyx
+++ b/numpy/random/_pcg64.pyx
@@ -3,7 +3,7 @@ cimport numpy as np
 
 from libc.stdint cimport uint32_t, uint64_t
 from ._common cimport uint64_to_double, wrap_int
-from ._bit_generator cimport BitGenerator
+from numpy.random cimport BitGenerator
 
 __all__ = ['PCG64']
 
diff --git a/numpy/random/_philox.pyx b/numpy/random/_philox.pyx
index 9f136c32f..7e8880490 100644
--- a/numpy/random/_philox.pyx
+++ b/numpy/random/_philox.pyx
@@ -10,7 +10,7 @@ cimport numpy as np
 
 from libc.stdint cimport uint32_t, uint64_t
 from ._common cimport uint64_to_double, int_to_array, wrap_int
-from ._bit_generator cimport BitGenerator
+from numpy.random cimport BitGenerator
 
 __all__ = ['Philox']
 
diff --git a/numpy/random/_sfc64.pyx b/numpy/random/_sfc64.pyx
index 1633669d5..1daee34f8 100644
--- a/numpy/random/_sfc64.pyx
+++ b/numpy/random/_sfc64.pyx
@@ -3,7 +3,7 @@ cimport numpy as np
 
 from libc.stdint cimport uint32_t, uint64_t
 from ._common cimport uint64_to_double
-from ._bit_generator cimport BitGenerator
+from numpy.random cimport BitGenerator
 
 __all__ = ['SFC64']
 
diff --git a/numpy/random/mtrand.pyx b/numpy/random/mtrand.pyx
index 691a6e6e7..e6cd9b87e 100644
--- a/numpy/random/mtrand.pyx
+++ b/numpy/random/mtrand.pyx
@@ -17,7 +17,7 @@ from ._bounded_integers cimport (_rand_bool, _rand_int32, _rand_int64,
          _rand_uint8,)
 from ._bounded_integers import _integers_types
 from ._mt19937 import MT19937 as _MT19937
-from ._bit_generator cimport bitgen_t
+from numpy.random cimport bitgen_t
 from ._common cimport (POISSON_LAM_MAX, CONS_POSITIVE, CONS_NONE,
             CONS_NON_NEGATIVE, CONS_BOUNDED_0_1, CONS_BOUNDED_GT_0_1, CONS_GTE_1,
             CONS_GT_1, LEGACY_CONS_POISSON,
@@ -379,6 +379,10 @@ cdef class RandomState:
 
           (b - a) * random_sample() + a
 
+        .. note::
+            New code should use ``default_rng().random`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         size : int or tuple of ints, optional
@@ -392,6 +396,10 @@ cdef class RandomState:
             Array of random floats of shape `size` (unless ``size=None``, in which
             case a single float is returned).
 
+        See also
+        --------
+        Generator.random: which should be used for new code.
+
         Examples
         --------
         >>> np.random.random_sample()
@@ -441,6 +449,10 @@ cdef class RandomState:
 
         It is often seen in Bayesian inference and order statistics.
 
+        .. note::
+            New code should use ``default_rng().beta`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         a : float or array_like of floats
@@ -458,6 +470,9 @@ cdef class RandomState:
         out : ndarray or scalar
             Drawn samples from the parameterized beta distribution.
 
+        See also
+        --------
+        Generator.beta: which should be used for new code.
         """
         return cont(&legacy_beta, &self._aug_state, size, self.lock, 2,
                     a, 'a', CONS_POSITIVE,
@@ -484,6 +499,10 @@ cdef class RandomState:
         the size of raindrops measured over many rainstorms [1]_, or the time
         between page requests to Wikipedia [2]_.
 
+        .. note::
+            New code should use ``default_rng().exponential`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         scale : float or array_like of floats
@@ -500,6 +519,10 @@ cdef class RandomState:
         out : ndarray or scalar
             Drawn samples from the parameterized exponential distribution.
 
+        See also
+        --------
+        Generator.exponential: which should be used for new code.
+
         References
         ----------
         .. [1] Peyton Z. Peebles Jr., "Probability, Random Variables and
@@ -525,6 +548,10 @@ cdef class RandomState:
         `standard_exponential` is identical to the exponential distribution
         with a scale parameter of 1.
 
+        .. note::
+            New code should use ``default_rng().standard_exponential`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         size : int or tuple of ints, optional
@@ -537,6 +564,10 @@ cdef class RandomState:
         out : float or ndarray
             Drawn samples.
 
+        See also
+        --------
+        Generator.standard_exponential: which should be used for new code.
+
         Examples
         --------
         Output a 3x8000 array:
@@ -618,6 +649,10 @@ cdef class RandomState:
         the specified dtype in the "half-open" interval [`low`, `high`). If
         `high` is None (the default), then results are from [0, `low`).
 
+        .. note::
+            New code should use ``default_rng().integers`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         low : int or array-like of ints
@@ -651,6 +686,7 @@ cdef class RandomState:
         random_integers : similar to `randint`, only for the closed
             interval [`low`, `high`], and 1 is the lowest value if `high` is
             omitted.
+        Generator.integers: which should be used for new code.
 
         Examples
         --------
@@ -735,6 +771,10 @@ cdef class RandomState:
 
         Return random bytes.
 
+        .. note::
+            New code should use ``default_rng().bytes`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         length : int
@@ -745,11 +785,14 @@ cdef class RandomState:
         out : str
             String of length `length`.
 
+        See also
+        --------
+        Generator.bytes: which should be used for new code.
+
         Examples
         --------
         >>> np.random.bytes(10)
         ' eh\\x85\\x022SZ\\xbf\\xa4' #random
-
         """
         cdef Py_ssize_t n_uint32 = ((length - 1) // 4 + 1)
         # Interpret the uint32s as little-endian to convert them to bytes
@@ -766,6 +809,10 @@ cdef class RandomState:
 
                 .. versionadded:: 1.7.0
 
+        .. note::
+            New code should use ``default_rng().choice`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         a : 1-D array-like or int
@@ -799,6 +846,7 @@ cdef class RandomState:
         See Also
         --------
         randint, shuffle, permutation
+        Generator.choice: which should be used in new code
 
         Examples
         --------
@@ -958,6 +1006,10 @@ cdef class RandomState:
         any value within the given interval is equally likely to be drawn
         by `uniform`.
 
+        .. note::
+            New code should use ``default_rng().uniform`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         low : float or array_like of floats, optional
@@ -987,6 +1039,7 @@ cdef class RandomState:
         rand : Convenience function that accepts dimensions as input, e.g.,
                ``rand(2,2)`` would generate a 2-by-2 array of floats,
                uniformly distributed over ``[0, 1)``.
+        Generator.uniform: which should be used for new code.
 
         Notes
         -----
@@ -1114,6 +1167,10 @@ cdef class RandomState:
             tuple to specify the size of the output, which is consistent with
             other NumPy functions like `numpy.zeros` and `numpy.ones`.
 
+        .. note::
+            New code should use ``default_rng().standard_normal`` (see
+            `random-quick-start`) instead.
+
         If positive int_like arguments are provided, `randn` generates an array
         of shape ``(d0, d1, ..., dn)``, filled
         with random floats sampled from a univariate "normal" (Gaussian)
@@ -1137,6 +1194,7 @@ cdef class RandomState:
         --------
         standard_normal : Similar, but takes a tuple as its argument.
         normal : Also accepts mu and sigma arguments.
+        Generator.standard_normal: which should be used for new code.
 
         Notes
         -----
@@ -1263,6 +1321,10 @@ cdef class RandomState:
 
         Draw samples from a standard Normal distribution (mean=0, stdev=1).
 
+        .. note::
+            New code should use ``default_rng().standard_normal`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         size : int or tuple of ints, optional
@@ -1276,6 +1338,13 @@ cdef class RandomState:
             A floating-point array of shape ``size`` of drawn samples, or a
             single sample if ``size`` was not specified.
 
+        See Also
+        --------
+        normal :
+            Equivalent function with additional ``loc`` and ``scale`` arguments
+            for setting the mean and standard deviation.
+        Generator.standard_normal: which should be used for new code.
+
         Notes
         -----
         For random samples from :math:`N(\\mu, \\sigma^2)`, use one of::
@@ -1283,12 +1352,6 @@ cdef class RandomState:
             mu + sigma * np.random.standard_normal(size=...)
             np.random.normal(mu, sigma, size=...)
 
-        See Also
-        --------
-        normal :
-            Equivalent function with additional ``loc`` and ``scale`` arguments
-            for setting the mean and standard deviation.
-
         Examples
         --------
         >>> np.random.standard_normal()
@@ -1333,6 +1396,10 @@ cdef class RandomState:
         by a large number of tiny, random disturbances, each with its own
         unique distribution [2]_.
 
+        .. note::
+            New code should use ``default_rng().normal`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         loc : float or array_like of floats
@@ -1355,6 +1422,7 @@ cdef class RandomState:
         --------
         scipy.stats.norm : probability density function, distribution or
             cumulative density function, etc.
+        Generator.normal: which should be used for new code.
 
         Notes
         -----
@@ -1428,6 +1496,10 @@ cdef class RandomState:
         Samples are drawn from a Gamma distribution with specified parameters,
         shape (sometimes designated "k") and scale=1.
 
+        .. note::
+            New code should use ``default_rng().standard_gamma`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         shape : float or array_like of floats
@@ -1447,6 +1519,7 @@ cdef class RandomState:
         --------
         scipy.stats.gamma : probability density function, distribution or
             cumulative density function, etc.
+        Generator.standard_gamma: which should be used for new code.
 
         Notes
         -----
@@ -1504,6 +1577,10 @@ cdef class RandomState:
         `shape` (sometimes designated "k") and `scale` (sometimes designated
         "theta"), where both parameters are > 0.
 
+        .. note::
+            New code should use ``default_rng().gamma`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         shape : float or array_like of floats
@@ -1526,6 +1603,7 @@ cdef class RandomState:
         --------
         scipy.stats.gamma : probability density function, distribution or
             cumulative density function, etc.
+        Generator.gamma: which should be used for new code.
 
         Notes
         -----
@@ -1588,6 +1666,10 @@ cdef class RandomState:
         that arises in ANOVA tests, and is the ratio of two chi-square
         variates.
 
+        .. note::
+            New code should use ``default_rng().f`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         dfnum : float or array_like of floats
@@ -1609,6 +1691,7 @@ cdef class RandomState:
         --------
         scipy.stats.f : probability density function, distribution or
             cumulative density function, etc.
+        Generator.f: which should be used for new code.
 
         Notes
         -----
@@ -1671,6 +1754,10 @@ cdef class RandomState:
         freedom in denominator), where both parameters > 1.
         `nonc` is the non-centrality parameter.
 
+        .. note::
+            New code should use ``default_rng().noncentral_f`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         dfnum : float or array_like of floats
@@ -1695,6 +1782,10 @@ cdef class RandomState:
         out : ndarray or scalar
             Drawn samples from the parameterized noncentral Fisher distribution.
 
+        See also
+        --------
+        Generator.noncentral_f: which should be used for new code.
+
         Notes
         -----
         When calculating the power of an experiment (power = probability of
@@ -1748,6 +1839,10 @@ cdef class RandomState:
         resulting distribution is chi-square (see Notes).  This distribution
         is often used in hypothesis testing.
 
+        .. note::
+            New code should use ``default_rng().chisquare`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         df : float or array_like of floats
@@ -1769,6 +1864,10 @@ cdef class RandomState:
             When `df` <= 0 or when an inappropriate `size` (e.g. ``size=-1``)
             is given.
 
+        See also
+        --------
+        Generator.chisquare: which should be used for new code.
+
         Notes
         -----
         The variable obtained by summing the squares of `df` independent,
@@ -1798,7 +1897,6 @@ cdef class RandomState:
         --------
         >>> np.random.chisquare(2,4)
         array([ 1.89920014,  9.00867716,  3.13710533,  5.62318272]) # random
-
         """
         return cont(&legacy_chisquare, &self._aug_state, size, self.lock, 1,
                     df, 'df', CONS_POSITIVE,
@@ -1814,6 +1912,10 @@ cdef class RandomState:
         The noncentral :math:`\\chi^2` distribution is a generalization of
         the :math:`\\chi^2` distribution.
 
+        .. note::
+            New code should use ``default_rng().noncentral_chisquare`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         df : float or array_like of floats
@@ -1834,6 +1936,10 @@ cdef class RandomState:
         out : ndarray or scalar
             Drawn samples from the parameterized noncentral chi-square distribution.
 
+        See also
+        --------
+        Generator.noncentral_chisquare: which should be used for new code.
+
         Notes
         -----
         The probability density function for the noncentral Chi-square
@@ -1892,6 +1998,10 @@ cdef class RandomState:
 
         Also known as the Lorentz distribution.
 
+        .. note::
+            New code should use ``default_rng().standard_cauchy`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         size : int or tuple of ints, optional
@@ -1904,6 +2014,10 @@ cdef class RandomState:
         samples : ndarray or scalar
             The drawn samples.
 
+        See also
+        --------
+        Generator.standard_cauchy: which should be used for new code.
+
         Notes
         -----
         The probability density function for the full Cauchy distribution is
@@ -1960,6 +2074,10 @@ cdef class RandomState:
         large, the result resembles that of the standard normal
         distribution (`standard_normal`).
 
+        .. note::
+            New code should use ``default_rng().standard_t`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         df : float or array_like of floats
@@ -1975,6 +2093,10 @@ cdef class RandomState:
         out : ndarray or scalar
             Drawn samples from the parameterized standard Student's t distribution.
 
+        See also
+        --------
+        Generator.standard_t: which should be used for new code.
+
         Notes
         -----
         The probability density function for the t distribution is
@@ -2057,6 +2179,10 @@ cdef class RandomState:
         circle.  It may be thought of as the circular analogue of the normal
         distribution.
 
+        .. note::
+            New code should use ``default_rng().vonmises`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         mu : float or array_like of floats
@@ -2078,6 +2204,7 @@ cdef class RandomState:
         --------
         scipy.stats.vonmises : probability density function, distribution, or
             cumulative density function, etc.
+        Generator.vonmises: which should be used for new code.
 
         Notes
         -----
@@ -2150,6 +2277,10 @@ cdef class RandomState:
         20 percent of the range, while the other 20 percent fill the
         remaining 80 percent of the range.
 
+        .. note::
+            New code should use ``default_rng().pareto`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         a : float or array_like of floats
@@ -2171,6 +2302,7 @@ cdef class RandomState:
             cumulative density function, etc.
         scipy.stats.genpareto : probability density function, distribution or
             cumulative density function, etc.
+        Generator.pareto: which should be used for new code.
 
         Notes
         -----
@@ -2239,6 +2371,10 @@ cdef class RandomState:
         The more common 2-parameter Weibull, including a scale parameter
         :math:`\\lambda` is just :math:`X = \\lambda(-ln(U))^{1/a}`.
 
+        .. note::
+            New code should use ``default_rng().weibull`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         a : float or array_like of floats
@@ -2260,6 +2396,7 @@ cdef class RandomState:
         scipy.stats.weibull_min
         scipy.stats.genextreme
         gumbel
+        Generator.weibull: which should be used for new code.
 
         Notes
         -----
@@ -2330,6 +2467,10 @@ cdef class RandomState:
 
         Also known as the power function distribution.
 
+        .. note::
+            New code should use ``default_rng().power`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         a : float or array_like of floats
@@ -2350,6 +2491,10 @@ cdef class RandomState:
         ValueError
             If a < 1.
 
+        See also
+        --------
+        Generator.power: which should be used for new code.
+
         Notes
         -----
         The probability density function is
@@ -2433,6 +2578,10 @@ cdef class RandomState:
         difference between two independent, identically distributed exponential
         random variables.
 
+        .. note::
+            New code should use ``default_rng().laplace`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         loc : float or array_like of floats, optional
@@ -2451,6 +2600,10 @@ cdef class RandomState:
         out : ndarray or scalar
             Drawn samples from the parameterized Laplace distribution.
 
+        See also
+        --------
+        Generator.laplace: which should be used for new code.
+
         Notes
         -----
         It has the probability density function
@@ -2516,6 +2669,10 @@ cdef class RandomState:
         scale.  For more information on the Gumbel distribution, see
         Notes and References below.
 
+        .. note::
+            New code should use ``default_rng().gumbel`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         loc : float or array_like of floats, optional
@@ -2540,6 +2697,7 @@ cdef class RandomState:
         scipy.stats.gumbel_r
         scipy.stats.genextreme
         weibull
+        Generator.gumbel: which should be used for new code.
 
         Notes
         -----
@@ -2633,6 +2791,10 @@ cdef class RandomState:
         Samples are drawn from a logistic distribution with specified
         parameters, loc (location or mean, also median), and scale (>0).
 
+        .. note::
+            New code should use ``default_rng().logistic`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         loc : float or array_like of floats, optional
@@ -2655,6 +2817,7 @@ cdef class RandomState:
         --------
         scipy.stats.logistic : probability density function, distribution or
             cumulative density function, etc.
+        Generator.logistic: which should be used for new code.
 
         Notes
         -----
@@ -2715,6 +2878,10 @@ cdef class RandomState:
         deviation are not the values for the distribution itself, but of the
         underlying normal distribution it is derived from.
 
+        .. note::
+            New code should use ``default_rng().lognormal`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         mean : float or array_like of floats, optional
@@ -2737,6 +2904,7 @@ cdef class RandomState:
         --------
         scipy.stats.lognorm : probability density function, distribution,
             cumulative density function, etc.
+        Generator.lognormal: which should be used for new code.
 
         Notes
         -----
@@ -2823,6 +2991,10 @@ cdef class RandomState:
         The :math:`\\chi` and Weibull distributions are generalizations of the
         Rayleigh.
 
+        .. note::
+            New code should use ``default_rng().rayleigh`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         scale : float or array_like of floats, optional
@@ -2838,6 +3010,10 @@ cdef class RandomState:
         out : ndarray or scalar
             Drawn samples from the parameterized Rayleigh distribution.
 
+        See also
+        --------
+        Generator.rayleigh: which should be used for new code.
+
         Notes
         -----
         The probability density function for the Rayleigh distribution is
@@ -2897,6 +3073,10 @@ cdef class RandomState:
         because there is an inverse relationship between the time to cover a
         unit distance and distance covered in unit time.
 
+        .. note::
+            New code should use ``default_rng().wald`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         mean : float or array_like of floats
@@ -2914,6 +3094,10 @@ cdef class RandomState:
         out : ndarray or scalar
             Drawn samples from the parameterized Wald distribution.
 
+        See also
+        --------
+        Generator.wald: which should be used for new code.
+
         Notes
         -----
         The probability density function for the Wald distribution is
@@ -2962,6 +3146,10 @@ cdef class RandomState:
         limit right. Unlike the other distributions, these parameters
         directly define the shape of the pdf.
 
+        .. note::
+            New code should use ``default_rng().triangular`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         left : float or array_like of floats
@@ -2983,6 +3171,10 @@ cdef class RandomState:
         out : ndarray or scalar
             Drawn samples from the parameterized triangular distribution.
 
+        See also
+        --------
+        Generator.triangular: which should be used for new code.
+
         Notes
         -----
         The probability density function for the triangular distribution is
@@ -3061,6 +3253,10 @@ cdef class RandomState:
         n an integer >= 0 and p is in the interval [0,1]. (n may be
         input as a float, but it is truncated to an integer in use)
 
+        .. note::
+            New code should use ``default_rng().binomial`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         n : int or array_like of ints
@@ -3084,6 +3280,7 @@ cdef class RandomState:
         --------
         scipy.stats.binom : probability density function, distribution or
             cumulative density function, etc.
+        Generator.binomial: which should be used for new code.
 
         Notes
         -----
@@ -3206,6 +3403,10 @@ cdef class RandomState:
         parameters, `n` successes and `p` probability of success where `n`
         is > 0 and `p` is in the interval [0, 1].
 
+        .. note::
+            New code should use ``default_rng().negative_binomial`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         n : float or array_like of floats
@@ -3225,6 +3426,10 @@ cdef class RandomState:
             where each sample is equal to N, the number of failures that
             occurred before a total of n successes was reached.
 
+        See also
+        --------
+        Generator.negative_binomial: which should be used for new code.
+
         Notes
         -----
         The probability mass function of the negative binomial distribution is
@@ -3283,6 +3488,10 @@ cdef class RandomState:
         The Poisson distribution is the limit of the binomial distribution
         for large N.
 
+        .. note::
+            New code should use ``default_rng().poisson`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         lam : float or array_like of floats
@@ -3299,6 +3508,10 @@ cdef class RandomState:
         out : ndarray or scalar
             Drawn samples from the parameterized Poisson distribution.
 
+        See also
+        --------
+        Generator.poisson: which should be used for new code.
+
         Notes
         -----
         The Poisson distribution
@@ -3361,6 +3574,10 @@ cdef class RandomState:
         frequency of an item is inversely proportional to its rank in a
         frequency table.
 
+        .. note::
+            New code should use ``default_rng().zipf`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         a : float or array_like of floats
@@ -3380,6 +3597,7 @@ cdef class RandomState:
         --------
         scipy.stats.zipf : probability density function, distribution, or
             cumulative density function, etc.
+        Generator.zipf: which should be used for new code.
 
         Notes
         -----
@@ -3446,6 +3664,10 @@ cdef class RandomState:
 
         where `p` is the probability of success of an individual trial.
 
+        .. note::
+            New code should use ``default_rng().geometric`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         p : float or array_like of floats
@@ -3461,6 +3683,10 @@ cdef class RandomState:
         out : ndarray or scalar
             Drawn samples from the parameterized geometric distribution.
 
+        See also
+        --------
+        Generator.geometric: which should be used for new code.
+
         Examples
         --------
         Draw ten thousand values from the geometric distribution,
@@ -3492,6 +3718,10 @@ cdef class RandomState:
         a bad selection), and `nsample` (number of items sampled, which is less
         than or equal to the sum ``ngood + nbad``).
 
+        .. note::
+            New code should use ``default_rng().hypergeometric`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         ngood : int or array_like of ints
@@ -3519,6 +3749,7 @@ cdef class RandomState:
         --------
         scipy.stats.hypergeom : probability density function, distribution or
             cumulative density function, etc.
+        Generator.hypergeometric: which should be used for new code.
 
         Notes
         -----
@@ -3618,6 +3849,10 @@ cdef class RandomState:
         Samples are drawn from a log series distribution with specified
         shape parameter, 0 < ``p`` < 1.
 
+        .. note::
+            New code should use ``default_rng().logseries`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         p : float or array_like of floats
@@ -3637,6 +3872,7 @@ cdef class RandomState:
         --------
         scipy.stats.logser : probability density function, distribution or
             cumulative density function, etc.
+        Generator.logseries: which should be used for new code.
 
         Notes
         -----
@@ -3706,6 +3942,10 @@ cdef class RandomState:
         (average or "center") and variance (standard deviation, or "width,"
         squared) of the one-dimensional normal distribution.
 
+        .. note::
+            New code should use ``default_rng().multivariate_normal`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         mean : 1-D array_like, of length N
@@ -3733,6 +3973,10 @@ cdef class RandomState:
             In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
             value drawn from the distribution.
 
+        See also
+        --------
+        Generator.multivariate_normal: which should be used for new code.
+
         Notes
         -----
         The mean is a coordinate in N-dimensional space, which represents the
@@ -3872,6 +4116,10 @@ cdef class RandomState:
         ``X_i = [X_0, X_1, ..., X_p]``, represent the number of times the
         outcome was ``i``.
 
+        .. note::
+            New code should use ``default_rng().multinomial`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         n : int
@@ -3895,6 +4143,10 @@ cdef class RandomState:
             In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
             value drawn from the distribution.
 
+        See also
+        --------
+        Generator.multinomial: which should be used for new code.
+
         Examples
         --------
         Throw a dice 20 times:
@@ -3982,6 +4234,10 @@ cdef class RandomState:
         is a conjugate prior of a multinomial distribution in Bayesian
         inference.
 
+        .. note::
+            New code should use ``default_rng().dirichlet`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         alpha : array
@@ -4002,6 +4258,10 @@ cdef class RandomState:
         ValueError
             If any value in alpha is less than or equal to zero
 
+        See also
+        --------
+        Generator.dirichlet: which should be used for new code.
+
         Notes
         -----
         The Dirichlet distribution is a distribution over vectors
@@ -4119,6 +4379,10 @@ cdef class RandomState:
         multi-dimensional array. The order of sub-arrays is changed but
         their contents remains the same.
 
+        .. note::
+            New code should use ``default_rng().shuffle`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         x : array_like
@@ -4128,6 +4392,10 @@ cdef class RandomState:
         -------
         None
 
+        See also
+        --------
+        Generator.shuffle: which should be used for new code.
+
         Examples
         --------
         >>> arr = np.arange(10)
@@ -4206,6 +4474,10 @@ cdef class RandomState:
         If `x` is a multi-dimensional array, it is only shuffled along its
         first index.
 
+        .. note::
+            New code should use ``default_rng().permutation`` (see
+            `random-quick-start`) instead.
+
         Parameters
         ----------
         x : int or array_like
@@ -4218,6 +4490,9 @@ cdef class RandomState:
         out : ndarray
             Permuted sequence or array range.
 
+        See also
+        --------
+        Generator.permutation: which should be used for new code.
 
         Examples
         --------
diff --git a/numpy/random/setup.py b/numpy/random/setup.py
index 776a018bc..64e1b5b92 100644
--- a/numpy/random/setup.py
+++ b/numpy/random/setup.py
@@ -125,6 +125,7 @@ def configuration(parent_package='', top_path=None):
                          depends=['mtrand.pyx'],
                          define_macros=defs + LEGACY_DEFS,
                          )
+    config.add_data_files('__init__.pxd')
     return config