BUG: __dealloc__ can be called without __init__ in some error modes

skip doctests that require scipy
move original mtrand module to _mtrand
adjust documentation for namespace change

25 files changed, 146 insertions, 140 deletions

diff --git a/doc/source/reference/randomgen/brng/dsfmt.rst b/doc/source/reference/random/brng/dsfmt.rst
index f9de48d61..a47586a50 100644
--- a/doc/source/reference/randomgen/brng/dsfmt.rst
+++ b/doc/source/reference/random/brng/dsfmt.rst
@@ -1,9 +1,9 @@
 Double SIMD Mersenne Twister (dSFMT) 
 ------------------------------------
 
-.. module:: numpy.random.randomgen.dsfmt
+.. module:: numpy.random.dsfmt
 
-.. currentmodule:: numpy.random.randomgen.dsfmt
+.. currentmodule:: numpy.random.dsfmt
 
 
 .. autoclass:: DSFMT
diff --git a/doc/source/reference/randomgen/brng/index.rst b/doc/source/reference/random/brng/index.rst
index aceecc792..5241f9856 100644
--- a/doc/source/reference/randomgen/brng/index.rst
+++ b/doc/source/reference/random/brng/index.rst
@@ -1,7 +1,9 @@
 Basic Random Number Generators
 ------------------------------
 
-The random values produced by :class:`~randomgen.generator.RandomGenerator` 
+.. currentmodule:: numpy.random
+
+The random values produced by :class:`~RandomGenerator` 
 are produced by a basic RNG.  These basic RNGs do not directly provide
 random numbers and only contains methods used for seeding, getting or
 setting the state, jumping or advancing the state, and for accessing 
diff --git a/doc/source/reference/randomgen/brng/mt19937.rst b/doc/source/reference/random/brng/mt19937.rst
index 7739e16ce..1bd3597c8 100644
--- a/doc/source/reference/randomgen/brng/mt19937.rst
+++ b/doc/source/reference/random/brng/mt19937.rst
@@ -1,9 +1,9 @@
 Mersenne Twister (MT19937) 
 --------------------------
 
-.. module:: numpy.random.randomgen.mt19937
+.. module:: numpy.random.mt19937
 
-.. currentmodule:: numpy.random.randomgen.mt19937
+.. currentmodule:: numpy.random.mt19937
 
 .. autoclass:: MT19937
 	:exclude-members:
diff --git a/doc/source/reference/randomgen/brng/pcg32.rst b/doc/source/reference/random/brng/pcg32.rst
index aaf3929e8..f079f5a8c 100644
--- a/doc/source/reference/randomgen/brng/pcg32.rst
+++ b/doc/source/reference/random/brng/pcg32.rst
@@ -1,9 +1,9 @@
 Parallel Congruent Generator (32-bit, PCG32)
 --------------------------------------------
 
-.. module:: numpy.random.randomgen.pcg32
+.. module:: numpy.random.pcg32
 
-.. currentmodule:: numpy.random.randomgen.pcg32
+.. currentmodule:: numpy.random.pcg32
 
 .. autoclass:: PCG32
 	:exclude-members:
diff --git a/doc/source/reference/randomgen/brng/pcg64.rst b/doc/source/reference/random/brng/pcg64.rst
index 94e73e491..93f026fcb 100644
--- a/doc/source/reference/randomgen/brng/pcg64.rst
+++ b/doc/source/reference/random/brng/pcg64.rst
@@ -1,9 +1,9 @@
 Parallel Congruent Generator (64-bit, PCG64)
 --------------------------------------------
 
-.. module:: numpy.random.randomgen.pcg64
+.. module:: numpy.random.pcg64
 
-.. currentmodule:: numpy.random.randomgen.pcg64
+.. currentmodule:: numpy.random.pcg64
 
 .. autoclass:: PCG64
 	:exclude-members:
diff --git a/doc/source/reference/randomgen/brng/philox.rst b/doc/source/reference/random/brng/philox.rst
index 091c4d3e0..c1e047c54 100644
--- a/doc/source/reference/randomgen/brng/philox.rst
+++ b/doc/source/reference/random/brng/philox.rst
@@ -1,9 +1,9 @@
 Philox Counter-based RNG
 ------------------------
 
-.. module:: numpy.random.randomgen.philox
+.. module:: numpy.random.philox
 
-.. currentmodule:: numpy.random.randomgen.philox
+.. currentmodule:: numpy.random.philox
 
 .. autoclass:: Philox
 	:exclude-members:
diff --git a/doc/source/reference/randomgen/brng/threefry.rst b/doc/source/reference/random/brng/threefry.rst
index 4f5c56bae..eefe16ea0 100644
--- a/doc/source/reference/randomgen/brng/threefry.rst
+++ b/doc/source/reference/random/brng/threefry.rst
@@ -1,9 +1,9 @@
 ThreeFry Counter-based RNG
 --------------------------
 
