Changing latex table style using Sphinx
I use sphinx
to create guides for our company. In our legacy tutorials, we have a specific table style that we would like to keep.
The table style consists of tables with a header with a dark green background, then there are some light green background lines, and after that there are some lines with a white background.
sphinx
creates my LaTeX input files which are then generated in PDF using PdfLatex. It is possible to include special LaTeX comments before the LaTeX table starts with :raw-role:
.
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 converted to:
\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}
Now I need a command called \firstRow
that changes the behavior of the environment \tabulary
so that the header has a dark green background, the first line at the bottom has a light green background, and the rest of the lines have a white background.
If all else fails, it may be possible to automatically replace the contents of the cells in the RST file using a tool like pandoc
. For example, you can replace 1A
with :raw-role:'\background{green}' 1A
in an RST file and then convert it with sphinx
.
I was wondering that in the case of the sphinx HTML
problem, the problem can be easily solved by using an adapted style.css
containing class firstRow
, together with a type command .. rst-class:: firstRow
, where firstRow
is a table style with a single light green background.
Unfortunately, the LaTeX target is missing something similar to style.css
.
source to share
Generally speaking, LaTeX cannot be configured like HTML + CSS in any way.
There may be some package that provides a convenient interface for coloring the first two rows of a table, unfortunately, I don't know which one will work with a macro like \firstRow
in front of the table. The package xcolor
provides (if loaded with an options table) a command \rowcolors
, but it seems to be insufficient. It's easy to get the desired goal by manually marking up the LaTeX source, but it's more difficult to achieve just using a macro \firstRow
.
I ended up with a convoluted approach that 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 is \sphinxstylethead
deprecated and \sphinxstyletheadfamily
should be used instead . This means the above should be:
latex_elements = {
'preamble': r"""
\usepackage{colortbl}
\protected\def\sphinxstyletheadfamily {\cellcolor{green}\sffamily}
"""
}
The first version works with Sphinx 1.6, but fails 1.7 when \sphinxstylethead
Sphinx stops being used.
in the 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}
Change the colors to your liking, of course. You may need to pass a parameter like dvipsnames
in xcolor
, and then you can use things like \rowcolor[named]{ForestGreen}
.
Sphinx 1.6 will have table templates to make customization a bit easier, but it will still be a looooong path from what can be done in HTML + CSS.
For completeness, here's how to pass a parameter dvipsnames
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 above [named]
( \rowcolor[named]{ForestGreen}
) is not needed with xcolor
and I have not used it in 'preamble'
config here.
This is required if only the package is used color
, but Sphinx uses xcolor
it if available.
Loading is colortbl
not required if you also pass the option table
in, xcolor
and it is probably better if the need arises to use it xcolor
\rowcolors
at a later stage.
Merged cells from a grid table are tricky issues and Sphinx 1.6 will be much better than currently in this regard, however, in the current state of development, merged cells (multirow, multicolumn, or both) are set to simply ignore table color commands.
source to share