New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
LaTeX: support for booktabs-style and zebra-striped tables #10759
Commits on Aug 6, 2022
-
Add support for booktabs-style tables to LaTeX builder
Render tables without vertical rules and horizontal rules of varying thickness (with additional space above and below) using the booktabs package. This is a rebase of original commit which was on master branch prior to 2.1 release. In this rebase the \RequirePackage{booktabs} has been removed from sphinx.sty, as it has to be conditional on latex_booktabs (or whatever its name will be) configuration option, and will be repositioned in a subsequent commit.
Commits on Aug 7, 2022
Commits on Aug 8, 2022
-
Cherry-pick: Add support for zebra-striped tables to LaTeX builder
Render tables with alternating background colors for even and odd rows (so called "zebra striping").
-
Commits on Aug 14, 2022
-
latex_table_style configuration, support booktabs, colorrows, borderless
This is a combination of 28 commits... - 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). - Refactor and trim doc about LaTeX tables... to make room for more, later - Enlarge allowed syntax for colour assignments via 'sphinxsetup' - latex_table_style new configuration value and coloured rows For the user interface 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! - Update LaTeX table tests and templates Modify longtable templates to put LaTeX macros each on its line Table body insertion without removing previous EOL may give output which contain some empty lines but longtable defines \par token to be same as \empty. - Work-around an incompatibility of \cline with row colours, improve docs - Reverse priority of classes to allow overruling booktabs by standard after parsing source but before letting LaTeX writer act - Closes sphinx-doc#8220 Commit sphinx-doc@bb859c6 already improved a bit, this finishes it (as :rst:dir:`rst-class` was actually not linking to anywhere). - Update CHANGES for PR sphinx-doc#10759 - Let booktabs style defaults to *not* using \cmidrule. They actually don't make much sense there, as all \hline's are removed. - Enhance customizability at LaTeX code level (via code executed prior to table rendering, e.g. from a container class environment). - Patch booktabs \cmidrule, as if it used via \sphinxcline, there is a vertical space problem in case of there are two in the same row due to booktabs \futurelet not knowing \sphinxcline - 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 - Needed to also detect if a '|' is in tabularcolumns, tests updated - Fix refactoring in this series which broke table.colsep update - Add test which would have shown regression regarding table.colsep - Fix another regression regarding \sphinxcline + booktabs Can not add test for that, because it shows only after PDF build. - Final testing and code comments update
Commits on Aug 17, 2022
-
Workaround LaTeX's \cline features and other grid tables matters
This is a combination of 7 commits. - LaTeX command \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. - Fix regression from a \kern erroneous displacement; and other problems with merged cells and colours - LaTeX code comments and rearrangements of code order
-
Add booktabscolorizegaps sphinxsetup option
Perhaps this should actually be default behaviour for booktabs + colorrows at sphinx-doc#10759 ? Then it would not be an option at all and would not need documentation. On seeing output in our own document PDF, I find this rather nice actually. Perhaps it is indeed better than leaving the white gaps.
Commits on Aug 18, 2022
-
\sphinxbooktabsspecialruleoverhang for perfect same-colour-joins
This avoids at high level of zooming, depending on PDF viewers a line of non-coloured or anti-aliased pixels at the joining of two rectangles of same colour due to rounding effects. Nota Bene: the background colour panels extend a tiny bit beyond left and right limits of table due to another parameter used for similar reasons motivated by horizontally merged cells: \sphinxcolorpanelextraoverhang (also defaulting to 0.1pt) Relates sphinx-doc#10759 This is a combination of 4 commits - some code comments for future edit if this is to be used upstream - safer usage of \spx@table@crazyfork in case #1 turns out to be \par - add \sphinxifthistablewithcolorrowsTF to simplify coding - \sphinxbooktabsspecialruleoverhang for perfect same-colour-joins
Commits on Aug 19, 2022
-
Suppress expression of header row color in longtable continuations
One reason in particular is that the colour is applied only up to the long table width, but the continuation hints may be larger than this width (but this width is hidden to not influence the table cells layout).
Commits on Aug 20, 2022
-
Rename some macros to use no @, make colorgaps true per default
This way, custom user replacement code for \sphinxbooktabs{top,mid,bottom}rule is relatively painless to inject in preamble or via container class. Also, it was needed to add some LaTeX code to the longtable template in order to avoid a colour-related problem with \sphinxbottomrule. The 'sphinxsetup' key now named booktabscolorgaps defaults to being true and is left only as a way to provide an easy "turn-off" if the issue with the longtable colours after the mid rule and above the bottom rule is blocking to some. But a priori I envision at 6.0.0 to simply remove this undocumented option as the said issue is not serious and more to be considered a fact-of-life. Besides using booktabs+colorrows is strictly opt-in at this time. I considered various LaTeX ways around this longtable thing (it constructs headers and footers once and for all, one can not let them depend on some "dynamic" context; there is no easy way for a body row to know it is first on the page after header, and anyway would require adding mark-up or considerably complicate the \everycr)) but none of them are even remotely reasonable. Also, a non-documented booktabsnogaps 'sphinxsetup' key has been added: it suppresses all the extra spacing booktabs injects around its top, mid, and bottom rules. Will solve the booktabs+colorrows+longtable conundrum from previous paragraph.
-
Move \rownum reset away from longtable template into afterendhook
This is better not to overload our template. Besides it makes it easier for user to use another longtable template.
Commits on Sep 24, 2022
Commits on Sep 25, 2022
Commits on Oct 5, 2022
Commits on Oct 6, 2022
-
Improve documentation of new latex_table_style regarding colours
Remove in passing a note from latex.rst which was of no real use to Sphinx LaTeX users.