-.. module:: numpy.random.randomgen.threefry
+.. module:: numpy.random.threefry
 
-.. currentmodule:: numpy.random.randomgen.threefry
+.. currentmodule:: numpy.random.threefry
 
 .. autoclass:: ThreeFry
 	:exclude-members:
diff --git a/doc/source/reference/randomgen/brng/threefry32.rst b/doc/source/reference/random/brng/threefry32.rst
index bd85db4a7..f0d3dc281 100644
--- a/doc/source/reference/randomgen/brng/threefry32.rst
+++ b/doc/source/reference/random/brng/threefry32.rst
@@ -1,9 +1,9 @@
 ThreeFry32 Counter-based RNG
 ----------------------------
 
-.. module:: numpy.random.randomgen.threefry32
+.. module:: numpy.random.threefry32
 
-.. currentmodule:: numpy.random.randomgen.threefry32
+.. currentmodule:: numpy.random.threefry32
 
 .. autoclass:: ThreeFry32
 	:exclude-members:
diff --git a/doc/source/reference/randomgen/brng/xoroshiro128.rst b/doc/source/reference/random/brng/xoroshiro128.rst
index 6796c4457..590552236 100644
--- a/doc/source/reference/randomgen/brng/xoroshiro128.rst
+++ b/doc/source/reference/random/brng/xoroshiro128.rst
@@ -1,9 +1,9 @@
 Xoroshiro128+
 -------------
 
-.. module:: numpy.random.randomgen.xoroshiro128
+.. module:: numpy.random.xoroshiro128
 
-.. currentmodule:: numpy.random.randomgen.xoroshiro128
+.. currentmodule:: numpy.random.xoroshiro128
 
 .. autoclass:: Xoroshiro128
 	:exclude-members:
diff --git a/doc/source/reference/randomgen/brng/xorshift1024.rst b/doc/source/reference/random/brng/xorshift1024.rst
index 64df7e050..24ed3df04 100644
--- a/doc/source/reference/randomgen/brng/xorshift1024.rst
+++ b/doc/source/reference/random/brng/xorshift1024.rst
@@ -1,9 +1,9 @@
 Xorshift1024*φ
 --------------
 
-.. module:: numpy.random.randomgen.xorshift1024
+.. module:: numpy.random.xorshift1024
 
-.. currentmodule:: numpy.random.randomgen.xorshift1024
+.. currentmodule:: numpy.random.xorshift1024
 
 .. autoclass:: Xorshift1024
 	:exclude-members:
diff --git a/doc/source/reference/randomgen/brng/xoshiro256starstar.rst b/doc/source/reference/random/brng/xoshiro256starstar.rst
index 7603e6f1b..85c445666 100644
--- a/doc/source/reference/randomgen/brng/xoshiro256starstar.rst
+++ b/doc/source/reference/random/brng/xoshiro256starstar.rst
@@ -1,9 +1,9 @@
 Xoshiro256**
 ------------
 
-.. module:: numpy.random.randomgen.xoshiro256starstar
+.. module:: numpy.random.xoshiro256starstar
 
-.. currentmodule:: numpy.random.randomgen.xoshiro256starstar
+.. currentmodule:: numpy.random.xoshiro256starstar
 
 .. autoclass:: Xoshiro256StarStar
 	:exclude-members:
diff --git a/doc/source/reference/randomgen/brng/xoshiro512starstar.rst b/doc/source/reference/random/brng/xoshiro512starstar.rst
index 64f95f750..0c008d56e 100644
--- a/doc/source/reference/randomgen/brng/xoshiro512starstar.rst
+++ b/doc/source/reference/random/brng/xoshiro512starstar.rst
@@ -1,9 +1,9 @@
 Xoshiro512**
 ------------
 
-.. module:: numpy.random.randomgen.xoshiro512starstar
+.. module:: numpy.random.xoshiro512starstar
 
-.. currentmodule:: numpy.random.randomgen.xoshiro512starstar
+.. currentmodule:: numpy.random.xoshiro512starstar
 
 .. autoclass:: Xoshiro512StarStar
 	:exclude-members:
diff --git a/doc/source/reference/randomgen/change-log.rst b/doc/source/reference/random/change-log.rst
index f791c8f54..af3c266ef 100644
--- a/doc/source/reference/randomgen/change-log.rst
+++ b/doc/source/reference/random/change-log.rst
@@ -1,5 +1,5 @@
-Change Log
-----------
+Change Log for the original bashtage/randomgen repo
+---------------------------------------------------
 v1.16.1
 =======
 - Synchronized with upstream changes.
@@ -7,12 +7,12 @@ v1.16.1
 
 v1.16.0
 =======
