BUG: adjust docs and doctests for namespace transition

Author: mattip

doc/source/reference/randomgen/extending.rst

@@ -1,8 +1,10 @@
+.. currentmodule:: numpy.random.randomgen
+
 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.
 
@@ -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
@@ -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
 

doc/source/reference/randomgen/generator.rst

@@ -2,7 +2,7 @@
 
 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

doc/source/reference/randomgen/new-or-different.rst

@@ -1,41 +1,44 @@
 .. _new-or-different:
 
+.. currentmodule:: numpy.random.randomgen
+
 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.randomgen 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
 

numpy/random/dsfmt.pyx

@@ -102,8 +102,8 @@ cdef class DSFMT:
     generators should be initialized with the same seed to ensure that the
     segments come from the same sequence.
 
-    >>> from numpy.random.randomgen.entropy import random_entropy
-    >>> from numpy.random.randomgen import RandomGenerator, DSFMT
+    >>> from numpy.random.entropy import random_entropy
+    >>> from numpy.random import RandomGenerator, DSFMT
     >>> seed = random_entropy()
     >>> rs = [RandomGenerator(DSFMT(seed)) for _ in range(10)]
     # Advance rs[i] by i jumps