Merge pull request #3504 from jfbu/fixtablevspaces

Fix #3491 via equalizing vertical spaces for latex tables of all types

sphinx/templates/latex/latex.tex_t

@@ -22,7 +22,6 @@
 <%= multilingual %>
 <%= fontpkg %>
 <%= fncychap %>
-<%= longtable %>
 \usepackage<%= sphinxpkgoptions %>{sphinx}
 <%= sphinxsetup %>
 <%= geometry %>

sphinx/templates/latex/longtable.tex_t

@@ -1,4 +1,4 @@
-\begin{savenotes}\begin{longtable}
+\begin{savenotes}\sphinxatlongtablestart\begin{longtable}
 <%- if table.align == 'center' -%>
   [c]
 <%- elif table.align == 'left' -%>
@@ -8,7 +8,7 @@
 <%- endif -%>
 <%= table.get_colspec() %>
 <%- if table.caption -%>
-\caption{<%= ''.join(table.caption) %>}<%= labels %>\\
+\caption{<%= ''.join(table.caption) %>\strut}<%= labels %>\\*[\sphinxlongtablecapskipadjust]
 <% endif -%>
 \hline
 <%= ''.join(table.header) %>
@@ -29,4 +29,4 @@
 <%= ''.join(table.caption_footnotetexts) %>
 <% endif -%>
 <%= ''.join(table.body) %>
-\end{longtable}\end{savenotes}
+\end{longtable}\sphinxatlongtableend\end{savenotes}

sphinx/templates/latex/tabular.tex_t

@@ -1,4 +1,4 @@
-\begin{savenotes}
+\begin{savenotes}\sphinxattablestart
 <% if table.align -%>
   <%- if table.align == 'center' -%>
   \centering
@@ -14,7 +14,7 @@
 \begin{threeparttable}
 \capstart\caption{<%= ''.join(table.caption) %>}<%= labels %>
 <% endif -%>
-\begin{tabular}<%= table.get_colspec() -%>
+\begin{tabular}[t]<%= table.get_colspec() -%>
 \hline
 <%= ''.join(table.header) %>
 <%- if table.caption_footnotetexts -%>
@@ -26,4 +26,4 @@
 \end{threeparttable}
 <%- endif %>
 \par
-\end{savenotes}
+\sphinxattableend\end{savenotes}

sphinx/templates/latex/tabulary.tex_t

@@ -1,4 +1,4 @@
-\begin{savenotes}
+\begin{savenotes}\sphinxattablestart
 <% if table.align -%>
   <%- if table.align == 'center' -%>
   \centering
@@ -14,7 +14,7 @@
 \begin{threeparttable}
 \capstart\caption{<%= ''.join(table.caption) %>}<%= labels %>
 <% endif -%>
-\begin{tabulary}{\linewidth}<%= table.get_colspec() -%>
+\begin{tabulary}{\linewidth}[t]<%= table.get_colspec() -%>
 \hline
 <%= ''.join(table.header) %>
 <%- if table.caption_footnotetexts -%>
@@ -26,4 +26,4 @@
 \end{threeparttable}
 <%- endif %>
 \par
-\end{savenotes}
+\sphinxattableend\end{savenotes}

sphinx/texinputs/sphinx.sty

