Doc: Reorganize math module documentation (#126337)

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>

Doc/library/math.rst

@@ -27,36 +27,39 @@ noted otherwise, all return values are floats.
 
 
 ====================================================  ============================================
-**Number-theoretic and representation functions**
+**Number-theoretic functions**
+--------------------------------------------------------------------------------------------------
+:func:`comb(n, k) <comb>`                             Number of ways to choose *k* items from *n* items without repetition and without order
+:func:`factorial(n) <factorial>`                      *n* factorial
+:func:`gcd(*integers) <gcd>`                          Greatest common divisor of the integer arguments
+:func:`isqrt(n) <isqrt>`                              Integer square root of a nonnegative integer *n*
+:func:`lcm(*integers) <lcm>`                          Least common multiple of the integer arguments
+:func:`perm(n, k) <perm>`                             Number of ways to choose *k* items from *n* items without repetition and with order
+
+**Floating point arithmetic**
 --------------------------------------------------------------------------------------------------
 :func:`ceil(x) <ceil>`                                Ceiling of *x*, the smallest integer greater than or equal to *x*
-:func:`comb(n, k) <comb>`                             Number of ways to choose *k* items from *n* items without repetition and without order
-:func:`copysign(x, y) <copysign>`                     Magnitude (absolute value) of *x* with the sign of *y*
 :func:`fabs(x) <fabs>`                                Absolute value of *x*
-:func:`factorial(n) <factorial>`                      *n* factorial
+:func:`floor(x)  <floor>`                             Floor of *x*, the largest integer less than or equal to *x*
-:func:`floor (x)  <floor>`                            Floor of *x*, the largest integer less than or equal to *x*
 :func:`fma(x, y, z) <fma>`                            Fused multiply-add operation: ``(x * y) + z``
 :func:`fmod(x, y) <fmod>`                             Remainder of division ``x / y``
+:func:`modf(x) <modf>`                                Fractional and integer parts of *x*
+:func:`remainder(x, y) <remainder>`                   Remainder of *x* with respect to *y*
+:func:`trunc(x) <trunc>`                              Integer part of *x*
+
+**Floating point manipulation functions**
+--------------------------------------------------------------------------------------------------
+:func:`copysign(x, y) <copysign>`                     Magnitude (absolute value) of *x* with the sign of *y*
 :func:`frexp(x) <frexp>`                              Mantissa and exponent of *x*
-:func:`fsum(iterable) <fsum>`                         Sum of values in the input *iterable*
-:func:`gcd(*integers) <gcd>`                          Greatest common divisor of the integer arguments
 :func:`isclose(a, b, rel_tol, abs_tol) <isclose>`     Check if the values *a* and *b* are close to each other
 :func:`isfinite(x) <isfinite>`                        Check if *x* is neither an infinity nor a NaN
 :func:`isinf(x) <isinf>`                              Check if *x* is a positive or negative infinity
 :func:`isnan(x) <isnan>`                              Check if *x* is a NaN  (not a number)
-:func:`isqrt(n) <isqrt>`                              Integer square root of a nonnegative integer *n*
-:func:`lcm(*integers) <lcm>`                          Least common multiple of the integer arguments
 :func:`ldexp(x, i) <ldexp>`                           ``x * (2**i)``, inverse of function :func:`frexp`
-:func:`modf(x) <modf>`                                Fractional and integer parts of *x*
 :func:`nextafter(x, y, steps) <nextafter>`            Floating-point value *steps* steps after *x* towards *y*
-:func:`perm(n, k) <perm>`                             Number of ways to choose *k* items from *n* items without repetition and with order
-:func:`prod(iterable, start) <prod>`                  Product of elements in the input *iterable* with a *start* value
-:func:`remainder(x, y) <remainder>`                   Remainder of *x* with respect to *y*
-:func:`sumprod(p, q) <sumprod>`                       Sum of products from two iterables *p* and *q*
-:func:`trunc(x) <trunc>`                              Integer part of *x*
 :func:`ulp(x) <ulp>`                                  Value of the least significant bit of *x*
 
-**Power and logarithmic functions**
+**Power, exponential and logarithmic functions**
 --------------------------------------------------------------------------------------------------
 :func:`cbrt(x) <cbrt>`                                Cube root of *x*
 :func:`exp(x) <exp>`                                  *e* raised to the power *x*
@@ -69,6 +72,19 @@ noted otherwise, all return values are floats.
 :func:`pow(x, y) <math.pow>`                          *x* raised to the power *y*
 :func:`sqrt(x) <sqrt>`                                Square root of *x*
 
+**Summation and product functions**
+--------------------------------------------------------------------------------------------------
+:func:`dist(p, q) <dist>`                             Euclidean distance between two points *p* and *q* given as an iterable of coordinates
+:func:`fsum(iterable) <fsum>`                         Sum of values in the input *iterable*
+:func:`hypot(*coordinates) <hypot>`                   Euclidean norm of an iterable of coordinates
+:func:`prod(iterable, start) <prod>`                  Product of elements in the input *iterable* with a *start* value
+:func:`sumprod(p, q) <sumprod>`                       Sum of products from two iterables *p* and *q*
+
+**Angular conversion**
+--------------------------------------------------------------------------------------------------
+:func:`degrees(x) <degrees>`                          Convert angle *x* from radians to degrees
+:func:`radians(x) <radians>`                          Convert angle *x* from degrees to radians
+
 **Trigonometric functions**
 --------------------------------------------------------------------------------------------------
 :func:`acos(x) <acos>`                                Arc cosine of *x*
@@ -76,16 +92,9 @@ noted otherwise, all return values are floats.
 :func:`atan(x) <atan>`                                Arc tangent of *x*
 :func:`atan2(y, x) <atan2>`                           ``atan(y / x)``
 :func:`cos(x) <cos>`                                  Cosine of *x*
-:func:`dist(p, q) <dist>`                             Euclidean distance between two points *p* and *q* given as an iterable of coordinates
-:func:`hypot(*coordinates) <hypot>`                   Euclidean norm of an iterable of coordinates
 :func:`sin(x) <sin>`                                  Sine of *x*
 :func:`tan(x) <tan>`                                  Tangent of *x*
 
-**Angular conversion**
---------------------------------------------------------------------------------------------------
-:func:`degrees(x) <degrees>`                          Convert angle *x* from radians to degrees
-:func:`radians(x) <radians>`                          Convert angle *x* from degrees to radians
-
 **Hyperbolic functions**
 --------------------------------------------------------------------------------------------------
 :func:`acosh(x) <acosh>`                              Inverse hyperbolic cosine of *x*
@@ -112,15 +121,8 @@ noted otherwise, all return values are floats.
 ====================================================  ============================================
 
 
-Number-theoretic and representation functions
+Number-theoretic functions
----------------------------------------------
+--------------------------
-
-.. function:: ceil(x)
-
-   Return the ceiling of *x*, the smallest integer greater than or equal to *x*.
-   If *x* is not a float, delegates to :meth:`x.__ceil__ <object.__ceil__>`,
-   which should return an :class:`~numbers.Integral` value.
-
 
 .. function:: comb(n, k)
 
@@ -140,18 +142,6 @@ Number-theoretic and representation functions
    .. versionadded:: 3.8
 
 
-.. function:: copysign(x, y)
-
-   Return a float with the magnitude (absolute value) of *x* but the sign of
-   *y*.  On platforms that support signed zeros, ``copysign(1.0, -0.0)``
-   returns *-1.0*.
-
-
-.. function:: fabs(x)
-
-   Return the absolute value of *x*.
-
-
 .. function:: factorial(n)
 
    Return *n* factorial as an integer.  Raises :exc:`ValueError` if *n* is not integral or
@@ -161,6 +151,78 @@ Number-theoretic and representation functions
       Floats with integral values (like ``5.0``) are no longer accepted.
 
 
+.. function:: gcd(*integers)
+
+   Return the greatest common divisor of the specified integer arguments.
+   If any of the arguments is nonzero, then the returned value is the largest
+   positive integer that is a divisor of all arguments.  If all arguments
+   are zero, then the returned value is ``0``.  ``gcd()`` without arguments
+   returns ``0``.
+
+   .. versionadded:: 3.5
+
+   .. versionchanged:: 3.9
+      Added support for an arbitrary number of arguments. Formerly, only two
+      arguments were supported.
+
+
+.. function:: isqrt(n)
+
+   Return the integer square root of the nonnegative integer *n*. This is the
+   floor of the exact square root of *n*, or equivalently the greatest integer
+   *a* such that *a*\ ² |nbsp| ≤ |nbsp| *n*.
+
+   For some applications, it may be more convenient to have the least integer
+   *a* such that *n* |nbsp| ≤ |nbsp| *a*\ ², or in other words the ceiling of
+   the exact square root of *n*. For positive *n*, this can be computed using
+   ``a = 1 + isqrt(n - 1)``.
+
+   .. versionadded:: 3.8
+
+
+.. function:: lcm(*integers)
+
+   Return the least common multiple of the specified integer arguments.
+   If all arguments are nonzero, then the returned value is the smallest
+   positive integer that is a multiple of all arguments.  If any of the arguments
+   is zero, then the returned value is ``0``.  ``lcm()`` without arguments
+   returns ``1``.
+
+   .. versionadded:: 3.9
+
+
+.. function:: perm(n, k=None)
+
+   Return the number of ways to choose *k* items from *n* items
+   without repetition and with order.
+
+   Evaluates to ``n! / (n - k)!`` when ``k <= n`` and evaluates
+   to zero when ``k > n``.
+
+   If *k* is not specified or is ``None``, then *k* defaults to *n*
+   and the function returns ``n!``.
+
+   Raises :exc:`TypeError` if either of the arguments are not integers.
+   Raises :exc:`ValueError` if either of the arguments are negative.
+
+   .. versionadded:: 3.8
+
+
+Floating point arithmetic
+-------------------------
+
+.. function:: ceil(x)
+
+   Return the ceiling of *x*, the smallest integer greater than or equal to *x*.
+   If *x* is not a float, delegates to :meth:`x.__ceil__ <object.__ceil__>`,
+   which should return an :class:`~numbers.Integral` value.
+
+
+.. function:: fabs(x)
+
+   Return the absolute value of *x*.
+
+
 .. function:: floor(x)
 
    Return the floor of *x*, the largest integer less than or equal to *x*.  If
@@ -199,6 +261,64 @@ Number-theoretic and representation functions
    floats, while Python's ``x % y`` is preferred when working with integers.
 
 
+.. function:: modf(x)
+
+   Return the fractional and integer parts of *x*.  Both results carry the sign
+   of *x* and are floats.
+
+   Note that :func:`modf` has a different call/return pattern
+   than its C equivalents: it takes a single argument and return a pair of
+   values, rather than returning its second return value through an 'output
+   parameter' (there is no such thing in Python).
+
+
+.. function:: remainder(x, y)
+
+   Return the IEEE 754-style remainder of *x* with respect to *y*.  For
+   finite *x* and finite nonzero *y*, this is the difference ``x - n*y``,
+   where ``n`` is the closest integer to the exact value of the quotient ``x /
+   y``.  If ``x / y`` is exactly halfway between two consecutive integers, the
+   nearest *even* integer is used for ``n``.  The remainder ``r = remainder(x,
+   y)`` thus always satisfies ``abs(r) <= 0.5 * abs(y)``.
+
+   Special cases follow IEEE 754: in particular, ``remainder(x, math.inf)`` is
+   *x* for any finite *x*, and ``remainder(x, 0)`` and
+   ``remainder(math.inf, x)`` raise :exc:`ValueError` for any non-NaN *x*.
+   If the result of the remainder operation is zero, that zero will have
+   the same sign as *x*.
+
+   On platforms using IEEE 754 binary floating point, the result of this
+   operation is always exactly representable: no rounding error is introduced.
+
+   .. versionadded:: 3.7
+
+
+.. function:: trunc(x)
+
+   Return *x* with the fractional part
+   removed, leaving the integer part.  This rounds toward 0: ``trunc()`` is
+   equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil`
+   for negative *x*. If *x* is not a float, delegates to :meth:`x.__trunc__
+   <object.__trunc__>`, which should return an :class:`~numbers.Integral` value.
+
+
+For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all*
+floating-point numbers of sufficiently large magnitude are exact integers.
+Python floats typically carry no more than 53 bits of precision (the same as the
+platform C double type), in which case any float *x* with ``abs(x) >= 2**52``
+necessarily has no fractional bits.
+
+
+Floating point manipulation functions
+-------------------------------------
+
+.. function:: copysign(x, y)
+
+   Return a float with the magnitude (absolute value) of *x* but the sign of
+   *y*.  On platforms that support signed zeros, ``copysign(1.0, -0.0)``
+   returns *-1.0*.
+
+
 .. function:: frexp(x)
 
    Return the mantissa and exponent of *x* as the pair ``(m, e)``.  *m* is a float
@@ -206,37 +326,10 @@ Number-theoretic and representation functions
    returns ``(0.0, 0)``, otherwise ``0.5 <= abs(m) < 1``.  This is used to "pick
    apart" the internal representation of a float in a portable way.
 
-
+   Note that :func:`frexp` has a different call/return pattern
-.. function:: fsum(iterable)
+   than its C equivalents: it takes a single argument and return a pair of
-
+   values, rather than returning its second return value through an 'output
-   Return an accurate floating-point sum of values in the iterable.  Avoids
+   parameter' (there is no such thing in Python).
-   loss of precision by tracking multiple intermediate partial sums.
-
-   The algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
-   typical case where the rounding mode is half-even.  On some non-Windows
-   builds, the underlying C library uses extended precision addition and may
-   occasionally double-round an intermediate sum causing it to be off in its
-   least significant bit.
-
-   For further discussion and two alternative approaches, see the `ASPN cookbook
-   recipes for accurate floating-point summation
-   <https://code.activestate.com/recipes/393090-binary-floating-point-summation-accurate-to-full-p/>`_\.
-
-
-.. function:: gcd(*integers)
-
-   Return the greatest common divisor of the specified integer arguments.
-   If any of the arguments is nonzero, then the returned value is the largest
-   positive integer that is a divisor of all arguments.  If all arguments
-   are zero, then the returned value is ``0``.  ``gcd()`` without arguments
-   returns ``0``.
-
-   .. versionadded:: 3.5
-
-   .. versionchanged:: 3.9
-      Added support for an arbitrary number of arguments. Formerly, only two
-      arguments were supported.
-
 
 .. function:: isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)
 
