From 993e970ad5b7f88d426d8079387527636bfe0d83 Mon Sep 17 00:00:00 2001
From: Stefan Wiehler <stefan.wiehler@missinglinkelectronics.com>
Date: Mon, 26 Aug 2019 12:00:43 +0200
Subject: [PATCH] Cherry-pick: Add support for zebra-striped tables to LaTeX
 builder

Render tables with alternating background colors for even and odd rows
(so called "zebra striping").
---
 doc/latex.rst                     | 12 ++++++++++++
 doc/usage/configuration.rst       |  9 +++++++++
 sphinx/builders/latex/__init__.py |  1 +
 sphinx/texinputs/sphinx.sty       |  4 +++-
 sphinx/writers/latex.py           |  8 ++++++++
 5 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/doc/latex.rst b/doc/latex.rst
index c46ab6e29b6..17698fcce85 100644
--- a/doc/latex.rst
+++ b/doc/latex.rst
@@ -841,6 +841,18 @@ 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.
 
diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst
index 00c3ba8f67c..898d2fa4825 100644
--- a/doc/usage/configuration.rst
+++ b/doc/usage/configuration.rst
@@ -2251,6 +2251,15 @@ These options influence LaTeX output.
 
    .. 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
diff --git a/sphinx/builders/latex/__init__.py b/sphinx/builders/latex/__init__.py
index f02e69483e6..a2478ad9684 100644
--- a/sphinx/builders/latex/__init__.py
+++ b/sphinx/builders/latex/__init__.py
@@ -519,6 +519,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('latex_use_latex_multicolumn', False, None)
     app.add_config_value('latex_use_xindy', default_latex_use_xindy, None, [bool])
     app.add_config_value('latex_use_booktabs', False, None)
+    app.add_config_value('latex_zebra_stripes', False, None)
     app.add_config_value('latex_toplevel_sectioning', None, None,
                          ENUM(None, 'part', 'chapter', 'section'))
     app.add_config_value('latex_domain_indices', True, None, [list])
diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty
index dabe1d37b75..0077543d999 100644
--- a/sphinx/texinputs/sphinx.sty
+++ b/sphinx/texinputs/sphinx.sty
@@ -43,7 +43,7 @@
 % checked at 5.0.0) \fcolorbox is used for admonitions (sphinxheavybox)
 % and appears also in Pygmentize output mark-up.
 \IfFileExists{xcolor.sty}{
-    \RequirePackage{xcolor}
+    \RequirePackage[table]{xcolor}
 }{
     \RequirePackage{color}
 }
@@ -153,6 +153,8 @@
 \sphinxDeclareColorOption{OuterLinkColor}{{rgb}{0.216,0.439,0.388}}
 \sphinxDeclareColorOption{VerbatimColor}{{rgb}{1,1,1}}
 \sphinxDeclareColorOption{VerbatimBorderColor}{{rgb}{0,0,0}}
+\sphinxDeclareColorOption{RowEvenColor}{{rgb}{0.85,0.85,0.85}}
+\sphinxDeclareColorOption{RowOddColor}{{rgb}{1,1,1}}
 % now the colours defined with "sphinx" prefix in their names
 \newcommand*{\sphinxDeclareSphinxColorOption}[2]{%
    % set the initial default
diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py
index 7b21d6fd6cd..8424ac5ce4c 100644
--- a/sphinx/writers/latex.py
+++ b/sphinx/writers/latex.py
@@ -926,6 +926,14 @@ def visit_row(self, node: Element) -> None:
         self.table.col = 0
         _colsep = '' if self.table.booktabs else '|'
 
+        if self.builder.config.latex_zebra_stripes and not isinstance(node.parent, nodes.thead):
+            if self.table.row % 2 == 0:
+                self.body.append(
+                        '\\rowcolor{RowEvenColor}[\\dimexpr\\tabcolsep+0.1pt\\relax]')
+            else:
+                self.body.append(
+                        '\\rowcolor{RowOddColor}[\\dimexpr\\tabcolsep+0.1pt\\relax]')
+
         # fill columns if the row starts with the bottom of multirow cell
         while True:
             cell = self.table.cell(self.table.row, self.table.col)