@@ -6,7 +6,7 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2017/02/28 v1.6 LaTeX package (Sphinx markup)]
+\ProvidesPackage{sphinx}[2017/03/04 v1.6 LaTeX package (Sphinx markup)]
 
 % provides \ltx@ifundefined
 % (many packages load ltxcmds: graphicx does for pdftex and lualatex but
@@ -56,6 +56,40 @@
       #1\dimexpr\linewidth-\arrayrulewidth\relax-\tw@\tabcolsep-\arrayrulewidth\relax}}
 % using here T (for Tabulary) feels less of a problem than the X could be
 \newcolumntype{T}{J}%
+\RequirePackage{longtable}
+% For table captions.
+\RequirePackage{threeparttable}
+% fixing the LaTeX mess of vertical spaces with threeparttable and longtable
+% The user interface:
+\newcommand*\sphinxtablepre {0pt}%
+\newcommand*\sphinxtablepost{\medskipamount}%
+% as one can not use \baselineskip from inside longtable (it is zero there)
+% we need \sphinxbaselineskip, which defaults to \baselineskip
+\newcommand*\sphinxbelowcaptionspace{.5\sphinxbaselineskip}%
+\def\sphinxbaselineskip{\baselineskip}%
+% Helper macros, not a priori for user customization
+\def\sphinxatlongtablestart
+   {\par
+    \vskip\parskip
+    \vskip\dimexpr\sphinxtablepre\relax % adjust vertical position
+    \vbox{}% get correct baseline from above
+    \LTpre\z@skip\LTpost\z@skip % set to zero longtable's own skips
+    \edef\sphinxbaselineskip{\dimexpr\the\dimexpr\baselineskip\relax\relax}}%
+\def\sphinxatlongtableend{\prevdepth\z@\vskip\sphinxtablepost\relax}%
+% the longtable template inserts a \strut at caption's end
+\def\sphinxlongtablecapskipadjust
+   {\dimexpr-\dp\strutbox-\sphinxbaselineskip
+            +\sphinxbelowcaptionspace\relax}%
+% tabular(y) with or without threeparttable
+\def\sphinxattablestart
+   {\par
+    \vskip\dimexpr\sphinxtablepre\relax
+    \belowcaptionskip\sphinx@TPTbelowcaptionskip}%
+\let\sphinxattableend\sphinxatlongtableend
+% the tabular(y) templates use [t] vertical placement parameter
+\def\sphinx@TPTbelowcaptionskip
+   {\dimexpr-1.2\baselineskip % .2\baselineskip hardcoded in threeparttable
+            +\sphinxbelowcaptionspace\relax }%
 % varwidth is crucial for our handling of general contents in merged cells
 \RequirePackage{varwidth}
 % but addition of a compatibility patch with hyperref is needed
@@ -81,8 +115,6 @@
 % For highlighted code.
 \RequirePackage{fancyvrb}
 \fvset{fontsize=\small}
-% For table captions.
-\RequirePackage{threeparttable}
 % For hyperlinked footnotes in tables; also for gathering footnotes from
 % topic and warning blocks. Also to allow code-blocks in footnotes.
 \RequirePackage{footnotehyper-sphinx}

sphinx/writers/latex.py

@@ -72,7 +72,6 @@ DEFAULT_SETTINGS = {
     'polyglossia':     '',
     'fontpkg':         '\\usepackage{times}',
     'fncychap':        '\\usepackage[Bjarne]{fncychap}',
-    'longtable':       '\\usepackage{longtable}',
     'hyperref':        ('% Include hyperref last.\n'
                         '\\usepackage{hyperref}\n'
                         '% Fix anchor placement for figures with captions.\n'
@@ -360,7 +359,7 @@ class Table(object):
 
         * longtable
         * tabular
-        * taburary
+        * tabulary
         """
         if self.is_longtable():
             return 'longtable'

tests/test_build_latex.py

@@ -492,7 +492,8 @@ def test_footnote(app, status, warning):
     assert ('Information about VIDIOC\\_CROPCAP %\n'
             '\\begin{footnote}[6]\\sphinxAtStartFootnote\n'
             'footnote in table not in header\n%\n\\end{footnote}\n\\\\\n\\hline\n'
-            '\\end{tabulary}\n\\end{threeparttable}\n\\par\n\\end{savenotes}\n') in result
+            '\\end{tabulary}\n\\end{threeparttable}\n'
+            '\\par\n\\sphinxattableend\\end{savenotes}\n') in result
 
 
 @pytest.mark.sphinx('latex', testroot='footnotes')
@@ -520,7 +521,7 @@ def test_reference_in_caption_and_codeblock_in_footnote(app, status, warning):
     assert ('\\caption{footnote \\sphinxfootnotemark[7] '
             'in caption of normal table}\\label{\\detokenize{index:id28}}') in result
     assert ('\\caption{footnote \\sphinxfootnotemark[8] '
-            'in caption \\sphinxfootnotemark[9] of longtable}') in result
+            'in caption \\sphinxfootnotemark[9] of longtable\\strut}') in result
     assert ('\\endlastfoot\n%\n\\begin{footnotetext}[8]\\sphinxAtStartFootnote\n'
             'Foot note in longtable\n%\n\\end{footnotetext}\\ignorespaces %\n'
             '\\begin{footnotetext}[9]\\sphinxAtStartFootnote\n'
@@ -845,58 +846,62 @@ def test_latex_table_tabulars(app, status, warning):
 
     # simple_table
     table = tables['simple table']
-    assert ('\\begin{savenotes}\n\\centering\n'
-            '\\begin{tabulary}{\\linewidth}{|T|T|}' in table)
+    assert ('\\begin{savenotes}\\sphinxattablestart\n\\centering\n'
+            '\\begin{tabulary}{\\linewidth}[t]{|T|T|}' in table)
     assert ('\\hline\n'
             '\\sphinxstylethead{\\relax \nheader1\n\\unskip}\\relax &'
             '\\sphinxstylethead{\\relax \nheader2\n\\unskip}\\relax' in table)
     assert ('\\hline\ncell1-1\n&\ncell1-2\n\\\\' in table)
     assert ('\\hline\ncell2-1\n&\ncell2-2\n\\\\' in table)
     assert ('\\hline\ncell3-1\n&\ncell3-2\n\\\\' in table)
-    assert ('\\hline\n\\end{tabulary}\n\\par\n\\end{savenotes}' in table)
+    assert ('\\hline\n\\end{tabulary}\n\\par\n'
+            '\\sphinxattableend\\end{savenotes}' in table)
 
     # table having :widths: option
     table = tables['table having :widths: option']
-    assert ('\\begin{savenotes}\n\\centering\n'
-            '\\begin{tabular}{|\\X{30}{100}|\\X{70}{100}|}' in table)
-    assert ('\\hline\n\\end{tabular}\n\\par\n\\end{savenotes}' in table)
+    assert ('\\begin{savenotes}\\sphinxattablestart\n\\centering\n'
+            '\\begin{tabular}[t]{|\\X{30}{100}|\\X{70}{100}|}' in table)
+    assert ('\\hline\n\\end{tabular}\n\\par\n'
+            '\\sphinxattableend\\end{savenotes}' in table)
 
     # table having :align: option (tabulary)
     table = tables['table having :align: option (tabulary)']
-    assert ('\\begin{savenotes}\n\\raggedleft\n'
-            '\\begin{tabulary}{\\linewidth}{|T|T|}\n' in table)
-    assert ('\\hline\n\\end{tabulary}\n\\par\n\\end{savenotes}' in table)
+    assert ('\\begin{savenotes}\\sphinxattablestart\n\\raggedleft\n'
+            '\\begin{tabulary}{\\linewidth}[t]{|T|T|}\n' in table)
+    assert ('\\hline\n\\end{tabulary}\n\\par\n'
+            '\\sphinxattableend\\end{savenotes}' in table)
 
     # table having :align: option (tabular)
     table = tables['table having :align: option (tabular)']
-    assert ('\\begin{savenotes}\n\\raggedright\n'
-            '\\begin{tabular}{|\\X{30}{100}|\\X{70}{100}|}\n' in table)
-    assert ('\\hline\n\\end{tabular}\n\\par\n\\end{savenotes}' in table)
+    assert ('\\begin{savenotes}\\sphinxattablestart\n\\raggedright\n'
+            '\\begin{tabular}[t]{|\\X{30}{100}|\\X{70}{100}|}\n' in table)
+    assert ('\\hline\n\\end{tabular}\n\\par\n'
+            '\\sphinxattableend\\end{savenotes}' in table)
 
     # table with tabularcolumn
     table = tables['table with tabularcolumn']
-    assert ('\\begin{tabulary}{\\linewidth}{|c|c|}' in table)
+    assert ('\\begin{tabulary}{\\linewidth}[t]{|c|c|}' in table)
 
     # table having caption
     table = tables['table having caption']
-    assert ('\\begin{savenotes}\n\\centering\n'
+    assert ('\\begin{savenotes}\\sphinxattablestart\n\\centering\n'
             '\\begin{threeparttable}\n\\capstart\\caption{caption for table}'
             '\\label{\\detokenize{tabular:id1}}' in table)
-    assert ('\\begin{tabulary}{\\linewidth}{|T|T|}' in table)
+    assert ('\\begin{tabulary}{\\linewidth}[t]{|T|T|}' in table)
     assert ('\\hline\n\\end{tabulary}\n\\end{threeparttable}'
-            '\n\\par\n\\end{savenotes}' in table)
+            '\n\\par\n\\sphinxattableend\\end{savenotes}' in table)
 
     # table having verbatim
     table = tables['table having verbatim']
-    assert ('\\begin{tabular}{|*{2}{\\X{1}{2}|}}\n\\hline' in table)
+    assert ('\\begin{tabular}[t]{|*{2}{\\X{1}{2}|}}\n\\hline' in table)
 
     # table having problematic cell
     table = tables['table having problematic cell']
-    assert ('\\begin{tabular}{|*{2}{\\X{1}{2}|}}\n\\hline' in table)
+    assert ('\\begin{tabular}[t]{|*{2}{\\X{1}{2}|}}\n\\hline' in table)
 
     # table having both :widths: and problematic cell
     table = tables['table having both :widths: and problematic cell']
-    assert ('\\begin{tabular}{|\\X{30}{100}|\\X{70}{100}|}' in table)
+    assert ('\\begin{tabular}[t]{|\\X{30}{100}|\\X{70}{100}|}' in table)
 
 
 @pytest.mark.skipif(docutils.__version_info__ < (0, 13),
@@ -913,7 +918,8 @@ def test_latex_table_longtable(app, status, warning):
 
     # longtable
     table = tables['longtable']
-    assert ('\\begin{savenotes}\\begin{longtable}{|l|l|}\n\\hline' in table)
+    assert ('\\begin{savenotes}\\sphinxatlongtablestart'
+            '\\begin{longtable}{|l|l|}\n\\hline' in table)
     assert ('\\hline\n'
             '\\sphinxstylethead{\\relax \nheader1\n\\unskip}\\relax &'
             '\\sphinxstylethead{\\relax \nheader2\n\\unskip}\\relax \\\\\n'
@@ -930,7 +936,7 @@ def test_latex_table_longtable(app, status, warning):
     assert ('\ncell1-1\n&\ncell1-2\n\\\\' in table)
     assert ('\\hline\ncell2-1\n&\ncell2-2\n\\\\' in table)
     assert ('\\hline\ncell3-1\n&\ncell3-2\n\\\\' in table)
-    assert ('\\hline\n\\end{longtable}\\end{savenotes}' in table)
+    assert ('\\hline\n\\end{longtable}\\sphinxatlongtableend\\end{savenotes}' in table)
 
     # longtable having :widths: option
     table = tables['longtable having :widths: option']
@@ -947,8 +953,9 @@ def test_latex_table_longtable(app, status, warning):
 
     # longtable having caption
     table = tables['longtable having caption']
-    assert ('\\begin{longtable}{|l|l|}\n\\caption{caption for longtable}'
-            '\\label{\\detokenize{longtable:id1}}\\\\\n\\hline' in table)
+    assert ('\\begin{longtable}{|l|l|}\n\\caption{caption for longtable\\strut}'
+            '\\label{\\detokenize{longtable:id1}}'
+            '\\\\*[\sphinxlongtablecapskipadjust]\n\\hline' in table)
 
     # longtable having verbatim
     table = tables['longtable having verbatim']
@@ -977,7 +984,7 @@ def test_latex_table_complex_tables(app, status, warning):
 
     # grid table
     table = tables['grid table']
-    assert ('\\begin{tabulary}{\\linewidth}{|T|T|T|}' in table)
+    assert ('\\begin{tabulary}{\\linewidth}[t]{|T|T|T|}' in table)
     assert ('\\hline\n'
             '\\sphinxstylethead{\\relax \nheader1\n\\unskip}\\relax &'
             '\\sphinxstylethead{\\relax \nheader2\n\\unskip}\\relax &'
@@ -996,7 +1003,7 @@ def test_latex_table_complex_tables(app, status, warning):
 
     # complex spanning cell
     table = tables['complex spanning cell']
-    assert ('\\begin{tabulary}{\\linewidth}{|T|T|T|T|T|}' in table)
+    assert ('\\begin{tabulary}{\\linewidth}[t]{|T|T|T|T|T|}' in table)
     assert ('\\sphinxmultirow{3}{1}{%\n'
             '\\begin{varwidth}[t]{\\sphinxcolwidth{1}{5}}\n'
             'cell1-1\n\\par\n\\vskip-\\baselineskip\\strut\\end{varwidth}%\n'