DOC: Added bullet about axis kwarg to rng overview docs.

Modified the introductory/overview documentation for the random
module to highlight the addition of the `axis` kwarg to
methods like `shuffle` and `choice` for dealing with
multi-dimensional arrays.

Related to gh-16075

2 files changed, 14 insertions, 0 deletions

diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst
index bda9c4d96..79e6a285e 100644
--- a/doc/source/reference/random/index.rst
+++ b/doc/source/reference/random/index.rst
@@ -168,6 +168,9 @@ What's New or Different
   Python's `random.random`.
 * All BitGenerators in numpy use `SeedSequence` to convert seeds into
   initialized states.
+* The addition of an ``axis`` keyword argument to methods such as 
+  `Generator.choice` and `Generator.shuffle` improves support for 
+  sampling from and shuffling multi-dimensional arrays.
 
 See :ref:`new-or-different` for a complete list of improvements and
 differences from the traditional ``Randomstate``.
diff --git a/doc/source/reference/random/new-or-different.rst b/doc/source/reference/random/new-or-different.rst
index b3bddb443..4b9ba72a4 100644
--- a/doc/source/reference/random/new-or-different.rst
+++ b/doc/source/reference/random/new-or-different.rst
@@ -114,3 +114,14 @@ And in more detail:
   rg.random(out=existing[:2])
   print(existing)
 
+* Optional ``axis`` argument for methods like `~.Generator.choice` and
+  `~.Generator.shuffle` to control which axis an operation is performed
+  over for higher-dimensional arrays.
+
+.. ipython:: python
+
+  a = np.arange(12).reshape((3, 4))
+  a
+  rg.choice(a, axis=1, size=2)
+  rg.shuffle(a, axis=1)        # Shuffle in-place
+  a