address review comments

Author: ndgrigorian

docs/source/how_to.rst

@@ -4,7 +4,7 @@ How-to Guides
 How to save and resume long computation
 ---------------------------------------
 
-:class:`RandomState` is pickleable. Pickling allows to save and restore
+:class:`MKLRandomState` is pickleable. Pickling allows to save and restore
 the internal state of the pseudo-random number generators.
 
 .. code-block:: python
@@ -14,7 +14,7 @@ the internal state of the pseudo-random number generators.
         import mkl_random
         import pickle
 
-        rs = mkl_random.RandomState(seed=777, brng="r250")
+        rs = mkl_random.MKLRandomState(seed=777, brng="r250")
         draw = rs.standard_normal(size=1357913)
 
         # pickle random state
@@ -45,7 +45,7 @@ from such family, initialized equally, produce streams of randomness statistical
 indistinguishable from independent.
 
 .. py:method:: skipahead(nskips)
-    :canonical: mkl_random.RandomState.skipahead
+    :canonical: mkl_random.MKLRandomState.skipahead
 
     Advance the state of the generator using skip-ahead method, or raise :code:`ValueError`
     exception if not supported.
@@ -63,7 +63,7 @@ indistinguishable from independent.
     independence breaks down.
 
 .. py:method:: leapfrog(k, nstreams)
-    :canonical: mkl_random.RandomState.leapfrog
+    :canonical: mkl_random.MKLRandomState.leapfrog
 
     Initialize the state of the generator using leap-frog method, or raise :code:`ValueError`
     exception if not supported.
@@ -85,3 +85,81 @@ indistinguishable from independent.
 randomness stasistically indistunguishable from independent. To use such families in parallel computation, assign
 difference family generators to different parallel workers and sample those assigned generators in each parallel worker.
 Please refer to "examples/" folder in the `GitHub repo <https://github.com/IntelPython/mkl_random>`_ for more details.
+
+
+Using :mod:`mkl_random` as a drop-in replacement for `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_
+-----------------------------------------------------------------
+
+The :mod:`mkl_random.interfaces.numpy_random` module is aligned to the legacy
+portion of the `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_ legacy API.
+You can import it in place of `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_
+without changing the rest of your code:
+
+.. code-block:: python
+    :caption: Drop-in replacement for numpy.random
+
+        from mkl_random.interfaces import numpy_random as rng
+
+        rng.seed(1234)
+        x = rng.standard_normal(size=100)
+        y = rng.uniform(0, 1, size=100)
+
+See :ref:`interfaces` for a full list of available functions.
+
+.. note::
+    While the API is the same, :mod:`mkl_random.interfaces.numpy_random` is **not** seed-compatible
+    with `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_. Given the same seed,
+    the two modules will produce different sequences. There also may be differences in some edge cases, such as
+    behavior of functions when given specific inputs.
+
+
+How to patch `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_ with :mod:`mkl_random`
+-------------------------------------------------------------
+
+Existing code that calls `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_
+directly can be patched to use :mod:`mkl_random.interfaces.numpy_random` at runtime.
+
+The recommended approach is to use the :class:`mkl_random.mkl_random` context manager:
+
+.. code-block:: python
+    :caption: Temporarily patch numpy.random using context manager
+
+        import numpy as np
+        import mkl_random
+
+        with mkl_random.mkl_random():
+            x = np.random.standard_normal(100)   # uses mkl_random
+            y = np.random.uniform(0, 1, size=100) # uses mkl_random
+
+:mod:`mkl_random` also exposes the explicit patching functions:
+
+.. code-block:: python
+    :caption: Patch numpy.random for the duration of a script
+
+        import mkl_random
+        mkl_random.patch_numpy_random() # subsequent numpy.random calls use mkl_random
+
+        import numpy as np
+        data = np.random.normal(0, 1, size=100)
+
+.. note::
+    The patching functions are provided for users' convenience, but they are not recommended
+    for new code. It is instead recommended to use :mod:`mkl_random` directly for new code.
+    For existing code where patching may be desirable, it is also suggested to prefer the
+    context manager, as it scopes the patch to blocks and thus, prevents user error of
+    forgetting to restore the original state, calling the patch multiple times, or
+    creating undefined behavior when patching in a multi-threaded program.
+
+You can also use :class:`mkl_random.mkl_random` as a decorator:
+
+.. code-block:: python
+    :caption: Patch numpy.random as a decorator
+
+        import numpy as np
+        import mkl_random
+
+        @mkl_random.mkl_random()
+        def get_data():
+            return np.random.standard_normal(100)
+
+See :ref:`patching` for details.

docs/source/reference/index.rst

@@ -28,14 +28,13 @@ Drop-in interfaces
 
 The :mod:`mkl_random.interfaces` submodule provides drop-in replacements for standard random modules:
 