-- Fixed a bug that affected :class:`~randomgen.dsfmt.DSFMT` when calling
-  :func:`~randomgen.dsfmt.DSFMT.jump` or :func:`~randomgen.dsfmt.DSFMT.seed`
+- Fixed a bug that affected ``randomgen.dsfmt.DSFMT`` when calling
+  ``~randomgen.dsfmt.DSFMT.jump`` or ``randomgen.dsfmt.DSFMT.seed``
   that failed to reset the buffer.  This resulted in upto 381 values from the
   previous state being used before the buffer was refilled at the new state.
-- Fixed bugs in :class:`~randomgen.xoshiro512starstar.Xoshiro512StarStar`
-  and :class:`~randomgen.xorshift1024.Xorshift1024` where the fallback
+- Fixed bugs in ``randomgen.xoshiro512starstar.Xoshiro512StarStar``
+  and ``randomgen.xorshift1024.Xorshift1024`` where the fallback
   entropy initialization used too few bytes. This bug is unlikely to be
   encountered since this path is only encountered if the system random
   number generator fails.
diff --git a/doc/source/reference/randomgen/entropy.rst b/doc/source/reference/random/entropy.rst
index 6814edfbe..0664da6f9 100644
--- a/doc/source/reference/randomgen/entropy.rst
+++ b/doc/source/reference/random/entropy.rst
@@ -1,6 +1,6 @@
 System Entropy
 ==============
 
-.. module:: numpy.random.randomgen.entropy
+.. module:: numpy.random.entropy
 
 .. autofunction:: random_entropy
diff --git a/doc/source/reference/randomgen/extending.rst b/doc/source/reference/random/extending.rst
index 64f2ddcc1..f76e3984f 100644
--- a/doc/source/reference/randomgen/extending.rst
+++ b/doc/source/reference/random/extending.rst
@@ -1,8 +1,10 @@
+.. currentmodule:: numpy.random
+
 Extending
 ---------
 The basic RNGs have been designed to be extendable using standard tools for
 high-performance Python -- numba and Cython.
-The :class:`randomgen.generator.RandomGenerator` object can also be used with
+The `~RandomGenerator` object can also be used with
 user-provided basic RNGs as long as these export a small set of required
 functions.
 
@@ -17,7 +19,7 @@ provided by ``ctypes.next_double``.
 
 .. code-block:: python
 
-    from randomgen import Xoroshiro128
+    from numpy.random import Xoroshiro128
     import numpy as np
     import numba as nb
 
@@ -65,7 +67,7 @@ Cython
 ======
 
 Cython can be used to unpack the ``PyCapsule`` provided by a basic RNG.
-This example uses :class:`~randomgen.xoroshiro128.Xoroshiro128` and
+This example uses `~xoroshiro128.Xoroshiro128` and
 ``random_gauss_zig``, the Ziggurat-based generator for normals, to fill an
 array.  The usual caveats for writing high-performance code using Cython --
 removing bounds checks and wrap around, providing array alignment information
@@ -77,9 +79,9 @@ removing bounds checks and wrap around, providing array alignment information
     cimport numpy as np
     cimport cython
     from cpython.pycapsule cimport PyCapsule_IsValid, PyCapsule_GetPointer
-    from randomgen.common cimport *
-    from randomgen.distributions cimport random_gauss_zig
-    from randomgen.xoroshiro128 import Xoroshiro128
+    from numpy.random.common cimport *
+    from numpy.random.distributions cimport random_gauss_zig
+    from numpy.random.xoroshiro128 import Xoroshiro128
 
 
    @cython.boundscheck(False)
@@ -137,7 +139,7 @@ examples folder.
 
 New Basic RNGs
 ==============
-:class:`~randomgen.generator.RandomGenerator` can be used with other
+`~RandomGenerator` can be used with other
 user-provided basic RNGs.  The simplest way to write a new basic RNG is to
 examine the pyx file of one of the existing basic RNGs. The key structure
 that must be provided is the ``capsule`` which contains a ``PyCapsule`` to a
@@ -158,7 +160,7 @@ used by the basic RNG.  The next three are function pointers which return the
 next 64- and 32-bit unsigned integers, the next random double and the next
 raw value.  This final function is used for testing and so can be set to
 the next 64-bit unsigned integer function if not needed. Functions inside
-:class:`~randomgen.generator.RandomGenerator` use this structure as in
+``RandomGenerator`` use this structure as in
 
 .. code-block:: c
 
diff --git a/doc/source/reference/randomgen/generator.rst b/doc/source/reference/random/generator.rst
index 54325f4d3..9d248732f 100644
--- a/doc/source/reference/randomgen/generator.rst
+++ b/doc/source/reference/random/generator.rst
@@ -1,8 +1,8 @@
-.. currentmodule:: numpy.random.randomgen
+.. currentmodule:: numpy.random
 
 Random Generator
 ----------------
