LaTeX: support for booktabs-style and zebra-striped tables

CHANGES

@@ -13,6 +13,8 @@ Deprecated
 Features added
 --------------
 
+* #10759: LaTeX: add :confval:`latex_table_style` and support the
+  ``'booktabs'``, ``'borderless'``, and ``'colorrows'`` styles.
 * #10840: One can cross-reference including an option value like ``:option:`--module=foobar```,
   ``:option:`--module[=foobar]``` or ``:option:`--module foobar```.
   Patch by Martin Liska.

doc/conf.py

@@ -78,14 +78,15 @@
              {\begin{sphinxtheindex}\end{sphinxtheindex}}
 ''',
     'sphinxsetup': """%
-VerbatimColor={RGB}{242,242,242},%
+VerbatimColor=black!5,% tests 5.2.0 extended syntax
 VerbatimBorderColor={RGB}{32,32,32},%
 pre_border-radius=3pt,%
 pre_box-decoration-break=slice,%
 """,
 }
 latex_show_urls = 'footnote'
 latex_use_xindy = True
+latex_table_style = ['booktabs', 'colorrows']
 
 autodoc_member_order = 'groupwise'
 autosummary_generate = False

doc/extdev/deprecated.rst

@@ -10,7 +10,7 @@ major versions (for more details, please see :ref:`deprecation-policy`).
 
 The following is a list of deprecated interfaces.
 
-.. tabularcolumns:: |>{\raggedright}\Y{.4}|>{\centering}\Y{.1}|>{\centering}\Y{.12}|>{\raggedright\arraybackslash}\Y{.38}|
+.. tabularcolumns:: >{\raggedright}\Y{.4}>{\centering}\Y{.1}>{\sphinxcolorblend{!95!red}\centering\noindent\bfseries\color{red}}\Y{.12}>{\raggedright\arraybackslash}\Y{.38}
 
 .. list-table:: deprecated APIs
    :header-rows: 1
@@ -19,7 +19,7 @@ The following is a list of deprecated interfaces.
 
    * - Target
      - Deprecated
-     - (will be) Removed
+     - Removed
      - Alternatives
 
    * - HTML 4 support

doc/latex.rst

@@ -823,16 +823,31 @@ Do not use quotes to enclose values, whether numerical or strings.
        definition of the continuation symbol was changed at 1.5 to accommodate
        various font sizes (e.g. code-blocks can be in footnotes).
 
+.. note::
+
+   Values for colour keys must either:
+
+   - obey the syntax of the ``\definecolor`` LaTeX command, e.g. something
+     such as ``VerbatimColor={rgb}{0.2,0.3,0.5}`` or ``{RGB}{37,23,255}`` or
+     ``{gray}{0.75}`` or (only with package ``xcolor``) ``{HTML}{808080}`` or
+     ...
+
+   - or obey the syntax of the ``\colorlet`` command from package ``xcolor``
+     (which then must exist in the LaTeX installation),
+     e.g. ``VerbatimColor=red!10`` or ``red!50!green`` or ``-red!75`` or
+     ``MyPreviouslyDefinedColour`` or... Refer to xcolor_ documentation for
+     this syntax.
+
+   .. _xcolor: https://ctan.org/pkg/xcolor
+
+   .. versionchanged:: 5.2.0
+      Formerly only the ``\definecolor`` syntax was accepted.
+
 ``TitleColor``
     The colour for titles (as configured via use of package "titlesec".)
 
     Default: ``{rgb}{0.126,0.263,0.361}``
 
-    .. warning::
-
-       Colours set via ``'sphinxsetup'``  must obey the syntax of the
-       argument of the ``color/xcolor`` packages ``\definecolor`` command.
-
 ``InnerLinkColor``
     A colour passed to ``hyperref`` as value of ``linkcolor``  and
     ``citecolor``.
@@ -862,10 +877,47 @@ Do not use quotes to enclose values, whether numerical or strings.
 
     .. versionadded:: 1.6.6
 
-    .. note::
+.. _tablecolors:
+
+``TableRowColorHeader``
+    Sets the background colour for (all) the header rows of tables.
+
+    It will have an effect only if either the :confval:`latex_table_style`
+    contains ``'colorrows'`` or if the table is assigned the ``colorrows``
+    class.  It is ignored for tables with ``nocolorrows`` class.
 
-       Starting with this colour, and for all others following, the
-       names declared to "color" or "xcolor" are prefixed with "sphinx".
+    As for the other ``'sphinxsetup'`` keys, it can also be set or modified
+    from a ``\sphinxsetup{...}`` LaTeX command inserted via the :dudir:`raw`
+    directive, or also from a LaTeX environment associated to a `container
+    class <latexcontainer_>`_ and using such ``\sphinxsetup{...}``.
+
+    Default: ``{gray}{0.86}``
+
+    There is also ``TableMergeColorHeader``.  If used, sets a specific colour
+    for merged single-row cells in the header.
+
+    .. versionadded:: 5.2.0
+
+``TableRowColorOdd``
+    Sets the background colour for odd rows in tables (the row count starts at
+    ``1`` at the first non-header row).  Has an effect only if the
+    :confval:`latex_table_style` contains ``'colorrows'`` or for specific
+    tables assigned the ``colorrows`` class.
+
+    Default: ``{gray}{0.92}``
+
+    There is also ``TableMergeColorOdd``.
+
+    .. versionadded:: 5.2.0
+
+``TableRowColorEven``
+    Sets the background colour for even rows in tables.
+
+    Default ``{gray}{0.98}``
+
+    There is also ``TableMergeColorEven``.
+
+    .. versionadded:: 5.2.0
 
 ``verbatimsep``
     The separation between code lines and the frame.
@@ -1425,6 +1477,8 @@ Miscellany
      Formerly, use of *fncychap* with other styles than ``Bjarne`` was
      dysfunctional.
 
+.. _latexcontainer:
+
 - Docutils :dudir:`container` directives are supported in LaTeX output: to
   let a container class with name ``foo`` influence the final PDF via LaTeX,
   it is only needed to define in the preamble an environment

doc/usage/configuration.rst

@@ -2233,6 +2233,101 @@ These options influence LaTeX output.
 
    .. versionadded:: 1.6
 
+.. confval:: latex_table_style
+
+   A list of styling classes (strings).  Currently supported:
+
+   - ``'booktabs'``: no vertical lines, and only 2 or 3 horizontal lines (the
+     latter if there is a header), using the booktabs_ package.
+
+   - ``'borderless'``: no lines whatsoever.
+
+   - ``'colorrows'``: the table rows are rendered with alternating background
+     colours.  The interface to customize them is via :ref:`dedicated keys
+     <tablecolors>` of :ref:`latexsphinxsetup`.
+
+     .. important::
+
+        With the ``'colorrows'`` style, the ``\rowcolors`` LaTeX command
+        becomes a no-op (this command has limitations and has never correctly
+        supported all types of tables Sphinx produces in LaTeX).  Please
+        update your project to use instead
+        the :ref:`latex table color configuration <tablecolors>` keys.
+
+   Default: ``[]``
+
+   .. versionadded:: 5.2.0
+
+   If using ``'booktabs'`` or ``'borderless'`` it seems recommended to also
+   opt for ``'colorrows'``...
+
+   Each table can override the global style via ``:class:`` option, or
+   ``.. rst-class::`` for no-directive tables (cf.  :ref:`table-directives`).
+   Currently recognized classes are ``booktabs``, ``borderless``,
+   ``standard``, ``colorrows``, ``nocolorrows``.  The latter two can be
+   combined with any of the first three.  The ``standard`` class produces
+   tables with both horizontal and vertical lines (as has been the default so
+   far with Sphinx).
+
+   A single-row multi-column merged cell will obey the row colour, if it is
+   set.  See also ``TableMergeColor{Header,Odd,Even}`` in the
+   :ref:`latexsphinxsetup` section.
+
+   .. note::
+
+      - It is hard-coded in LaTeX that a single cell will obey the row colour
+        even if there is a column colour set via ``\columncolor`` from a
+        column specification (see :rst:dir:`tabularcolumns`).  Sphinx provides
+        ``\sphinxnorowcolor`` which can be used like this:
+
+        .. code-block:: latex
+
+           >{\columncolor{blue}\sphinxnorowcolor}
+
+        in a table column specification.
+
+      - Sphinx also provides ``\sphinxcolorblend`` which however requires the
+        xcolor_ package.  Here is an example:
+
+        .. code-block:: latex
+
+           >{\sphinxcolorblend{!95!red}}
+
+        It means that in this column, the row colours will be slightly tinted
+        by red; refer to xcolor_ documentation for more on the syntax of its
+        ``\blendcolors`` command (a ``\blendcolors`` in place of
+        ``\sphinxcolorblend`` would modify colours of the cell *contents*, not
+        of the cell *background colour panel*...).  You can find an example of
+        usage in the :ref:`dev-deprecated-apis` section of this document in
+        PDF format.
+
+        .. hint::
+
+           If you want to use a special colour for the *contents* of the
+           cells of a given column use ``>{\noindent\color{<color>}}``,
+           possibly in addition to the above.
+
+      - Multi-row merged cells, whether single column or multi-column
+        currently ignore any set column, row, or cell colour.
+
+      - It is possible for a simple cell to set a custom colour via the
+        :dudir:`raw` directive and the ``\cellcolor`` LaTeX command used
+        anywhere in the cell contents.  This currently is without effect
+        in a merged cell, whatever its kind.
+
+   .. hint::
+
+      In a document not using ``'booktabs'`` globally, it is possible to style
+      an individual table via the ``booktabs`` class, but it will be necessary
+      to add ``r'\usepackage{booktabs}'`` to the LaTeX preamble.
+
+      On the other hand one can use ``colorrows`` class for individual tables
+      with no extra package (as Sphinx since 5.2.0 always loads colortbl_).
+
+   .. _booktabs: https://ctan.org/pkg/booktabs
+   .. _colortbl: https://ctan.org/pkg/colortbl
+   .. _xcolor: https://ctan.org/pkg/xcolor
+
 .. confval:: latex_use_xindy
 
    If ``True``, the PDF build from the LaTeX files created by Sphinx

doc/usage/restructuredtext/basics.rst

@@ -370,7 +370,15 @@ Docutils supports the following directives:
   - :dudir:`include` (include reStructuredText from another file) -- in Sphinx,
     when given an absolute include file path, this directive takes it as
     relative to the source directory
-  - :dudir:`class` (assign a class attribute to the next element) [1]_
+
+    .. _rstclass:
+
+  - :dudir:`class` (assign a class attribute to the next element)
+
+    .. note::
+
+       When the default domain contains a ``class`` directive, this directive
+       will be shadowed.  Therefore, Sphinx re-exports it as ``rst-class``.
 
 * HTML specifics:
 
@@ -621,10 +629,3 @@ There are some problems one commonly runs into while authoring reST documents:
 
 * **No nested inline markup:** Something like ``*see :func:`foo`*`` is not
   possible.
-
-
-.. rubric:: Footnotes
-
-.. [1] When the default domain contains a :rst:dir:`class` directive, this
-       directive will be shadowed.  Therefore, Sphinx re-exports it as
-       :rst:dir:`rst-class`.