使用 Sphinx 更改 Latex Table 样式

Question

我正在使用 sphinx 生成我们公司的手册。在我们的遗留手册中，我们希望保留某种 table 风格。

table 样式由具有 header 和深绿色背景的 table 组成，然后有几行 light-green 背景行，然后是几行带有白色背景。

Sphinx 生成我的 LaTeX 输入文件，然后使用 PdfLatex 将其制作为 PDF。可以在 LaTeX table 以 :raw-role:.

开头之前包含 LaTeX 特定注释

输入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 环境的行为，以便 header 具有 dark-green 背景，下面的第一行具有 light-green 背景，其余行具有白色背景。

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

我发现有趣的是，对于狮身人面像 HTML 目标，通过使用包含 class firstRow 的改编 style.css 可以很容易地解决问题使用像 .. rst-class:: firstRow 这样的命令，其中 firstRow 表示具有浅绿色背景的 table 样式。

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

Answer 1

一般来说，LaTeX 的可定制性不如 HTML+CSS。

可能有一些包提供方便的界面来为 table 的前两行着色，不幸的是我不知道有哪个包可以在 [= 之前使用像 \firstRow 这样的宏79=]。 xcolor 包提供（如果加载选项 table）一个 \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，但当 \sphinxstylethead 将停止被 Sphinx 使用时，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 将具有 table 模板，允许更轻松地进行自定义，但与 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后期出现。

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

使用 Sphinx 更改 Latex Table 样式

Change Latex Table Style using Sphinx

latex

pdflatex

python-sphinx

pandoc