-The :class:`~RandomGenerator` provides access to
+The `~RandomGenerator` provides access to
 a wide range of distributions, and served as a replacement for
 :class:`~numpy.random.RandomState`.  The main difference between
 the two is that ``RandomGenerator`` relies on an additional basic RNG to
diff --git a/doc/source/reference/randomgen/index.rst b/doc/source/reference/random/index.rst
index a8b6f1c9b..1cbf5c685 100644
--- a/doc/source/reference/randomgen/index.rst
+++ b/doc/source/reference/random/index.rst
@@ -1,49 +1,46 @@
-.. current_module numpy.random.randomgen
+.. currentmodule:: numpy.random
 
-numpy.random.randomgen
-======================
+numpy.random
+============
 
-This package modernizes the legacy
-`~numpy.random.RandomState` object and allows changing the core random
-number generator (RNG). The `~numpy.random.randomgen.RandomGenerator` can
-be initialized with a number of different RNGs, and exposes many different
-probability distributions.
+A `~RandomGenerator` can
+be initialized with a number of different Random Number Generators (RNG)s, and
+exposes many different probability distributions.
 
 
 Quick Start
 -----------
 
-By default, `generator.RandomGenerator` uses normals provided by
+By default, `RandomGenerator` uses normals provided by
 `xoroshiro128.Xoroshiro128` which will be faster than the legacy methods in
-`numpy.random`
+`numpy.random.RandomState`
 
 .. code-block:: python
 
-  # As replacement for numpy.random
-  import randomgen.generator as random
+  # As replacement for numpy.random.RandomState
+  from numpy import random
   random.standard_normal()
 
-`numpy.random.randomgen.RandomGenerator` can also be used as a replacement for
-`~numpy.random.RandomState`, although the random values are generated by
-`~numpyrandom.randomgen.xoroshiro128.Xoroshiro128`. Since ``randomgen``
-separates the `~numpy.random.randomgen.RandomGenerator` from the RNG, it is not
-possible to directly seed the generator.
+`RandomGenerator` can be used as a direct replacement for
+`~RandomState`, although the random values are generated by
+`~xoroshiro128.Xoroshiro128`. The `RandomGenerator` holds an instance of a RNG.
+It is accessable as ``gen.brng``.
 
 .. code-block:: python
 
   # As replacement for RandomState()
-  from randomgen import RandomGenerator
+  from numpy.random import RandomGenerator
   rg = RandomGenerator()
   rg.standard_normal()
 
 
-Seeds can be passed to any of the basic RNGs. Here `numpy.random.randomgen.
-mt19937.MT19937` is used and the `~numpy.random.randomgen.RandomGenerator` is
-accessed via the attribute `~numpy.random.randomgen.mt19937.MT19937.generator`.
+Seeds can be passed to any of the basic RNGs. Here `mt19937.MT19937` is used
+and the ``RandomGenerator`` is accessed via the attribute `mt19937.MT19937.
+generator`.
 
 .. code-block:: python
 
-  from randomgen import MT19937
+  from numpy.random import MT19937
   rg = MT19937(12345).generator
   rg.standard_normal()
 
@@ -59,20 +56,20 @@ underlying RNG state and provides functions to produce random doubles and
 random unsigned 32- and 64-bit values. The basic random generator also handles
 all seeding since this varies when using alternative basic RNGs.
 
-The `random generator <~numpy.random.randomgen.RandomGenerator>` takes the
+The `random generator <~RandomGenerator>` takes the
 basic RNG-provided functions and transforms them into more useful
 distributions, e.g., simulated normal random values. This structure allows
 alternative basic RNGs to be used without code duplication.
 
-The `~numpy.random.randomgen.RandomGenerator` is the user-facing object
-that is nearly identical to :class:`~numpy.random.RandomState`. The canonical
-method to initialize a generator passes a basic RNG -- `~numpy.random.
-randomgen.mt19937.MT19937`, the underlying RNG in NumPy  -- as the
-sole argument. Note that the basic RNG must be instantized.
+The ``RandomGenerator`` is the user-facing object
+that is nearly identical to :class:`~.RandomState`. The canonical
+method to initialize a generator passes a basic RNG -- `~mt19937.MT19937`, the
+underlying RNG in NumPy  -- as the sole argument. Note that the basic RNG must
+be instantized.
 
 .. code-block:: python
 
-  from randomgen import RandomGenerator, MT19937
+  from numpy.random import RandomGenerator, MT19937
   rg = RandomGenerator(MT19937())
   rg.random_sample()
 
@@ -83,9 +80,8 @@ Seed information is directly passed to the basic RNG.
   rg = RandomGenerator(MT19937(12345))
   rg.random_sample()
 
