LaTeX: support for booktabs-style and zebra-striped tables (#10759)

This is a combination of 2 + 28 + 7 + and some more commits...

* Cherry-pick: Add support for booktabs-style tables to LaTeX builder

* Cherry-pick: Add support for zebra-striped tables to LaTeX builder

Co-authored-by: Stefan Wiehler <stefan.wiehler@missinglinkelectronics.com>

Above work originally initiated by @sephalon (thanks!)

Development refactored and continued by @jfbu

* latex_table_style configuration, support booktabs, colorrows, borderless

Some details:

- Simplify a bit a conditional in the longtable template

  This also puts the target for a longtable with a label but no caption
  above the toprule for better hyperlinking (testing shows hyperlink
  target can not end up alone at bottom of previous page).

- Extend allowed syntax for colour assignments via 'sphinxsetup'

- latex_table_style new configuration value and coloured rows

  For the user interface I tried to look for inspiration in
  https://docutils.sourceforge.io/docs/user/config.html#table-style
  which mentions booktabs and borderless.  They also mention
  captionbelow which we can implement later, now that architecture
  is here.  They don't mention coloured rows.

- Test on our own document... looks fine!

- Work-around an incompatibility of \cline with row colours

- Reverse priority of classes to allow overruling booktabs by standard
  after parsing source but before letting LaTeX writer act

- Closes #8220

  Commit
  bb859c6
  already improved a bit, this finishes it (as :rst:dir:`rst-class` was
  actually not linking to anywhere).

- Let booktabs style defaults to *not* using \cmidrule.  They actually
  don't make much sense there, as all \hline's are removed.

- Add \sphinxnorowcolor which allows construct such as this one in
  a tabularcolumns directive:

    >{\columncolor{blue}\sphinxnorowcolor}

  else LaTeX always overrides column colour by row colour

- Add TableMergeColorHeader, TableMergeColorOdd, TableMergeColorEven
  so single-row merged cells can be styled especially

- Extend row colours to all header rows not only the first one
  (all header rows will share same colour settings)

- Auto-adjust to a no '|'-colspec for optimal handling of merged cell

- Add \sphinxcolorblend

- Workaround LaTeX's \cline features and other grid tables matters

- Add \sphinxbuildwarning for important warnings

- Fix some white gaps in merged cells of tables with vlines and
  colorrows

- Work around LaTeX's \cline serious deficiencies for complex grid
  tables

  This commit corrects \cline badly impacting vertical spacing and
  making tables look even more cramped as they usually are in LaTeX
  (although one sees it clearly only with \arrarrulewidth a bit more
  than the LaTeX default of 0.4pt).

  Most importantly this commit solves the problem that \cline's got
  masked by colour panels from the row below.

- Update CHANGES for PR #10759

- Improve documentation of new latex_table_style regarding colours

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`.