@@ -291,43 +384,12 @@ Number-theoretic and representation functions
    Return ``True`` if *x* is a NaN (not a number), and ``False`` otherwise.
 
 
-.. function:: isqrt(n)
-
-   Return the integer square root of the nonnegative integer *n*. This is the
-   floor of the exact square root of *n*, or equivalently the greatest integer
-   *a* such that *a*\ ² |nbsp| ≤ |nbsp| *n*.
-
-   For some applications, it may be more convenient to have the least integer
-   *a* such that *n* |nbsp| ≤ |nbsp| *a*\ ², or in other words the ceiling of
-   the exact square root of *n*. For positive *n*, this can be computed using
-   ``a = 1 + isqrt(n - 1)``.
-
-   .. versionadded:: 3.8
-
-
-.. function:: lcm(*integers)
-
-   Return the least common multiple of the specified integer arguments.
-   If all arguments are nonzero, then the returned value is the smallest
-   positive integer that is a multiple of all arguments.  If any of the arguments
-   is zero, then the returned value is ``0``.  ``lcm()`` without arguments
-   returns ``1``.
-
-   .. versionadded:: 3.9
-
-
 .. function:: ldexp(x, i)
 
    Return ``x * (2**i)``.  This is essentially the inverse of function
    :func:`frexp`.
 
 
