Closes #4159: add LaTeX tabular column specifications to tables that otherwise...

Closes #4159: add LaTeX tabular column specifications to tables that otherwise are cut off or have overlapping text.

Doc/c-api/buffer.rst

@@ -263,6 +263,7 @@ The flags that control the logical structure of the memory are listed
 in decreasing order of complexity. Note that each flag contains all bits
 of the flags below it.
 
+.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|
 
 +-----------------------------+-------+---------+------------+
 |  Request                    | shape | strides | suboffsets |
@@ -283,6 +284,8 @@ contiguity requests
 C or Fortran contiguity can be explicitly requested, with and without stride
 information. Without stride information, the buffer must be C-contiguous.
 
+.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|
+
 +-----------------------------------+-------+---------+------------+--------+
 |  Request                          | shape | strides | suboffsets | contig |
 +===================================+=======+=========+============+========+
@@ -306,7 +309,7 @@ used combinations as single flags.
 In the following table *U* stands for undefined contiguity. The consumer would
 have to call :c:func:`PyBuffer_IsContiguous` to determine contiguity.
 
-
+.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|l|l|
 
 +-------------------------------+-------+---------+------------+--------+----------+--------+
 |  Request                      | shape | strides | suboffsets | contig | readonly | format |

Doc/c-api/bytes.rst

@@ -62,6 +62,8 @@ called with a non-bytes parameter.
    .. % because not all compilers support the %z width modifier -- we fake it
    .. % when necessary via interpolating PY_FORMAT_SIZE_T.
 
+   .. tabularcolumns:: |l|l|L|
+
    +-------------------+---------------+--------------------------------+
    | Format Characters | Type          | Comment                        |
    +===================+===============+================================+

Doc/c-api/unicode.rst

@@ -439,6 +439,8 @@ APIs:
    .. % Similar comments apply to the %ll width modifier and
    .. % PY_FORMAT_LONG_LONG.
 
+   .. tabularcolumns:: |l|l|L|
+
    +-------------------+---------------------+--------------------------------+
    | Format Characters | Type                | Comment                        |
    +===================+=====================+================================+

Doc/distutils/apiref.rst

@@ -26,6 +26,8 @@ setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and
    The setup function takes a large number of arguments. These are laid out in the
    following table.
 
+   .. tabularcolumns:: |l|L|L|
+
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | argument name      | value                          | type                                                        |
    +====================+================================+=============================================================+
@@ -125,6 +127,8 @@ setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and
 
    *stop_after* tells :func:`setup` when to stop processing; possible  values:
 
+   .. tabularcolumns:: |l|L|
+
    +---------------+---------------------------------------------+
    | value         | description                                 |
    +===============+=============================================+
@@ -165,6 +169,8 @@ the full reference.
    The Extension class describes a single C or C++extension module in a setup
    script. It accepts the following keyword arguments in its constructor:
 
+   .. tabularcolumns:: |l|L|l|
+
    +------------------------+--------------------------------+---------------------------+
    | argument name          | value                          | type                      |
    +========================+================================+===========================+
@@ -1562,6 +1568,8 @@ lines, and joining lines with backslashes.
 
    The options are all boolean, and affect the values returned by :meth:`readline`
 
+   .. tabularcolumns:: |l|L|l|
+
    +------------------+--------------------------------+---------+
    | option name      | description                    | default |
    +==================+================================+=========+

Doc/faq/extending.rst

@@ -2,7 +2,9 @@
 Extending/Embedding FAQ
 =======================
 
-.. contents::
+.. only:: html
+
+   .. contents::
 
 .. highlight:: c
 

Doc/faq/general.rst

@@ -4,7 +4,10 @@
 General Python FAQ
 ==================
 
-.. contents::
+.. only:: html
+
+   .. contents::
+
 
 General Information
 ===================

Doc/faq/gui.rst

@@ -4,7 +4,9 @@
 Graphic User Interface FAQ
 ==========================
 
-.. contents::
+.. only:: html
+
+   .. contents::
 
 .. XXX need review for Python 3.
 

Doc/faq/library.rst

@@ -4,7 +4,9 @@
 Library and Extension FAQ
 =========================
 
-.. contents::
+.. only:: html
+
+   .. contents::
 
 General Library Questions
 =========================

Doc/faq/programming.rst

@@ -4,7 +4,9 @@
 Programming FAQ
 ===============
 
