使用 Sphinx 更改 Latex 表格样式

Question

我正在使用sphinx 来生成我们的公司手册。在我们的旧手册中，我们希望保留某种表格样式。

表格样式由具有深绿色背景标题的表格组成，然后是几行浅绿色背景行，然后是几行白色背景。

Sphinx 生成我的 LaTeX 输入文件，然后使用 PdfLatex 将其制成 PDF。可以在 LaTeX 表以 :raw-role: 开头之前包含 LaTeX 特定的 cmets。

输入RST文件：

.. role:: raw-role(raw)
   :format: latex

:raw-role:`\firstRow`   

=== === ===
 A   B   C
=== === ===
1A   1B  1C
2A   2B  2C
3A   3B  3C
4A   4B  4C
=== === ===

会变成：

\firstRow

\noindent\begin{tabulary}{\linewidth}{|L|L|L|}
\hline
\sphinxstylethead{\relax 
A
\unskip}\relax &\sphinxstylethead{\relax 
B
\unskip}\relax &\sphinxstylethead{\relax 
C
\unskip}\relax \\
\hline
1A
&
1B
&
1C
\\
\hline
2A
&
2B
&
2C
\\
\hline
3A
&
3B
&
3C
\\
\hline
4A
&
4B
&
4C
\\
\hline\end{tabulary}

我现在需要一个名为 \firstRow 的命令，它可以修改 \tabulary 环境的行为，使标题具有深绿色背景，下面的第一行具有浅绿色背景，而其余行具有白色背景。

如果其他一切都失败了，仍然有可能使用pandoc 之类的工具自动替换 RST 文件中单元格的内容。 例如，可以将 RST 文件中的1A 替换为:raw-role:'\background{green}' 1A，然后将其转换为sphinx。

我发现有趣的是，如果是 sphinx HTML 目标，则可以通过使用包含 firstRow 类的改编 style.css 以及类似 .. rst-class:: firstRow 的命令来轻松解决问题，其中 firstRow表示具有一个浅绿色背景的表格样式。

不幸的是，LaTeX 目标错过了类似于 style.css 的内容。

Answer 1

一般来说，LaTeX 不像 HTML+CSS 那样可定制。

可能有一些包提供了方便的界面来为表格的前两行着色，不幸的是我不知道有一个包可以在表格之前使用像\firstRow 这样的宏。 xcolor 包提供（如果加载了选项表）\rowcolors 命令，但似乎还不够。通过手动标记 LaTeX 源代码很容易获得所需的目标，但仅使用 \firstRow 宏来实现这一目标更加复杂。

我最终采用了一种复杂的方法，并在 Sphinx 1.5.3 上进行了测试。

在conf.py:

latex_elements = {
    'preamble': r"""
\usepackage{colortbl}
\protected\def\sphinxstylethead {\cellcolor{green}\textsf}
"""
}

---

编辑：自 Sphinx 1.6 起，\sphinxstylethead 已弃用，\sphinxstyletheadfamily should be used instead。这意味着上面现在应该是：

latex_elements = {
    'preamble': r"""
\usepackage{colortbl}
\protected\def\sphinxstyletheadfamily {\cellcolor{green}\sffamily}
"""
}

以前的版本适用于 Sphinx 1.6，但在 Sphinx 停止使用 \sphinxstylethead 时会在 1.7 中失败。

---

在 reST 源中，如下所示：

======  === ===
  A      B   C
======  === ===
|x| 1A   1B  1C
2A       2B  2C
3A       3B  3C
4A       4B  4C
======  === ===


.. |x| raw:: latex

       \rowcolor{blue}

当然可以根据自己的喜好更改颜色。您可能需要将dvipsnames 之类的选项传递给xcolor 包，然后您可以使用\rowcolor[named]{ForestGreen} 之类的东西。

Sphinx 1.6 将具有表格模板，允许更轻松地进行自定义，但这仍然是一种与 HTML+CSS 相比的方式。

---

为了完整起见，这里是如何将dvipsnames 选项传递给xcolor：

latex_elements = {
    'passoptionstopackages': '\\PassOptionsToPackage{dvipsnames}{xcolor}',

    'preamble': r"""
\usepackage{colortbl}
% for Sphinx 1.5.x (1.6 ok, but 1.7 not):
\protected\def\sphinxstylethead {\cellcolor{Aquamarine}\textsf}
% better to use rather this with Sphinx 1.6 and mandatory if Sphinx 1.7:
% \protected\def\sphinxstyletheadfamily {\cellcolor{Aquamarine}\sffamily}
""",
}

另外，xcolor 不需要我上面提到的[named] (\rowcolor[named]{ForestGreen})，我也没有在 'preamble' 配置中使用它。

当仅使用 color 包时需要它，但 Sphinx 使用 xcolor（如果可用）。

如果还可以将选项table 传递给xcolor，则不需要加载colortbl，如果在稍后阶段需要使用xcolor 的\rowcolors，这可能是更好的方法。

网格表中的合并单元格会导致棘手的问题，Sphinx 1.6 在这方面会比目前好得多，但是在当前的开发状态下，合并单元格（多行、多列或两者）被设置为简单地忽略表格颜色命令。