-* :ref:`mkl_random.interfaces.numpy_random <numpy_random_interface>` - a drop-in replacement for the legacy :mod:`numpy.random` module
+* :ref:`mkl_random.interfaces.numpy_random <numpy_random_interface>` - a drop-in replacement for the legacy `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_ module
 
 
 Patching
 --------
 
-:mod:`mkl_random` can :ref:`patch numpy.random <patching>` so that existing code calling :mod:`numpy.random`
-functions can use :mod:`mkl_random` implementations.
+:mod:`mkl_random` can :ref:`patch numpy.random <patching>` so that existing code calling `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_ functions can use :mod:`mkl_random` implementations.
 
 .. toctree::
     :hidden:

docs/source/reference/interfaces.rst

@@ -14,13 +14,13 @@ NumPy interface --- :mod:`mkl_random.interfaces.numpy_random`
 -------------------------------------------------------------
 
 :mod:`mkl_random.interfaces.numpy_random` is a drop-in replacement for the legacy portion of
-:mod:`numpy.random`.
+`numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_.
 
 .. note::
     While the API is the same, :mod:`mkl_random.interfaces.numpy_random` is **not** seed-compatible
-    with :mod:`numpy.random`. Given the same seed, the two modules will produce different sequences.
-    The output of `get_state` and accepted input to `set_state` may also differ. It is not
-    recommended to provide the output of `get_state` from one module to `set_state` of the other.
+    with `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_. Given the same seed, the two modules
+    will produce different sequences. The output of :func:`get_state` and accepted input to :func:`set_state` may also differ.
+    It is not recommended to provide the output of :func:`get_state` from one module to :func:`set_state` of the other.
     There also may be differences in some edge cases, such as behavior of functions when given specific inputs.
 
 

docs/source/reference/patching.rst

@@ -1,10 +1,10 @@
 .. _patching:
 
-Patching :mod:`numpy.random`
+Patching `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_
 ============================
 
-:mod:`mkl_random` can temporarily replace functions and classes in :mod:`numpy.random` with
-:mod:`mkl_random`implementations from the :ref:`numpy interface <numpy_random_interface>`.
+:mod:`mkl_random` can temporarily replace functions and classes in `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_ with
+:mod:`mkl_random` implementations from the :ref:`numpy interface <numpy_random_interface>`.
 
 
 Functions

docs/source/tutorials.rst

@@ -39,23 +39,31 @@ The :mod:`mkl_random` is also distributed as part of `Intel® Distribution for P
 First steps
 -----------
 
-The :mod:`mkl_random` package has followed the design of :class:`numpy.random` package to
-make :mod:`mkl_random` easy to use for those already familiar with the :mod:`numpy.random` module.
+The :mod:`mkl_random` package has followed the design of `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_
+package to make :mod:`mkl_random` easy to use for those already familiar with the
+`numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_ module.
 
 .. note::
     Since the first release of :mod:`mkl_random`, NumPy introduced new classes :class:`numpy.random.Generator` and
     :class:`numpy.random.BitGenerator`, while also retaining :class:`numpy.random.RandomState` for backwards
     compatibility. :mod:`mkl_random`, at present, does not provide classes mirroring :class:`Generator` or
     :class:`BitGenerators`.
 
-The state of pseudo-random number generator is stored in :class:`mkl_random.RandomState` class,
+.. tip::
+    If you want a drop-in replacement for the `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_ legacy interface,
+    see :ref:`interfaces`. While it is recommended users rewrite code to use :mod:`mkl_random` or :mod:`<|mkl_random.interfaces.numpy_random|>`
+    directly, :mod:`mkl_random` provides tools to patch `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_ so that
+    existing code transparently uses the MKL-backed implementations in `numpy.random <https://numpy.org/doc/stable/reference/random/legacy.html>`_.
+    See :ref:`patching` for details.
+
+The state of pseudo-random number generator is stored in :class:`mkl_random.MKLRandomState` class,
 so using :mod:`mkl_random` begins with creating an instance of this class:
 
 .. code-block:: python
     :caption: Construct random number generator
 
         import mkl_random
-        rs = mkl_random.RandomState(seed=1234)
+        rs = mkl_random.MKLRandomState(seed=1234)
 
 Sampling from difference probability distribution is done by calling the class methods on the constructed instance:
 
@@ -75,7 +83,7 @@ Here is an example of estimating value of :math:`\pi` by using Monte-Carlo metho
         import numpy as np
         import mkl_random
 
-        rs = mkl_random.RandomState(seed=1234)
+        rs = mkl_random.MKLRandomState(seed=1234)
 
         sample_size = 10**8
         batch_size = 10**6
@@ -110,7 +118,7 @@ distributions of interest.
 `True random generator <https://en.wikipedia.org/wiki/Hardware_random_number_generator>`_ relies on
 laws of physics to provide those, leveraging dedicated hardware providing a source of entropy.
 
-`Psuedo-random generator <https://en.wikipedia.org/wiki/Pseudorandom_number_generator>`_ is an algorithm that outputs a sequence that emulates true randomness.
+`Pseudo-random generator <https://en.wikipedia.org/wiki/Pseudorandom_number_generator>`_ is an algorithm that outputs a sequence that emulates true randomness.
 The quality of emulation is tested statistically through a battery of test, e.g. `Diehard tests <https://en.wikipedia.org/wiki/Diehard_tests>`_.
 These tests check if various statistical tests can separate the pseudo-random sequence from a true random one.