-.. contents::
+.. only:: html
+
+   .. contents::
 
 General Questions
 =================

Doc/faq/windows.rst

@@ -6,7 +6,9 @@
 Python on Windows FAQ
 =====================
 
-.. contents::
+.. only:: html
+
+   .. contents::
 
 .. XXX need review for Python 3.
    XXX need review for Windows Vista/Seven?

Doc/howto/logging.rst

@@ -63,6 +63,8 @@ The logging functions are named after the level or severity of the events
 they are used to track. The standard levels and their applicability are
 described below (in increasing order of severity):
 
+.. tabularcolumns:: |l|L|
+
 +--------------+---------------------------------------------+
 | Level        | When it's used                              |
 +==============+=============================================+

Doc/install/index.rst

@@ -235,6 +235,8 @@ by how you built/installed Python itself.  On Unix (and Mac OS X, which is also
 Unix-based), it also depends on whether the module distribution being installed
 is pure Python or contains extensions ("non-pure"):
 
+.. tabularcolumns:: |l|l|l|l|
+
 +-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
 | Platform        | Standard installation location                      | Default value                                    | Notes |
 +=================+=====================================================+==================================================+=======+

Doc/library/codecs.rst

@@ -315,6 +315,8 @@ To simplify and standardize error handling, the :meth:`encode` and
 providing the *errors* string argument.  The following string values are defined
 and implemented by all standard Python codecs:
 
+.. tabularcolumns:: |l|L|
+
 +-------------------------+-----------------------------------------------+
 | Value                   | Meaning                                       |
 +=========================+===============================================+
@@ -926,6 +928,8 @@ particular, the following variants typically exist:
 
 * an IBM PC code page, which is ASCII compatible
 
+.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
+
 +-----------------+--------------------------------+--------------------------------+
 | Codec           | Aliases                        | Languages                      |
 +=================+================================+================================+
@@ -1140,6 +1144,8 @@ particular, the following variants typically exist:
 
 .. XXX fix here, should be in above table
 
+.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
+
 +--------------------+---------+---------------------------+
 | Codec              | Aliases | Purpose                   |
 +====================+=========+===========================+
@@ -1182,6 +1188,8 @@ particular, the following variants typically exist:
 
 The following codecs provide bytes-to-bytes mappings.
 
+.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
+
 +--------------------+---------------------------+---------------------------+
 | Codec              | Aliases                   | Purpose                   |
 +====================+===========================+===========================+
@@ -1208,6 +1216,8 @@ The following codecs provide bytes-to-bytes mappings.
 
 The following codecs provide string-to-string mappings.
 
+.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
+
 +--------------------+---------------------------+---------------------------+
 | Codec              | Aliases                   | Purpose                   |
 +====================+===========================+===========================+

Doc/library/collections.abc.rst

@@ -31,6 +31,8 @@ Collections Abstract Base Classes
 
 The collections module offers the following :term:`ABCs <abstract base class>`:
 
+.. tabularcolumns:: |l|L|L|L|
+
 =========================  =====================  ======================  ====================================================
 ABC                        Inherits from          Abstract Methods        Mixin Methods
 =========================  =====================  ======================  ====================================================
@@ -134,7 +136,7 @@ classes supporting container APIs.  For example, to write a class supporting
 the full :class:`Set` API, it only necessary to supply the three underlying
 abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
 The ABC supplies the remaining methods such as :meth:`__and__` and
