Doc: Add a single table as summary to math documentation (GH-125810)

* Summary for math module with separate tables * Forgot remainder description * Single table * data instead of func * Add arguments in the table * Fix inconsistencies in pow documentation * Remove full stops from the table Co-authored-by: Hugo van Kemenade <[email protected]> * Fix math.pow link * Fix spacing --------- (cherry picked from commit 74cf596) Co-authored-by: Joseph Martinot-Lagarde <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]>
python · willingc · Nov 1, 2024 · Nov 1, 2024 · Nov 1, 2024 · e79e7210d1fe267d69819ea720b9f390e18ac5e8
commit e79e7210d1fe267d69819ea720b9f390e18ac5e8
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
@@ -26,6 +26,92 @@ The following functions are provided by this module.  Except when explicitly
 noted otherwise, all return values are floats.
 
 
+====================================================  ============================================
+**Number-theoretic and representation functions**
+--------------------------------------------------------------------------------------------------
+: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:`fma(x, y, z) <fma>`                            Fused multiply-add operation: ``(x * y) + z``
+:func:`fmod(x, y) <fmod>`                             Remainder of division ``x / 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**
+--------------------------------------------------------------------------------------------------
+:func:`cbrt(x) <cbrt>`                                Cube root of *x*
+:func:`exp(x) <exp>`                                  *e* raised to the power *x*
+:func:`exp2(x) <exp2>`                                *2* raised to the power *x*
+:func:`expm1(x) <expm1>`                              *e* raised to the power *x*, minus 1
+:func:`log(x, base) <log>`                            Logarithm of *x* to the given base (*e* by default)
+:func:`log1p(x) <log1p>`                              Natural logarithm of *1+x* (base *e*)
+:func:`log2(x) <log2>`                                Base-2 logarithm of *x*
+:func:`log10(x) <log10>`                              Base-10 logarithm of *x*
+:func:`pow(x, y) <math.pow>`                          *x* raised to the power *y*
+:func:`sqrt(x) <sqrt>`                                Square root of *x*
+
+**Trigonometric functions**
+--------------------------------------------------------------------------------------------------
+:func:`acos(x) <acos>`                                Arc cosine of *x*
+:func:`asin(x) <asin>`                                Arc sine of *x*
+: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*
+:func:`asinh(x) <asinh>`                              Inverse hyperbolic sine of *x*
+:func:`atanh(x) <atanh>`                              Inverse hyperbolic tangent of *x*
+:func:`cosh(x) <cosh>`                                Hyperbolic cosine of *x*
+:func:`sinh(x) <sinh>`                                Hyperbolic sine of *x*
+:func:`tanh(x) <tanh>`                                Hyperbolic tangent of *x*
+
+**Special functions**
+--------------------------------------------------------------------------------------------------
+:func:`erf(x) <erf>`                                  `Error function <https://en.wikipedia.org/wiki/Error_function>`_ at *x*
+:func:`erfc(x) <erfc>`                                `Complementary error function <https://en.wikipedia.org/wiki/Error_function>`_ at *x*
+:func:`gamma(x) <gamma>`                              `Gamma function <https://en.wikipedia.org/wiki/Gamma_function>`_ at *x*
+:func:`lgamma(x) <lgamma>`                            Natural logarithm of the absolute value of the `Gamma function <https://en.wikipedia.org/wiki/Gamma_function>`_ at *x*
+
+**Constants**
+--------------------------------------------------------------------------------------------------
+:data:`pi`                                            *π* = 3.141592...
+:data:`e`                                             *e* = 2.718281...
+:data:`tau`                                           *τ* = 2\ *π* = 6.283185...
+:data:`inf`                                           Positive infinity
+:data:`nan`                                           "Not a number" (NaN)
+====================================================  ============================================
+
+
 Number-theoretic and representation functions
 ---------------------------------------------
 
@@ -447,11 +533,11 @@ Power and logarithmic functions
 
 .. function:: pow(x, y)
 
-   Return ``x`` raised to the power ``y``.  Exceptional cases follow
+   Return *x* raised to the power *y*.  Exceptional cases follow
    the IEEE 754 standard as far as possible.  In particular,
    ``pow(1.0, x)`` and ``pow(x, 0.0)`` always return ``1.0``, even
-   when ``x`` is a zero or a NaN.  If both ``x`` and ``y`` are finite,
-   ``x`` is negative, and ``y`` is not an integer then ``pow(x, y)``
+   when *x* is a zero or a NaN.  If both *x* and *y* are finite,
+   *x* is negative, and *y* is not an integer then ``pow(x, y)``
    is undefined, and raises :exc:`ValueError`.
 
    Unlike the built-in ``**`` operator, :func:`math.pow` converts both