-A shorthand method is also available which uses the `~numpy.random.randomgen.
-mt19937.MT19937.generator` property from a basic RNG to access an embedded
-random generator.
+A shorthand method is also available which uses the `~mt19937.MT19937.
+generator` property from a basic RNG to access an embedded random generator.
 
 .. code-block:: python
 
@@ -97,11 +93,10 @@ What's New or Different
 .. warning::
 
   The Box-Muller method used to produce NumPy's normals is no longer available
-  in `~numpy.random.randomgen.RandomGenerator`.  It is not possible to
-  reproduce the random values using `~numpy.random.randomgen.RandomGenerator`
-  for the normal distribution or any other distribution that
-  relies on the normal such as the gamma or student's t. If you require
-  backward compatibility, a legacy generator, `~numpy.random.randomgen.legacy.
+  in `~RandomGenerator`.  It is not possible to reproduce the random values
+  using ``RandomGenerator`` for the normal distribution or any other
+  distribution that relies on the normal such as the gamma or student's t.
+  If you require backward compatibility, a legacy generator, `~legacy.
   LegacyGenerator`, has been created which can fully reproduce the sequence
   produced by NumPy.
 
@@ -113,18 +108,18 @@ What's New or Different
   select distributions
 * Optional ``out`` argument that allows existing arrays to be filled for
   select distributions
-* `~numpy.random.randomgen.entropy.random_entropy` provides access to the system
+* `~entropy.random_entropy` provides access to the system
   source of randomness that is used in cryptographic applications (e.g.,
   ``/dev/urandom`` on Unix).
 * All basic random generators functions can produce doubles, uint64s and
-  uint32s via CTypes (`~numpy.random.randomgen.xoroshiro128.Xoroshiro128.ctypes`)
-  and CFFI (:meth:`~numpy.random.randomgen.xoroshiro128.Xoroshiro128.cffi`).
+  uint32s via CTypes (`~xoroshiro128.Xoroshiro128.ctypes`)
+  and CFFI (:meth:`~xoroshiro128.Xoroshiro128.cffi`).
   This allows these basic RNGs to be used in numba.
 * The basic random number generators can be used in downstream projects via
   :ref:`Cython <randomgen_cython>`.
 * Support for Lemire’s method [Lemire]_ of generating uniform integers on an
   arbitrary interval by setting ``use_masked=True`` in
-  `~umpy.random.randomgen.generator.RandomGenerator.randint`.
+  `~RandomGenerator.randint`.
 
 
 See :ref:`new-or-different` for a complete list of improvements and
@@ -146,7 +141,7 @@ generators, 'in addition' to the standard PRNG in NumPy.  The included PRNGs are
 
 * MT19937 - The standard NumPy generator.  Produces identical results to NumPy
   using the same seed/state. Adds a
-  `~numpy.random.randomgen.mt19937.MT19937.jump` function that advances the
+  `~mt19937.MT19937.jump` function that advances the
   generator as-if ``2**128`` draws have been made.  See `numpy.random`.
 * dSFMT - SSE2 enabled versions of the MT19937 generator.  Theoretically
   the same, but with a different state and so it is not possible to produce a
@@ -155,24 +150,24 @@ generators, 'in addition' to the standard PRNG in NumPy.  The included PRNGs are
 * XoroShiro128+ - Improved version of XorShift128+ with better performance
   and statistical quality. Like the XorShift generators, it can be jumped
   to produce multiple streams in parallel applications. See
-  `~numpy.random.randomgen.xoroshiro128.Xoroshiro128.jump` for details.
+  `~xoroshiro128.Xoroshiro128.jump` for details.
   More information about this PRNG is available at the
   `xorshift, xoroshiro and xoshiro authors' page`_.
 * XorShift1024*φ - Fast fast generator based on the XSadd
   generator. Supports ``jump`` and so can be used in
   parallel applications. See the documentation for
-  `~numpy.random.randomgen.xorshift1024.Xorshift1024.jump` for details. More
+  `~xorshift1024.Xorshift1024.jump` for details. More
   information about these PRNGs is available at the
   `xorshift, xoroshiro and xoshiro authors' page`_.
 * Xorshiro256** and Xorshiro512** - The most recently introduced XOR,
   shift, and rotate generator. Supports ``jump`` and so can be used in
   parallel applications. See the documentation for
-  `~numpy.random.randomgen.xoshiro256starstar.Xoshirt256StarStar.jump` for
+  `~xoshiro256starstar.Xoshirt256StarStar.jump` for
   details. More information about these PRNGs is available at the
   `xorshift, xoroshiro and xoshiro authors' page`_.
 * PCG-64 - Fast generator that support many parallel streams and
   can be advanced by an arbitrary amount. See the documentation for
-  `~numpy.random.randomgen.pcg64.PCG64.advance`. PCG-64 has a period of
+  `~pcg64.PCG64.advance`. PCG-64 has a period of
   :math:`2^{128}`. See the `PCG author's page`_ for more details about
   this class of PRNG.
 * ThreeFry and Philox - counter-based generators capable of being advanced an
