This is a combination of 2 + 28 + 7 + and some more commits...
* Cherry-pick: Add support for booktabs-style tables to LaTeX builder
* Cherry-pick: Add support for zebra-striped tables to LaTeX builder
Co-authored-by: Stefan Wiehler <stefan.wiehler@missinglinkelectronics.com>
Above work originally initiated by @sephalon (thanks!)
Development refactored and continued by @jfbu
* latex_table_style configuration, support booktabs, colorrows, borderless
Some details:
- Simplify a bit a conditional in the longtable template
This also puts the target for a longtable with a label but no caption
above the toprule for better hyperlinking (testing shows hyperlink
target can not end up alone at bottom of previous page).
- Extend allowed syntax for colour assignments via 'sphinxsetup'
- latex_table_style new configuration value and coloured rows
For the user interface I tried to look for inspiration in
https://docutils.sourceforge.io/docs/user/config.html#table-style
which mentions booktabs and borderless. They also mention
captionbelow which we can implement later, now that architecture
is here. They don't mention coloured rows.
- Test on our own document... looks fine!
- Work-around an incompatibility of \cline with row colours
- Reverse priority of classes to allow overruling booktabs by standard
after parsing source but before letting LaTeX writer act
- Closes#8220
Commit
https://github.com/sphinx-doc/sphinx/commit/bb859c669679baebd8cc8d10c99382478c0d1647
already improved a bit, this finishes it (as :rst:dir:`rst-class` was
actually not linking to anywhere).
- Let booktabs style defaults to *not* using \cmidrule. They actually
don't make much sense there, as all \hline's are removed.
- Add \sphinxnorowcolor which allows construct such as this one in
a tabularcolumns directive:
>{\columncolor{blue}\sphinxnorowcolor}
else LaTeX always overrides column colour by row colour
- Add TableMergeColorHeader, TableMergeColorOdd, TableMergeColorEven
so single-row merged cells can be styled especially
- Extend row colours to all header rows not only the first one
(all header rows will share same colour settings)
- Auto-adjust to a no '|'-colspec for optimal handling of merged cell
- Add \sphinxcolorblend
- Workaround LaTeX's \cline features and other grid tables matters
- Add \sphinxbuildwarning for important warnings
- Fix some white gaps in merged cells of tables with vlines and
colorrows
- Work around LaTeX's \cline serious deficiencies for complex grid
tables
This commit corrects \cline badly impacting vertical spacing and
making tables look even more cramped as they usually are in LaTeX
(although one sees it clearly only with \arrarrulewidth a bit more
than the LaTeX default of 0.4pt).
Most importantly this commit solves the problem that \cline's got
masked by colour panels from the row below.
- Update CHANGES for PR #10759
- Improve documentation of new latex_table_style regarding colours
This is cosmetic as the blank line starting varwidth environment used
for merged table cells in latex output changed nothing to PDF.
Nevertheless I extended a unit test to have a multi-paragraph merged
cell using varwidth. What is important is that \sphinxAtStartPar line
itself is never followed by blank line.
Refs: #6890
The comma character is not TeX-escaped because it is frequent in general
text and escaping it would make the LaTeX output larger for only dealing
with the problem of the LaTeX-ligature of ,, into a single character.
And one there is problem with the commas in options to Verbatim from
PygmentsBridge.
The hyphen character is escaped (not in ids and URIs!) to
\sphinxhyphen{} for both Unicode and non-Unicode engines. This is needed
to work around hyperref transforming -- and --- from section titles into
EN DASH resp. EM DASH in PDF bookmarks.
https://github.com/latex3/hyperref/issues/112
Note to expert LaTeX users: if Sphinx latex user with xelatex has
- turned off Smart Quotes for some reason,
- but does want TeX ligatures and thus overrode Sphinx
latex_elements['fontenc'] default (since #6888) to this effect,
then this should be added to LaTeX preamble:
\def\sphinxhyphen#1{-}% (\protected is now not needed)
\let\sphinxhyphenforbookmarks\sphinxhyphen
This compatibility is mainly re-instored for convenience of user to
style the fonts used for the caption, and also possibly influence the
horizontal position via "width" or "margin" option of caption package
(attention that caption package obeys the document class tacit "twoside"
option, so if left and right margins are not set-up to be the same,
positioning of caption will depend on parity of the page number).
Regarding vertical skips, for captions placed on top (which is the table
templates default and also the literalblockcappos default), this commit
ensures that the vertical spacing separating the caption last baseline
to the top of framing is governed by \sphinxbelowcaptionspace in all
these three cases: tabular(y), longtable, literal blocks; the "skip"
option of caption package is ignored for them.
The "skip" is obeyed for the spacing between an image and its caption,
which currently in Sphinx is always below the image (no customization of
the figure caption vertical placement is currently available).
If literalblockcappos is "b" (captions follow code-blocks), this commit
removes the caption-package added \abovecaptionskip, so that "skip" is
also ignored for code-blocks in this case. This looks better due to the
extra space already added by the framing of the code-block and achieves
same spacing as without caption package (presumably loaded mainly to
style the fonts used for the caption). However in future maybe caption's
package "skip" should be obeyed for "literalblock" caption type.
Fixes: 5520
This implementation in latex writer allows arbitrary columns to be
declared "stub columns". But currently Docutils option
``:stub-columns:`` only allows a number telling the how many initial
columns are "stub columns".
Jean-François BandStefan Wiehler
jfbu
Takeshi KOMIYA