-.. function:: modf(x)
-
-   Return the fractional and integer parts of *x*.  Both results carry the sign
-   of *x* and are floats.
-
-
 .. function:: nextafter(x, y, steps=1)
 
    Return the floating-point value *steps* steps after *x* towards *y*.
@@ -348,79 +410,6 @@ Number-theoretic and representation functions
    .. versionchanged:: 3.12
       Added the *steps* argument.
 
-.. function:: perm(n, k=None)
-
-   Return the number of ways to choose *k* items from *n* items
-   without repetition and with order.
-
-   Evaluates to ``n! / (n - k)!`` when ``k <= n`` and evaluates
-   to zero when ``k > n``.
-
-   If *k* is not specified or is ``None``, then *k* defaults to *n*
-   and the function returns ``n!``.
-
-   Raises :exc:`TypeError` if either of the arguments are not integers.
-   Raises :exc:`ValueError` if either of the arguments are negative.
-
-   .. versionadded:: 3.8
-
-
-.. function:: prod(iterable, *, start=1)
-
-   Calculate the product of all the elements in the input *iterable*.
-   The default *start* value for the product is ``1``.
-
-   When the iterable is empty, return the start value.  This function is
-   intended specifically for use with numeric values and may reject
-   non-numeric types.
-
-   .. versionadded:: 3.8
-
-
-.. function:: remainder(x, y)
-
-   Return the IEEE 754-style remainder of *x* with respect to *y*.  For
-   finite *x* and finite nonzero *y*, this is the difference ``x - n*y``,
-   where ``n`` is the closest integer to the exact value of the quotient ``x /
-   y``.  If ``x / y`` is exactly halfway between two consecutive integers, the
-   nearest *even* integer is used for ``n``.  The remainder ``r = remainder(x,
-   y)`` thus always satisfies ``abs(r) <= 0.5 * abs(y)``.
-
-   Special cases follow IEEE 754: in particular, ``remainder(x, math.inf)`` is
-   *x* for any finite *x*, and ``remainder(x, 0)`` and
-   ``remainder(math.inf, x)`` raise :exc:`ValueError` for any non-NaN *x*.
-   If the result of the remainder operation is zero, that zero will have
-   the same sign as *x*.
-
-   On platforms using IEEE 754 binary floating point, the result of this
-   operation is always exactly representable: no rounding error is introduced.
-
-   .. versionadded:: 3.7
-
-
-.. function:: sumprod(p, q)
-
-   Return the sum of products of values from two iterables *p* and *q*.
-
-   Raises :exc:`ValueError` if the inputs do not have the same length.
-
-   Roughly equivalent to::
-
-       sum(map(operator.mul, p, q, strict=True))
-
-   For float and mixed int/float inputs, the intermediate products
-   and sums are computed with extended precision.
-
-   .. versionadded:: 3.12
-
-
-.. function:: trunc(x)
-
-   Return *x* with the fractional part
-   removed, leaving the integer part.  This rounds toward 0: ``trunc()`` is
-   equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil`
-   for negative *x*. If *x* is not a float, delegates to :meth:`x.__trunc__
-   <object.__trunc__>`, which should return an :class:`~numbers.Integral` value.
 
 .. function:: ulp(x)
 
@@ -447,20 +436,8 @@ Number-theoretic and representation functions
    .. versionadded:: 3.9
 
 
-Note that :func:`frexp` and :func:`modf` have a different call/return pattern
+Power, exponential and logarithmic functions
-than their C equivalents: they take a single argument and return a pair of
+--------------------------------------------
-values, rather than returning their second return value through an 'output
-parameter' (there is no such thing in Python).
-
-For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all*
-floating-point numbers of sufficiently large magnitude are exact integers.
-Python floats typically carry no more than 53 bits of precision (the same as the
-platform C double type), in which case any float *x* with ``abs(x) >= 2**52``
-necessarily has no fractional bits.
-
-
-Power and logarithmic functions
--------------------------------
 
 .. function:: cbrt(x)
 
@@ -557,6 +534,99 @@ Power and logarithmic functions
    Return the square root of *x*.
 
 
+Summation and product functions
+-------------------------------
+
+.. function:: dist(p, q)
+
+   Return the Euclidean distance between two points *p* and *q*, each
+   given as a sequence (or iterable) of coordinates.  The two points
+   must have the same dimension.
+
+   Roughly equivalent to::
+
+       sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))
+
+   .. versionadded:: 3.8
+
+
+.. function:: fsum(iterable)
+
+   Return an accurate floating-point sum of values in the iterable.  Avoids
+   loss of precision by tracking multiple intermediate partial sums.
+
+   The algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
+   typical case where the rounding mode is half-even.  On some non-Windows
+   builds, the underlying C library uses extended precision addition and may
+   occasionally double-round an intermediate sum causing it to be off in its
+   least significant bit.
+
+   For further discussion and two alternative approaches, see the `ASPN cookbook
+   recipes for accurate floating-point summation
+   <https://code.activestate.com/recipes/393090-binary-floating-point-summation-accurate-to-full-p/>`_\.
+
+
+.. function:: hypot(*coordinates)
+
+   Return the Euclidean norm, ``sqrt(sum(x**2 for x in coordinates))``.
+   This is the length of the vector from the origin to the point
+   given by the coordinates.
+
+   For a two dimensional point ``(x, y)``, this is equivalent to computing
+   the hypotenuse of a right triangle using the Pythagorean theorem,
+   ``sqrt(x*x + y*y)``.
+
+   .. versionchanged:: 3.8
+      Added support for n-dimensional points. Formerly, only the two
+      dimensional case was supported.
+
+   .. versionchanged:: 3.10
+      Improved the algorithm's accuracy so that the maximum error is
+      under 1 ulp (unit in the last place).  More typically, the result
+      is almost always correctly rounded to within 1/2 ulp.
+
+
+.. function:: prod(iterable, *, start=1)
+
+   Calculate the product of all the elements in the input *iterable*.
+   The default *start* value for the product is ``1``.
+
+   When the iterable is empty, return the start value.  This function is
+   intended specifically for use with numeric values and may reject
+   non-numeric types.
+
+   .. versionadded:: 3.8
+
+
+.. function:: sumprod(p, q)
+
+   Return the sum of products of values from two iterables *p* and *q*.
+
+   Raises :exc:`ValueError` if the inputs do not have the same length.
+
+   Roughly equivalent to::
+
+       sum(map(operator.mul, p, q, strict=True))
+
+   For float and mixed int/float inputs, the intermediate products
+   and sums are computed with extended precision.
+
+   .. versionadded:: 3.12
+
+
+Angular conversion
+------------------
+
+.. function:: degrees(x)
+
+   Convert angle *x* from radians to degrees.
+
+
+.. function:: radians(x)
+
+   Convert angle *x* from degrees to radians.
+
+
 Trigonometric functions
 -----------------------
 
