使用Sphinx更改乳胶表样式

Question

I'm using sphinx to generate our company manuals. In our legacy manuals we have a certain table style, that we would like to keep.

The table style consists of tables having a header with dark green background, then there are several light-green background rows and after that several rows with a white background.

Sphinx generates my LaTeX input files, which are then made an PDF using PdfLatex. There is the possibility to include LaTeX specific comments right before the LaTeX table starts with :raw-role: .

The input RST file:

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

:raw-role:`\firstRow`   

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

Will be transformed into:

\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}

I'm now in need for a command called \\firstRow that modifies the behaviour of the \\tabulary environment, so that the header has a dark-green background, the first row beneath has a light-green background and the remaining rows having a white background.

If everything else fails there might be still the possibility to automatically replace the contents of the cells in the RST-File using a tool like pandoc . For example it might be possible to replace 1A by :raw-role:'\\background{green}' 1A in the RST file and then to transform it with sphinx .

I found it interesting that in case of the sphinx HTML target the problem can be very easily solved by using an adapted style.css containing the class firstRow together with a command like .. rst-class:: firstRow , where firstRow represents a table style with one light green background.

Unfortunately, the LaTeX target misses something similar to style.css .

Answer 1

Generally speaking, LaTeX is in no way as customizable as HTML+CSS.

There might be some package providing convenient interface to colorizing the first two rows of a table, unfortunately I am not aware of one which would work with a macro like \\firstRow before the table. The xcolor package provides (if loaded with option table) a \\rowcolors command, but it does not seem to suffice. It is easy to obtain the desired goal by manual mark-up of the LaTeX source, but it is more complicated achieving this solely using \\firstRow macro.

I ended up with a convoluted approach, which I tested on Sphinx 1.5.3.

in conf.py :

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

---

Edit: since Sphinx 1.6, \\sphinxstylethead is deprecated and \\sphinxstyletheadfamily should be used instead . This means that the above should now be:

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

The former version works with Sphinx 1.6 but will fail with 1.7 when \\sphinxstylethead will stopped being used by Sphinx.

---

in reST sources, something like this:

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


.. |x| raw:: latex

       \rowcolor{blue}

Of course change colours to your liking. You may need to pass an option like dvipsnames to xcolor package, and then you can use things like \\rowcolor[named]{ForestGreen} .

Sphinx 1.6 will have table templates allowing some easier customization but still this will be a looooong way from what one can do in HTML+CSS.

---

For completeness here is how to pass the dvipsnames option to 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}
""",
}

Also, the [named] I mentioned above ( \\rowcolor[named]{ForestGreen} ) is not needed with xcolor and I have not used it in 'preamble' config here.

It is needed when only color package is used, but Sphinx uses xcolor if available.

Loading colortbl is not needed if one also passes option table to xcolor , and is perhaps better way in case the need for use of xcolor 's \\rowcolors emerges at a later stage.

Merged cells from grid table cause arduous issues and Sphinx 1.6 will be much better than currently in this respect, however in current state of development, merged cells (multirow, multicolumn, or both) are set to simply ignore table colour commands.