diff --git a/doc/source/reference/randomgen/legacy.rst b/doc/source/reference/random/legacy.rst
index 7e87f871c..b9bfabcc7 100644
--- a/doc/source/reference/randomgen/legacy.rst
+++ b/doc/source/reference/random/legacy.rst
@@ -1,15 +1,15 @@
 Legacy Random Generation
 ------------------------
-The :class:`~randomgen.legacy.LegacyGenerator` provides access to 
-some legacy generators.  These all depend on Box-Muller normals or
+The :class:`~legacy.LegacyGenerator` provides access to 
+legacy generators.  These all depend on Box-Muller normals or
 inverse CDF exponentials or gammas. This class should only be used 
 if it is essential to have randoms that are identical to what
 would have been produced by NumPy. 
 
-:class:`~randomgen.legacy.LegacyGenerator` add additional information
+:class:`~legacy.LegacyGenerator` add additional information
 to the state which is required when using Box-Muller normals since these
 are produced in pairs. It is important to use 
-:attr:`~randomgen.legacy.LegacyGenerator.state` 
+:attr:`~legacy.LegacyGenerator.state` 
 when accessing the state so that these extra values are saved. 
 
 .. warning::
@@ -27,8 +27,8 @@ when accessing the state so that these extra values are saved.
 
 .. code-block:: python
   
-   from randomgen import RandomGenerator, MT19937
-   from randomgen.legacy import LegacyGenerator
+   from numpy.random import MT19937
+   from numpy.random.legacy import LegacyGenerator
    from numpy.random import RandomState
       # Use same seed
    rs = RandomState(12345)
@@ -47,7 +47,7 @@ when accessing the state so that these extra values are saved.
    lg.standard_exponential()
    
 
-.. currentmodule:: numpy.random.randomgen.legacy
+.. currentmodule:: numpy.random.legacy
 
 .. autoclass:: LegacyGenerator
 	:exclude-members:
diff --git a/doc/source/reference/randomgen/multithreading.rst b/doc/source/reference/random/multithreading.rst
index 6efbcdbe7..f7762b73a 100644
--- a/doc/source/reference/randomgen/multithreading.rst
+++ b/doc/source/reference/random/multithreading.rst
@@ -16,7 +16,7 @@ that the same seed will produce the same outputs.
 
 .. code-block:: ipython
 
-    from randomgen import Xorshift1024
+    from numpy.random import Xorshift1024
     import multiprocessing
     import concurrent.futures
     import numpy as np
diff --git a/doc/source/reference/randomgen/new-or-different.rst b/doc/source/reference/random/new-or-different.rst
index 089efd6fb..7ddebb5b2 100644
--- a/doc/source/reference/randomgen/new-or-different.rst
+++ b/doc/source/reference/random/new-or-different.rst
@@ -1,41 +1,44 @@
 .. _new-or-different:
 
+.. currentmodule:: numpy.random
+
 What's New or Different
 -----------------------
 
 .. warning::
 
   The Box-Muller method used to produce NumPy's normals is no longer available
-  in :class:`~randomgen.generator.RandomGenerator`.  It is not possible to 
-  reproduce the random values using :class:`~randomgen.generator.RandomGenerator` 
-  for the normal distribution or any other distribution that relies on the
-  normal such as the gamma or student's t. If you require backward compatibility, a 
-  legacy generator, :class:`~randomgen.legacy.LegacyGenerator`, has been created
-  which can fully reproduce the sequence produced by NumPy.
+  in `~.RandomGenerator`.  It is not possible to
+  reproduce the exact random values using ``RandomGenerator`` for the normal
+  distribution or any other distribution that relies on the normal such as the
+  `numpy.random.gamma` or `numpy.random.standard_t`. If you require backward
+  compatibility, a legacy generator, `~.legacy.
+  LegacyGenerator`, has been created which can fully reproduce the exact byte
+  sequence produced by legacy code.
 
 
-* :func:`~randomgen.entropy.random_entropy` provides access to the system
+* `~.entropy.random_entropy` provides access to the system
   source of randomness that is used in cryptographic applications (e.g.,
   ``/dev/urandom`` on Unix).
 * Simulate from the complex normal distribution
-  (:meth:`~randomgen.generator.RandomGenerator.complex_normal`)
+  (`~.RandomGenerator.complex_normal`)
 * The normal, exponential and gamma generators use 256-step Ziggurat
   methods which are 2-10 times faster than NumPy's default implementation in
-  :meth:`~randomgen.generator.RandomGenerator.standard_normal`,
-  :meth:`~randomgen.generator.RandomGenerator.standard_exponential` or
-  :meth:`~randomgen.generator.RandomGenerator.standard_gamma`.
+  `~.RandomGenerator.standard_normal`,
+  `~.RandomGenerator.standard_exponential` or
+  `~.RandomGenerator.standard_gamma`.
 * The Box-Muller used to produce NumPy's normals is no longer available.
 * All basic random generators functions to produce doubles, uint64s and
