[3.14] decimal docs: specification link and examples (GH-128698) (#142804)

decimal docs: specification link and examples (GH-128698)
(cherry picked from commit 2450be6)

Co-authored-by: Sergey B Kirpichev <[email protected]>
Co-authored-by: RUANG (James Roy) <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>

Author: 5 people

Doc/library/decimal.rst

@@ -34,10 +34,12 @@ The :mod:`decimal` module provides support for fast correctly rounded
 decimal floating-point arithmetic. It offers several advantages over the
 :class:`float` datatype:
 
-* Decimal "is based on a floating-point model which was designed with people
-  in mind, and necessarily has a paramount guiding principle -- computers must
-  provide an arithmetic that works in the same way as the arithmetic that
-  people learn at school." -- excerpt from the decimal arithmetic specification.
+* Decimal "is based on a `floating-point model
+  <https://speleotrove.com/decimal/damodel.html#refnumber>`__ which was designed
+  with people in mind, and necessarily has a paramount guiding principle --
+  computers must provide an arithmetic that works in the same way as the
+  arithmetic that people learn at school." -- excerpt from the decimal
+  arithmetic specification.
 
 * Decimal numbers can be represented exactly.  In contrast, numbers like
   ``1.1`` and ``2.2`` do not have exact representations in binary
@@ -238,6 +240,26 @@ floating-point flying circus:
    >>> c % a
    Decimal('0.77')
 
+Decimals can be formatted (with :func:`format` built-in or :ref:`f-strings`) in
+fixed-point or scientific notation, using the same formatting syntax (see
+:ref:`formatspec`) as builtin :class:`float` type:
+
+.. doctest::
+
+   >>> format(Decimal('2.675'), "f")
+   '2.675'
+   >>> format(Decimal('2.675'), ".2f")
+   '2.68'
+   >>> f"{Decimal('2.675'):.2f}"
+   '2.68'
+   >>> format(Decimal('2.675'), ".2e")
+   '2.68e+0'
+   >>> with localcontext() as ctx:
+   ...     ctx.rounding = ROUND_DOWN
+   ...     print(format(Decimal('2.675'), ".2f"))
+   ...
+   2.67
+
 And some mathematical functions are also available to Decimal:
 
    >>> getcontext().prec = 28