Move pprinter parameters description to the table

Privat33r-dev · Privat33r-dev · commit cc92c08f7fa3 · 2024-03-31T14:16:07.000+02:00
The change improves readability.
Suggested in the GH#116085 PR discussion.
diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst
@@ -70,18 +70,57 @@ Functions
    The configuration parameters *stream*, *indent*, *width*, *depth*,
    *compact*, *sort_dicts* and *underscore_numbers* are passed to the
    :class:`PrettyPrinter` constructor and their meanings are as
-   described in its documentation below.
+   described in the documentation below.
 
    Note that *sort_dicts* is ``True`` by default and you might want to use
    :func:`~pprint.pp` instead where it is ``False`` by default.
 
+.. _prettyprinter-parameters:
+
+.. list-table:: **Recognised parameters for PrettyPrinter**
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Parameter
+     - Description
+   * - ``indent``: ``int``
+     - The amount of indentation added for each nesting level.
+   * - ``width``: ``int``
+     - The desired maximum number of characters per line in the output.
+       If a structure cannot be formatted within the width constraint,
+       a best effort will be made.
+   * - ``depth``: ``int`` | ``None``
+     - The number of nesting levels which may be printed.
+       If the data structure being printed is too deep,
+       the next contained level is replaced by ``...``.
+       If ``None`` (the default), there is no constraint
+       on the depth of the objects being formatted.
+   * - ``stream``: :term:`file-like object` | ``None``
+     - A file-like object to which the output will be written
+       by calling its :meth:`!write` method.
+       If ``None`` (the default), :data:`sys.stdout` is used.
+   * - ``compact``: ``bool``
+     - Control the way long :term:`sequences <sequence>` are formatted.
+       If ``False`` (the default),
+       each item of a sequence will be formatted on a separate line,
+       otherwise as many items as will fit within the *width*
+       will be formatted on each output line.
+   * - ``sort_dicts``: ``bool``
+     - If ``True`` (the default), dictionaries will be formatted with
+       their keys sorted, otherwise they will display in insertion order.
+   * - ``underscore_numbers``: ``bool``
+     - If ``True``,
+       integers will be formatted with the ``_`` character for a thousands separator,
+       otherwise underscores are not displayed (the default).
+
+
 .. function:: pformat(object, indent=1, width=80, depth=None, *, \
                       compact=False, sort_dicts=True, underscore_numbers=False)
 
    Return the formatted representation of *object* as a string.  *indent*,
    *width*, *depth*, *compact*, *sort_dicts* and *underscore_numbers* are
    passed to the :class:`PrettyPrinter` constructor as formatting parameters
-   and their meanings are as described in its documentation below.
+   and their meanings are as described in the documentation above.
 
 
 .. function:: isreadable(object)
@@ -120,51 +159,14 @@ Functions
 PrettyPrinter Objects
 ---------------------
 
-This module defines one class:
-
-.. First the implementation class:
-
-
 .. index:: single: ...; placeholder
 
 .. class:: PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, \
                          compact=False, sort_dicts=True, underscore_numbers=False)
 
    Construct a :class:`PrettyPrinter` instance.  This constructor understands
    several keyword parameters.
-
-   *stream* (default :data:`!sys.stdout`) is a :term:`file-like object` to
-   which the output will be written by calling its :meth:`!write` method.
-   If both *stream* and :data:`!sys.stdout` are ``None``, then
-   :meth:`~PrettyPrinter.pprint` silently returns.
-
-   Other values configure the manner in which nesting of complex data
-   structures is displayed.
-
-   *indent* (default 1) specifies the amount of indentation added for
-   each nesting level.
-
-   *depth* controls the number of nesting levels which may be printed; if
-   the data structure being printed is too deep, the next contained level
-   is replaced by ``...``.  By default, there is no constraint on the
-   depth of the objects being formatted.
-
-   *width* (default 80) specifies the desired maximum number of characters per
-   line in the output. If a structure cannot be formatted within the width
-   constraint, a best effort will be made.
-
-   *compact* impacts the way that long sequences (lists, tuples, sets, etc)
-   are formatted. If *compact* is false (the default) then each item of a
-   sequence will be formatted on a separate line.  If *compact* is true, as
-   many items as will fit within the *width* will be formatted on each output
-   line.
-
-   If *sort_dicts* is true (the default), dictionaries will be formatted with
-   their keys sorted, otherwise they will display in insertion order.
-
-   If *underscore_numbers* is true, integers will be formatted with the
-   ``_`` character for a thousands separator, otherwise underscores are not
-   displayed (the default).
+   Parameters described at :ref:`parameters table <prettyprinter-parameters>`.
 
    .. versionchanged:: 3.4
       Added the *compact* parameter.
