使用Sphinx

Question

我使用sphinx生成公司手册。在我们的遗留手册中，我们有一定的桌面风格，我们希望保留。

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

Sphinx生成我的LaTeX输入文件，然后使用PdfLatex将其制作为PDF。在LaTeX表以: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环境的行为，以便标题有一个深绿色的背景，下面的第一行有一个浅绿色背景和剩余的行具有白色背景。

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

我觉得有趣的是，在sphinx HTML目标的情况下，通过使用包含类style.css的适应firstRow以及{{1}之类的命令，可以很容易地解决问题。 1}}，其中.. rst-class:: firstRow表示具有浅绿色背景的表格样式。

不幸的是，LaTeX目标错过了与firstRow类似的东西。

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，但当{2}将停止被Sphinx使用时，将失败1.7。

在reST来源中，

是这样的：

\sphinxstylethead

当然根据自己的喜好改变颜色。您可能需要将====== === === A B C ====== === === |x| 1A 1B 1C 2A 2B 2C 3A 3B 3C 4A 4B 4C ====== === === .. |x| raw:: latex \rowcolor{blue} 这样的选项传递给dvipsnames包，然后您可以使用xcolor之类的内容。

Sphinx 1.6将拥有表格模板，允许更容易的自定义，但这仍然是一个与HTML + CSS中的一致的方式。

为了完整起见，这里是如何将\rowcolor[named]{ForestGreen}选项传递给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} """, } 不需要上面提到的[named] \rowcolor[named]{ForestGreen}，我在xcolor配置中没有使用它。

仅使用'preamble'包时 ，但如果可用，Sphinx会使用color。

如果还将选项xcolor传递给colortbl，则不需要加载table，如果需要使用xcolor＆＃39; s xcolor会在稍后阶段出现。

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