-:meth:`isdisjoint` ::
+:meth:`isdisjoint`::
 
     class ListBasedSet(collections.Set):
          ''' Alternate set implementation favoring space over speed

Doc/library/concurrent.futures.rst

@@ -346,6 +346,8 @@ Module Functions
    *return_when* indicates when this function should return.  It must be one of
    the following constants:
 
+   .. tabularcolumns:: |l|L|
+
    +-----------------------------+----------------------------------------+
    | Constant                    | Description                            |
    +=============================+========================================+

Doc/library/email.policy.rst

@@ -139,6 +139,8 @@ added matters.  To illustrate::
       Controls the type of Content Transfer Encodings that may be or are
       required to be used.  The possible values are:
 
+      .. tabularcolumns:: |l|L|
+
       ========  ===============================================================
       ``7bit``  all data must be "7 bit clean" (ASCII-only).  This means that
                 where necessary data will be encoded using either

Doc/library/functions.rst

@@ -843,7 +843,7 @@ are always available.  They are listed here in alphabetical order.
 
    ========= ===============================================================
    Character Meaning
-   --------- ---------------------------------------------------------------
+   ========= ===============================================================
    ``'r'``   open for reading (default)
    ``'w'``   open for writing, truncating the file first
    ``'x'``   open for exclusive creation, failing if the file already exists

Doc/library/inspect.rst

@@ -520,6 +520,8 @@ function.
       Describes how argument values are bound to the parameter.  Possible values
       (accessible via :class:`Parameter`, like ``Parameter.KEYWORD_ONLY``):
 
+      .. tabularcolumns:: |l|L|
+
       +------------------------+----------------------------------------------+
       |    Name                | Meaning                                      |
       +========================+==============================================+

Doc/library/io.rst

@@ -187,6 +187,8 @@ Argument names are not part of the specification, and only the arguments of
 
 The following table summarizes the ABCs provided by the :mod:`io` module:
 
+.. tabularcolumns:: |l|l|L|L|
+
 =========================  ==================  ========================  ==================================================
 ABC                        Inherits            Stub Methods              Mixin Methods and Properties
 =========================  ==================  ========================  ==================================================

Doc/library/locale.rst

@@ -55,6 +55,8 @@ The :mod:`locale` module defines the following exception and functions:
    Returns the database of the local conventions as a dictionary. This dictionary
    has the following strings as keys:
 
+   .. tabularcolumns:: |l|l|L|
+
    +----------------------+-------------------------------------+--------------------------------+
    | Category             | Key                                 | Meaning                        |
    +======================+=====================================+================================+

Doc/library/logging.rst

@@ -1037,6 +1037,8 @@ functions.
 
    The following keyword arguments are supported.
 
+   .. tabularcolumns:: |l|L|
+
    +--------------+---------------------------------------------+
    | Format       | Description                                 |
    +==============+=============================================+

Doc/library/subprocess.rst

@@ -169,6 +169,8 @@ use cases, the underlying :class:`Popen` interface can be used directly.
 
    .. versionadded:: 3.1
 
+   ..
+
    .. warning::
 
       Invoking the system shell with ``shell=True`` can be a security hazard

Doc/library/sys.rst

@@ -307,6 +307,8 @@ always available.
    programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard
    [C99]_, 'Characteristics of floating types', for details.
 
+   .. tabularcolumns:: |l|l|L|
+
    +---------------------+----------------+--------------------------------------------------+
    | attribute           | float.h macro  | explanation                                      |
    +=====================+================+==================================================+
@@ -646,6 +648,8 @@ always available.
    A :term:`struct sequence` that holds information about Python's internal
    representation of integers.  The attributes are read only.
 
+   .. tabularcolumns:: |l|L|
+
    +-------------------------+----------------------------------------------+
    | Attribute               | Explanation                                  |
    +=========================+==============================================+
@@ -1079,6 +1083,8 @@ always available.
    A :term:`struct sequence` holding information about the thread
    implementation.
 
+   .. tabularcolumns:: |l|p{0.7\linewidth}|
+
    +------------------+---------------------------------------------------------+
    | Attribute        | Explanation                                             |
    +==================+=========================================================+

Doc/library/tkinter.ttk.rst

@@ -102,6 +102,8 @@ Standard Options
 
 All the :mod:`ttk` Widgets accepts the following options:
 
+   .. tabularcolumns:: |l|L|
+
    +-----------+--------------------------------------------------------------+
    | Option    | Description                                                  |
    +===========+==============================================================+
@@ -134,8 +136,10 @@ Scrollable Widget Options
 The following options are supported by widgets that are controlled by a
 scrollbar.
 
+   .. tabularcolumns:: |l|L|
+
    +----------------+---------------------------------------------------------+
-   | option         | description                                             |
+   | Option         | Description                                             |
    +================+=========================================================+
    | xscrollcommand | Used to communicate with horizontal scrollbars.         |
    |                |                                                         |
@@ -158,11 +162,10 @@ Label Options
 The following options are supported by labels, buttons and other button-like
 widgets.
 
-.. tabularcolumns:: |p{0.2\textwidth}|p{0.7\textwidth}|
-..
+   .. tabularcolumns:: |l|p{0.7\linewidth}|
 
    +--------------+-----------------------------------------------------------+
-   | option       | description                                               |
+   | Option       | Description                                               |
    +==============+===========================================================+
    | text         | Specifies a text string to be displayed inside the widget.|
    +--------------+-----------------------------------------------------------+
@@ -202,8 +205,10 @@ widgets.
 Compatibility Options
 ^^^^^^^^^^^^^^^^^^^^^
 
+   .. tabularcolumns:: |l|L|
+
    +--------+----------------------------------------------------------------+
-   | option | description                                                    |
+   | Option | Description                                                    |
    +========+================================================================+
    | state  | May be set to "normal" or "disabled" to control the "disabled" |
    |        | state bit. This is a write-only option: setting it changes the |
@@ -216,8 +221,10 @@ Widget States
 
 The widget state is a bitmap of independent state flags.
 
+   .. tabularcolumns:: |l|L|
+
    +------------+-------------------------------------------------------------+
-   | flag       | description                                                 |
+   | Flag       | Description                                                 |
    +============+=============================================================+
    | active     | The mouse cursor is over the widget and pressing a mouse    |
    |            | button will cause some action to occur                      |
@@ -301,8 +308,10 @@ Options
 
 This widget accepts the following specific options:
 
+   .. tabularcolumns:: |l|L|
+
    +-----------------+--------------------------------------------------------+
-   | option          | description                                            |
+   | Option          | Description                                            |
    +=================+========================================================+
    | exportselection | Boolean value. If set, the widget selection is linked  |
    |                 | to the Window Manager selection (which can be returned |
@@ -380,8 +389,10 @@ Options
 
 This widget accepts the following specific options:
 
+   .. tabularcolumns:: |l|L|
+
    +---------+----------------------------------------------------------------+
-   | option  | description                                                    |
+   | Option  | Description                                                    |
    +=========+================================================================+
    | height  | If present and greater than zero, specifies the desired height |
    |         | of the pane area (not including internal padding or tabs).     |
@@ -404,8 +415,10 @@ Tab Options
 
 There are also specific options for tabs:
 
+   .. tabularcolumns:: |l|L|
+
    +-----------+--------------------------------------------------------------+
-   | option    | description                                                  |
+   | Option    | Description                                                  |
    +===========+==============================================================+
    | state     | Either "normal", "disabled" or "hidden". If "disabled", then |
    |           | the tab is not selectable. If "hidden", then the tab is not  |
@@ -566,8 +579,10 @@ Options
 
 This widget accepts the following specific options:
 
+   .. tabularcolumns:: |l|L|
+
    +----------+---------------------------------------------------------------+
-   | option   | description                                                   |
+   | Option   | Description                                                   |
    +==========+===============================================================+
    | orient   | One of "horizontal" or "vertical". Specifies the orientation  |
    |          | of the progress bar.                                          |
@@ -635,8 +650,10 @@ Options
 
 This widget accepts the following specific option:
 
+   .. tabularcolumns:: |l|L|
+
    +--------+----------------------------------------------------------------+
-   | option | description                                                    |
+   | Option | Description                                                    |
    +========+================================================================+
    | orient | One of "horizontal" or "vertical". Specifies the orientation of|
    |        | the separator.                                                 |
@@ -701,11 +718,10 @@ Options
 
 This widget accepts the following specific options:
 
-.. tabularcolumns:: |p{0.2\textwidth}|p{0.7\textwidth}|
-..
+   .. tabularcolumns:: |l|p{0.7\linewidth}|
 
    +----------------+--------------------------------------------------------+
-   | option         | description                                            |
+   | Option         | Description                                            |
    +================+========================================================+
    | columns        | A list of column identifiers, specifying the number of |
    |                | columns and their names.                               |
@@ -753,8 +769,10 @@ Item Options
 The following item options may be specified for items in the insert and item
 widget commands.
 
+   .. tabularcolumns:: |l|L|
+
    +--------+---------------------------------------------------------------+
-   | option | description                                                   |
+   | Option | Description                                                   |
    +========+===============================================================+
    | text   | The textual label to display for the item.                    |
    +--------+---------------------------------------------------------------+
@@ -779,8 +797,10 @@ Tag Options
 
 The following options may be specified on tags:
 
+   .. tabularcolumns:: |l|L|
+
    +------------+-----------------------------------------------------------+
-   | option     | description                                               |
+   | Option     | Description                                               |
    +============+===========================================================+
    | foreground | Specifies the text foreground color.                      |
    +------------+-----------------------------------------------------------+
@@ -822,8 +842,10 @@ Virtual Events
 
 The Treeview widget generates the following virtual events.
 
+   .. tabularcolumns:: |l|L|
+
    +--------------------+--------------------------------------------------+
-   | event              | description                                      |
+   | Event              | Description                                      |
    +====================+==================================================+
    | <<TreeviewSelect>> | Generated whenever the selection changes.        |
    +--------------------+--------------------------------------------------+

Doc/library/turtle.rst

@@ -2301,9 +2301,11 @@ The :mod:`turtledemo` package directory contains:
 
 The demo scripts are:
 
+.. tabularcolumns:: |l|L|L|
+
 +----------------+------------------------------+-----------------------+
 | Name           | Description                  | Features              |
-+----------------+------------------------------+-----------------------+
++================+==============================+=======================+
 | bytedesign     | complex classical            | :func:`tracer`, delay,|
 |                | turtle graphics pattern      | :func:`update`        |
 +----------------+------------------------------+-----------------------+

Doc/library/warnings.rst

@@ -54,6 +54,8 @@ There are a number of built-in exceptions that represent warning categories.
 This categorization is useful to be able to filter out groups of warnings.  The
 following warnings category classes are currently defined:
 
+.. tabularcolumns:: |l|p{0.6\linewidth}|
+
 +----------------------------------+-----------------------------------------------+
 | Class                            | Description                                   |
 +==================================+===============================================+

Doc/library/xml.etree.elementtree.rst

@@ -278,6 +278,8 @@ module.  We'll be using the ``countrydata`` XML document from the
 Supported XPath syntax
 ^^^^^^^^^^^^^^^^^^^^^^
 
+.. tabularcolumns:: |l|L|
+
 +-----------------------+------------------------------------------------------+
 | Syntax                | Meaning                                              |
 +=======================+======================================================+

Doc/library/xmlrpc.client.rst

@@ -72,6 +72,8 @@ between conformable Python objects and XML on the wire.
    (e.g. that can be marshalled through XML), include the following (and except
    where noted, they are unmarshalled as the same Python type):
 
+   .. tabularcolumns:: |l|L|
+
    +---------------------------------+---------------------------------------------+
    | Name                            | Meaning                                     |
    +=================================+=============================================+

Doc/reference/datamodel.rst

@@ -448,6 +448,8 @@ Callable types
 
       Special attributes:
 
+      .. tabularcolumns:: |l|L|l|
+
       +-------------------------+-------------------------------+-----------+
       | Attribute               | Meaning                       |           |
       +=========================+===============================+===========+

Doc/reference/expressions.rst

@@ -1335,7 +1335,7 @@ groups from right to left).
 | :keyword:`not` ``x``                          | Boolean NOT                         |
 +-----------------------------------------------+-------------------------------------+
 | :keyword:`in`, :keyword:`not in`,             | Comparisons, including membership   |
-| :keyword:`is`, :keyword:`is not`, ``<``,      | tests and identity tests,           |
+| :keyword:`is`, :keyword:`is not`, ``<``,      | tests and identity tests            |
 | ``<=``, ``>``, ``>=``, ``!=``, ``==``         |                                     |
 +-----------------------------------------------+-------------------------------------+
 | ``|``                                         | Bitwise OR                          |

Doc/reference/import.rst

@@ -685,8 +685,7 @@ proposed ``__name__`` for semantics :pep:`366` would eventually specify for
 :pep:`338` defines executing modules as scripts.
 
 
-Footnotes
-=========
+.. rubric:: Footnotes
 
 .. [#fnmo] See :class:`types.ModuleType`.
 

Doc/whatsnew/3.3.rst

@@ -1208,6 +1208,8 @@ the ``Message`` object it is serializing.  The default policy is
 
 The minimum set of controls implemented by all ``policy`` objects are:
 
+    .. tabularcolumns:: |l|L|
+
     ===============     =======================================================
     max_line_length     The maximum length, excluding the linesep character(s),
                         individual lines may have when a ``Message`` is
@@ -1259,6 +1261,8 @@ removal of the code) may occur if deemed necessary by the core developers.
 The new policies are instances of :class:`~email.policy.EmailPolicy`,
 and add the following additional controls:
 
+    .. tabularcolumns:: |l|L|
+
     ===============     =======================================================
     refold_source       Controls whether or not headers parsed by a
                         :mod:`~email.parser` are refolded by the