Improve recipe readability (GH-22685) (GH-22686)

1 files changed, 37 insertions, 31 deletions

diff --git a/Doc/library/random.rst b/Doc/library/random.rst
index c43307c..d37fd9c 100644
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -253,6 +253,8 @@ Functions for sequences
       order so that the sample is reproducible.
 
 
+.. _real-valued-distributions:
+
 Real-valued distributions
 -------------------------
 
@@ -516,26 +518,42 @@ Simulation of arrival times and service deliveries for a multiserver queue::
     print(f'Mean wait: {mean(waits):.1f}.  Stdev wait: {stdev(waits):.1f}.')
     print(f'Median wait: {median(waits):.1f}.  Max wait: {max(waits):.1f}.')
 
+.. seealso::
+
+   `Statistics for Hackers <https://www.youtube.com/watch?v=Iq9DzN6mvYA>`_
+   a video tutorial by
+   `Jake Vanderplas <https://us.pycon.org/2016/speaker/profile/295/>`_
+   on statistical analysis using just a few fundamental concepts
+   including simulation, sampling, shuffling, and cross-validation.
+
+   `Economics Simulation
+   <http://nbviewer.jupyter.org/url/norvig.com/ipython/Economics.ipynb>`_
+   a simulation of a marketplace by
+   `Peter Norvig <http://norvig.com/bio.html>`_ that shows effective
+   use of many of the tools and distributions provided by this module
+   (gauss, uniform, sample, betavariate, choice, triangular, and randrange).
+
+   `A Concrete Introduction to Probability (using Python)
+   <http://nbviewer.jupyter.org/url/norvig.com/ipython/Probability.ipynb>`_
+   a tutorial by `Peter Norvig <http://norvig.com/bio.html>`_ covering
+   the basics of probability theory, how to write simulations, and
+   how to perform data analysis using Python.
+
+
 Recipes
 -------
 
 The default :func:`.random` returns multiples of 2⁻⁵³ in the range
-*0.0 ≤ x < 1.0*.  All such numbers are evenly spaced and exactly
+*0.0 ≤ x < 1.0*.  All such numbers are evenly spaced and are exactly
 representable as Python floats.  However, many floats in that interval
 are not possible selections.  For example, ``0.05954861408025609``
 isn't an integer multiple of 2⁻⁵³.
 
 The following recipe takes a different approach.  All floats in the
-interval are possible selections.  Conceptually it works by choosing
-from evenly spaced multiples of 2⁻¹⁰⁷⁴ and then rounding down to the
-nearest representable float.
-
-For efficiency, the actual mechanics involve calling
-:func:`~math.ldexp` to construct a representable float.  The mantissa
-comes from a uniform distribution of integers in the range *2⁵² ≤
-mantissa < 2⁵³*.  The exponent comes from a geometric distribution
-where exponents smaller than *-53* occur half as often as the next
-larger exponent.
+interval are possible selections.  The mantissa comes from a uniform
+distribution of integers in the range *2⁵² ≤ mantissa < 2⁵³*.  The
+exponent comes from a geometric distribution where exponents smaller
+than *-53* occur half as often as the next larger exponent.
 
 ::
 
@@ -553,7 +571,8 @@ larger exponent.
                 exponent += x.bit_length() - 32
             return ldexp(mantissa, exponent)
 
-All of the real valued distributions will use the new method::
+All :ref:`real valued distributions <real-valued-distributions>`
+in the class will use the new method::
 
     >>> fr = FullRandom()
     >>> fr.random()
@@ -561,27 +580,14 @@ All of the real valued distributions will use the new method::
     >>> fr.expovariate(0.25)
     8.87925541791544
 
+The recipe is conceptually equivalent to an algorithm that chooses from
+all the multiples of 2⁻¹⁰⁷⁴ in the range *0.0 ≤ x < 1.0*.  All such
+numbers are evenly spaced, but most have to be rounded down to the
+nearest representable Python float.  (The value 2⁻¹⁰⁷⁴ is the smallest
+positive unnormalized float and is equal to ``math.ulp(0.0)``.)
 
-.. seealso::
-
-   `Statistics for Hackers <https://www.youtube.com/watch?v=Iq9DzN6mvYA>`_
-   a video tutorial by
-   `Jake Vanderplas <https://us.pycon.org/2016/speaker/profile/295/>`_
-   on statistical analysis using just a few fundamental concepts
-   including simulation, sampling, shuffling, and cross-validation.
-
-   `Economics Simulation
-   <http://nbviewer.jupyter.org/url/norvig.com/ipython/Economics.ipynb>`_
-   a simulation of a marketplace by
-   `Peter Norvig <http://norvig.com/bio.html>`_ that shows effective
-   use of many of the tools and distributions provided by this module
-   (gauss, uniform, sample, betavariate, choice, triangular, and randrange).
 
-   `A Concrete Introduction to Probability (using Python)
-   <http://nbviewer.jupyter.org/url/norvig.com/ipython/Probability.ipynb>`_
-   a tutorial by `Peter Norvig <http://norvig.com/bio.html>`_ covering
-   the basics of probability theory, how to write simulations, and
-   how to perform data analysis using Python.
+.. seealso::
 
    `Generating Pseudo-random Floating-Point Values
    <https://allendowney.com/research/rand/downey07randfloat.pdf>`_ a