@@ -593,39 +663,6 @@ Trigonometric functions
    Return the cosine of *x* radians.
 
 
-.. function:: dist(p, q)
-
-   Return the Euclidean distance between two points *p* and *q*, each
-   given as a sequence (or iterable) of coordinates.  The two points
-   must have the same dimension.
-
-   Roughly equivalent to::
-
-       sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))
-
-   .. versionadded:: 3.8
-
-
-.. function:: hypot(*coordinates)
-
-   Return the Euclidean norm, ``sqrt(sum(x**2 for x in coordinates))``.
-   This is the length of the vector from the origin to the point
-   given by the coordinates.
-
-   For a two dimensional point ``(x, y)``, this is equivalent to computing
-   the hypotenuse of a right triangle using the Pythagorean theorem,
-   ``sqrt(x*x + y*y)``.
-
-   .. versionchanged:: 3.8
-      Added support for n-dimensional points. Formerly, only the two
-      dimensional case was supported.
-
-   .. versionchanged:: 3.10
-      Improved the algorithm's accuracy so that the maximum error is
-      under 1 ulp (unit in the last place).  More typically, the result
-      is almost always correctly rounded to within 1/2 ulp.
-
-
 .. function:: sin(x)
 
    Return the sine of *x* radians.
@@ -636,19 +673,6 @@ Trigonometric functions
    Return the tangent of *x* radians.
 
 
-Angular conversion
-------------------
-
-.. function:: degrees(x)
-
-   Convert angle *x* from radians to degrees.
-
-
-.. function:: radians(x)
-
-   Convert angle *x* from degrees to radians.
-
-
 Hyperbolic functions
 --------------------