-  uint32s via CTypes (:meth:`~randomgen.xoroshiro128.Xoroshiro128.ctypes`)
-  and CFFI (:meth:`~randomgen.xoroshiro128.Xoroshiro128.cffi`).  This allows
-  these basic RNGs to be used in numba.
+  uint32s via CTypes (`~.xoroshiro128.Xoroshiro128.
+  ctypes`) and CFFI (`~.xoroshiro128.Xoroshiro128.cffi`).
+  This allows these basic RNGs to be used in numba.
 * The basic random number generators can be used in downstream projects via
   Cython.
 
 
 .. ipython:: python
 
-  from numpy.random.randomgen import Xoroshiro128
+  from  numpy.random import Xoroshiro128
   import numpy.random
   rg = Xoroshiro128().generator
   %timeit rg.standard_normal(100000)
@@ -55,12 +58,12 @@ What's New or Different
   to produce either single or double prevision uniform random variables for
   select distributions
 
-  * Uniforms (:meth:`~randomgen.generator.RandomGenerator.random_sample` and
-    :meth:`~randomgen.generator.RandomGenerator.rand`)
-  * Normals (:meth:`~randomgen.generator.RandomGenerator.standard_normal` and
-    :meth:`~randomgen.generator.RandomGenerator.randn`)
-  * Standard Gammas (:meth:`~randomgen.generator.RandomGenerator.standard_gamma`)
-  * Standard Exponentials (:meth:`~randomgen.generator.RandomGenerator.standard_exponential`)
+  * Uniforms (`~.RandomGenerator.random_sample` and
+    `~.RandomGenerator.rand`)
+  * Normals (`~.RandomGenerator.standard_normal` and
+    `~.RandomGenerator.randn`)
+  * Standard Gammas (`~.RandomGenerator.standard_gamma`)
+  * Standard Exponentials (`~.RandomGenerator.standard_exponential`)
 
 .. ipython:: python
 
@@ -72,10 +75,10 @@ What's New or Different
 * Optional ``out`` argument that allows existing arrays to be filled for
   select distributions
 
-  * Uniforms (:meth:`~randomgen.generator.RandomGenerator.random_sample`)
-  * Normals (:meth:`~randomgen.generator.RandomGenerator.standard_normal`)
-  * Standard Gammas (:meth:`~randomgen.generator.RandomGenerator.standard_gamma`)
-  * Standard Exponentials (:meth:`~randomgen.generator.RandomGenerator.standard_exponential`)
+  * Uniforms (`~.RandomGenerator.random_sample`)
+  * Normals (`~.RandomGenerator.standard_normal`)
+  * Standard Gammas (`~.RandomGenerator.standard_gamma`)
+  * Standard Exponentials (`~.RandomGenerator.standard_exponential`)
 
   This allows multithreading to fill large arrays in chunks using suitable
   PRNGs in parallel.
@@ -90,7 +93,7 @@ What's New or Different
 
 * Support for Lemire’s method of generating uniform integers on an
   arbitrary interval by setting ``use_masked=True`` in
-  (:meth:`~randomgen.generator.RandomGenerator.randint`).
+  (`~.RandomGenerator.randint`).
 
 .. ipython:: python
 
diff --git a/doc/source/reference/randomgen/parallel.rst b/doc/source/reference/random/parallel.rst
index df6f58d75..41e47039d 100644
--- a/doc/source/reference/randomgen/parallel.rst
+++ b/doc/source/reference/random/parallel.rst
@@ -7,18 +7,20 @@ or distributed).
 
 .. _independent-streams:
 
+.. currentmodule:: numpy.random
+
 Independent Streams
 -------------------
 
-:class:`~randomgen.pcg64.PCG64`, :class:`~randomgen.threefry.ThreeFry`
-and :class:`~randomgen.philox.Philox` support independent streams.  This
+:class:`~pcg64.PCG64`, :class:`~threefry.ThreeFry`
+and :class:`~philox.Philox` support independent streams.  This
 example shows how many streams can be created by passing in different index
 values in the second input while using the same seed in the first.
 
 .. code-block:: python
 
-  from randomgen.entropy import random_entropy
-  from randomgen import PCG64
+  from numpy.random.entropy import random_entropy
+  from numpy.random import PCG64
 
   entropy = random_entropy(4)
   # 128-bit number as a seed
@@ -26,14 +28,14 @@ values in the second input while using the same seed in the first.
   streams = [PCG64(seed, stream) for stream in range(10)]
 
 
