DOC: tighten up documentation, add a table of comparison

Author: mattip

doc/source/reference/random/brng/index.rst

@@ -1,3 +1,5 @@
+.. _brng:
+
 Basic Random Number Generators
 ------------------------------
 
@@ -12,8 +14,6 @@ access the functions provided, e.g., `numba <https://numba.pydata.org>`_.
 
 Stable RNGs
 ===========
-These RNGs will be included in future releases.
-
 
 .. toctree::
    :maxdepth: 1

doc/source/reference/random/index.rst

@@ -93,11 +93,11 @@ What's New or Different
 .. warning::
 
   The Box-Muller method used to produce NumPy's normals is no longer available
-  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.
-  Use the backward-compatible legacy generator, `~mtrand`, which fully
-  reproduces the sequence produced by pre-1.17.0.
+  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 bitwise backward compatible
+  streams, use `~.mtrand.RandomState`.
 
 * The normal, exponential and gamma generators use 256-step Ziggurat
   methods which are 2-10 times faster than NumPy's Box-Muller or inverse CDF
@@ -120,7 +120,6 @@ What's New or Different
   arbitrary interval by setting ``use_masked=True`` in
   `~RandomGenerator.randint`.
 
-
 See :ref:`new-or-different` for a complete list of improvements and
 differences.
 

doc/source/reference/random/legacy.rst

@@ -1,15 +1,17 @@
+.. _legacy:
+
 Legacy Random Generation
 ------------------------
-The :class:`~mtrand.RandomState` provides access to
+The `~mtrand.RandomState` 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:`~mtrand.RandomState` adds additional information
+`~mtrand.RandomState` adds 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:`~mtrand.RandomState.get_state`
+`~mtrand.RandomState.get_state`
 when accessing the state so that these extra values are saved.
 
 .. code-block:: python
@@ -46,6 +48,7 @@ Seeding and State
 
    ~RandomState.get_state
    ~RandomState.set_state
+   ~RandomState.seed
 
 Simple random data
 ==================

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

@@ -8,14 +8,37 @@ What's New or Different
 .. warning::
 
   The Box-Muller method used to produce NumPy's normals is no longer available
-  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.
-
+  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 bitwise backward compatible
+  streams, use `~.mtrand.RandomState`.
+
+Quick comparison of legacy `mtrand <legacy>`_ to the new `generator
+<RandomGenerator>`
+
+=================== =================== =============
+Feature             Older Equivalent    Notes
+------------------- ------------------- -------------
+`RandomGenerator`   `RandomState`       ``RandomGenerator`` requires a stream
+                                        source, called a RandomNumberGenerator
+                                        (RNG). A number of different basic
+                                        `RNGs <brng>`_ exist.  ``RandomState``
+                                        uses only the Box- Muller method.
+------------------- ------------------- -------------
+``np.random.gen.``  ``np.random.``      Access the next values in an already-
+``random_sample()`` ``random_sample()`` instaniated RNG, convert them to
+                                        ``float64`` in the interval ``[0.0.,``
+                                        `` 1.0)`` In addition to the ``size``
+                                        kwarg, now supports ``dtype='d'`` or
+                                        ``dtype='f'``, and an ``out`` kwarg to
+                                        fill a user-supplied array.
+
+                                        Many other distributions are also
+                                        supported.
+=================== =================== =============
+
+And in more detail:
 
 * `~.entropy.random_entropy` provides access to the system
   source of randomness that is used in cryptographic applications (e.g.,