latex_book_style configuration, support booktabs, colorrows, borderless

This is a combination of 28 commits...

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

- Refactor and trim doc about LaTeX tables... to make room for more,
  later

- Enlarge allowed syntax for colour assignments via 'sphinxsetup'

- latex_table_style new configuration value and coloured rows

  For the user interface 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!

- Update LaTeX table tests and templates

  Modify longtable templates to put LaTeX macros each on its line

  Table body insertion without removing previous EOL may give output
  which contain some empty lines but longtable defines \par token to be
  same as \empty.

- Work-around an incompatibility of \cline with row colours, improve
  docs

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

- Closes sphinx-doc#8220

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

- Update CHANGES for PR sphinx-doc#10759

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

- Enhance customizability at LaTeX code level (via code executed prior
  to table rendering, e.g. from a container class environment).

- Patch booktabs \cmidrule, as if it used via \sphinxcline, there is
  a vertical space problem in case of there are two in the same row
  due to booktabs \futurelet not knowing \sphinxcline

- 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

- Needed to also detect if a '|' is in tabularcolumns, tests updated

- Fix refactoring in this series which broke table.colsep update

- Add test which would have shown regression regarding table.colsep

- Fix another regression regarding \sphinxcline + booktabs

  Can not add test for that, because it shows only after PDF build.

- Final testing and code comments update

CHANGES

@@ -15,6 +15,8 @@ Features added
 
 - #10286: C++, support requires clauses not just between the template
   parameter lists and the declaration.
+- #10759: LaTeX: add :confval:`latex_table_style` and support the
+  ``'booktabs'``, ``'borderless'``, and ``'colorrows'`` styles.
 
 Bugs fixed
 ----------

doc/conf.py

@@ -77,14 +77,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
 
    * - ``sphinx.util.path_stabilize``

doc/latex.rst

@@ -819,16 +819,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``.
@@ -841,18 +856,6 @@ Do not use quotes to enclose values, whether numerical or strings.
 
     Default: ``{rgb}{0.216,0.439,0.388}``
 
-``RowEvenColor``
-    default ``{rgb}{0.85,0.85,0.85}``. Background color for even rows in
-    tables, if option :confval:`latex_zebra_stripes` is set to ``True``.
-
-    .. versionadded:: 2.1
-
-``RowOddColor``
-    default ``{rgb}{1,1,1}``. Background color for odd rows in tables, if
-    option :confval:`latex_zebra_stripes` is set to ``True``.
-
-    .. versionadded:: 2.1
-
 ``VerbatimColor``
     The background colour for :rst:dir:`code-block`\ s.
 
@@ -875,6 +878,40 @@ Do not use quotes to enclose values, whether numerical or strings.
        Starting with this colour, and for all others following, the
        names declared to "color" or "xcolor" are prefixed with "sphinx".
 
+``TableRowColorHeader``
+    Background colour for (all) the header rows.  This (as the next
+    ``Table...`` colours) applies conditionnally
+    on either ``'colorrows'`` being contained in :confval:`latex_table_style`
+    or on the table receiving ``colorrows`` as class.
+
+    Default: ``{gray}{0.86}``
+
+    There is also ``TableMergeColorHeader`` which as long as it is not
+    defined (either globally via ``'sphinxsetup'`` interface or locally
+    via :dudir:`raw` directive and ``\sphinxsetup`` LaTeX macro) will keep
+    in sync with ``TableRowColorHeader``.
+
+    .. versionadded:: 5.2.0
+
+``TableRowColorOdd``
+    Background colour for odd rows in tables (the row count starts at ``1``
+    at the first non-header row).
+
+    Default: ``{gray}{0.92}``
+
+    There is also ``TableMergeColorOdd``.
+
+    .. versionadded:: 5.2.0
+
+``TableRowColorEven``
+    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.
 

doc/usage/configuration.rst

@@ -2210,6 +2210,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 body rows are rendered with alternating background
+     colours, see the :ref:`latexsphinxsetup` keys ``TableRowColorOdd`` and
+     ``TableRowColorEven`` for configuration.  And ``TableRowColorHeader``
+     for the header rows.
+
+   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_).
+
+      When using both ``'booktabs'`` and ``'colorrows'`` there is a small
+      white gap between the bottom row and the bottom rule, and between the
+      first body row and the (mid or top) rule above it.  It is possible to
+      extend the background colouring to touch the rules, via some extra LaTeX
+      coding.  This may be added to Sphinx in case of feature request, but
+      this whitespace is considered currently a quality rather than a defect.
+
+   .. _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
@@ -2241,25 +2336,6 @@ These options influence LaTeX output.
 
    .. versionadded:: 1.8
 
-.. confval:: latex_use_booktabs
-
-   If ``True``, render tables without vertical rules and horizontal rules of
-   varying thickness (with additional space above and below) using the
-   booktabs_ package.
-
-   .. _booktabs: https://ctan.org/pkg/booktabs
-
-   .. versionadded:: 5.2.0
-
-.. confval:: latex_zebra_stripes
-
-   If ``True``, render tables with alternating background colors for even and
-   odd rows (so called "zebra striping"). See :ref:`latexsphinxsetup`
-   ``RowEvenColor`` and ``RowOddColor`` for changing the default white-grey
-   color scheme.
-
-   .. versionadded:: 2.1
-
 .. confval:: latex_elements
 
    .. versionadded:: 0.5

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