-:class:`~randomgen.philox.Philox` and :class:`~randomgen.threefry.ThreeFry` are
+:class:`~philox.Philox` and :class:`~threefry.ThreeFry` are
 counter-based RNGs which use a counter and key.  Different keys can be used
 to produce independent streams.
 
 .. code-block:: python
 
   import numpy as np
-  from randomgen import ThreeFry
+  from numpy.random import ThreeFry
 
   key = random_entropy(8)
   key = key.view(np.uint64)
@@ -81,8 +83,8 @@ overlap.
 
 .. code-block:: python
 
-  from randomgen.entropy import random_entropy
-  from randomgen import Xorshift1024
+  from numpy.random.entropy import random_entropy
+  from numpy.random import Xorshift1024
 
   entropy = random_entropy(2).astype(np.uint64)
   # 64-bit number as a seed
@@ -97,8 +99,8 @@ overlap.
 Advance
 *******
 ``advance`` can be used to jump the state an arbitrary number of steps, and so
-is a more general approach than ``jump``.  :class:`~randomgen.pcg64.PCG64`,
-:class:`~randomgen.threefry.ThreeFry` and :class:`~randomgen.philox.Philox`
+is a more general approach than ``jump``.  :class:`~pcg64.PCG64`,
+:class:`~threefry.ThreeFry` and :class:`~philox.Philox`
 support ``advance``, and since these also support independent
 streams, it is not usually necessary to use ``advance``.
 
@@ -119,12 +121,12 @@ This occurs for two reasons:
 Advancing the PRNG state resets any pre-computed random numbers. This is
 required to ensure exact reproducibility.
 
-This example uses ``advance`` to advance a :class:`~randomgen.pcg64.PCG64`
+This example uses ``advance`` to advance a :class:`~pcg64.PCG64`
 generator 2 ** 127 steps to set a sequence of random number generators.
 
 .. code-block:: python
 
-   from randomgen import PCG64
+   from numpy.random import PCG64
    brng = PCG64()
    brng_copy = PCG64()
    brng_copy.state = brng.state
diff --git a/doc/source/reference/randomgen/performance.py b/doc/source/reference/random/performance.py
index 12cbbc5d3..12cbbc5d3 100644
--- a/doc/source/reference/randomgen/performance.py
+++ b/doc/source/reference/random/performance.py
diff --git a/doc/source/reference/randomgen/performance.rst b/doc/source/reference/random/performance.rst
index 2dfb32101..321d49454 100644
--- a/doc/source/reference/randomgen/performance.rst
+++ b/doc/source/reference/random/performance.rst
@@ -1,26 +1,28 @@
 Performance
 -----------
 
-.. py:module:: randomgen
+.. py:module:: numpy.random
+
+.. currentmodule:: numpy.random
 
 Recommendation
 **************
 The recommended generator for single use is
-:class:`~randomgen.xoroshiro128.Xoroshiro128`.  The recommended generator
+:class:`~xoroshiro128.Xoroshiro128`.  The recommended generator
 for use in large-scale parallel applications is
-:class:`~randomgen.xorshift1024.Xorshift1024`
+:class:`~xorshift1024.Xorshift1024`
 where the `jump` method is used to advance the state. For very large scale
 applications -- requiring 1,000+ independent streams,
-:class:`~randomgen.pcg64.PCG64` or :class:`~randomgen.threefry.ThreeFry` are
+:class:`~pcg64.PCG64` or :class:`~threefry.ThreeFry` are
 the best choices.
 
 Timings
 *******
 
 The timings below are the time in ms to produce 1,000,000 random values from a
-specific distribution.  :class:`~randomgen.xoroshiro128.Xoroshiro128` is the
-fastest, followed by :class:`~randomgen.xorshift1024.Xorshift1024` and
-:class:`~randomgen.pcg64.PCG64`.  The original :class:`~randomgen.mt19937.MT19937`
+specific distribution.  :class:`~xoroshiro128.Xoroshiro128` is the
+fastest, followed by :class:`~xorshift1024.Xorshift1024` and
+:class:`~pcg64.PCG64`.  The original :class:`~mt19937.MT19937`
 generator is much slower since it requires 2 32-bit values to equal the output
 of the faster generators.
 
diff --git a/doc/source/reference/randomgen/references.rst b/doc/source/reference/random/references.rst
index 0dc99868f..0dc99868f 100644
--- a/doc/source/reference/randomgen/references.rst
+++ b/doc/source/reference/random/references.rst
diff --git a/doc/source/reference/routines.rst b/doc/source/reference/routines.rst
index 0ed99cbda..e3fbc2be6 100644
--- a/doc/source/reference/routines.rst
+++ b/doc/source/reference/routines.rst
@@ -42,7 +42,7 @@ indentation.
    routines.padding
    routines.polynomials
    routines.random
-   randomgen/index
+   random/index
    routines.set
    routines.sort
    routines.statistics