Merge remote-tracking branch 'refs/remotes/origin/1.6-release' into 1.6-release

CHANGES

@@ -11,6 +11,9 @@ Incompatible changes
 Deprecated
 ----------
 
+* LaTeX ``\sphinxstylethead`` is deprecated at 1.6 and will be removed at 1.7.
+  Please move customization into new macro ``\sphinxstyletheadfamily``.
+
 Features added
 --------------
 
@@ -33,6 +36,7 @@ Bugs fixed
 * #3714: viewcode extension not taking ``highlight_code='none'`` in account
 * #3698: Moving :doc: to std domain broke backwards compatibility
 * #3633: misdetect unreferenced citations
+* LaTeX tables do not allow multiple paragraphs in a header cell
 
 Testing
 --------

doc/latex.rst

@@ -431,13 +431,18 @@ Let us now list some macros from the package file
 - more text styling commands: ``\sphinxstyle<bar>`` with ``<bar>`` one of
   ``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``,
   ``sidebartitle``, ``othertitle``, ``sidebarsubtitle``, ``thead``,
-  ``emphasis``, ``literalemphasis``, ``strong``, ``literalstrong``,
+  ``theadfamily``, ``emphasis``, ``literalemphasis``, ``strong``, ``literalstrong``,
   ``abbreviation``, ``literalintitle``.
 
   .. versionadded:: 1.5
      the new macros are wrappers of the formerly hard-coded ``\texttt``,
      ``\emph``, ... The default definitions can be found in
      :file:`sphinx.sty`.
+  .. versionadded:: 1.6
+     ``\sphinxstyletheadfamily`` which defaults to ``\sffamily`` and allows
+     multiple paragraphs in header cells of tables.
+  .. deprecated:: 1.6
+     macro ``\sphinxstylethead`` is deprecated at 1.6 and will be removed at 1.7.
 - a :dudir:`figure` may have an optional legend with arbitrary body
   elements: they are rendered in a ``sphinxlegend`` environment. The default
   definition issues ``\small``, and ends with ``\par``.

sphinx/texinputs/sphinx.sty

@@ -1402,7 +1402,17 @@
 \let\sphinxstylesidebartitle\sphinxstyletopictitle
 \protected\def\sphinxstyleothertitle     {\textbf}
 \protected\def\sphinxstylesidebarsubtitle #1{~\\\textbf{#1} \smallskip}
-\protected\def\sphinxstylethead          {\textsf}
+% \text.. commands do not allow multiple paragraphs
+\let\sphinxstylethead\empty
+\protected\def\sphinxstyletheadfamily {\ifx\sphinxstylethead\empty\sffamily\fi}
+\AtBeginDocument{\ifx\sphinxstylethead\empty\else
+\sphinxdeprecationwarning{\sphinxstylethead}{1.6}{1.7}{%
+    \string\sphinxstyletheadfamily\space replaces it
+    (it defaults to \string\sffamily) to allow use^^J
+    with multiple paragraphs. Backwards compatibility is maintained, but please^^J
+    move customization into \string\sphinxstyletheadfamily\space
+    in time for 1.7.^^J
+    And if you do it now, you will spare yourself this warning!}\fi}
 \protected\def\sphinxstyleemphasis       {\emph}
 \protected\def\sphinxstyleliteralemphasis#1{\emph{\sphinxcode{#1}}}
 \protected\def\sphinxstylestrong         {\textbf}

sphinx/writers/latex.py

@@ -1448,7 +1448,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
             if len(node) == 1 and isinstance(node[0], nodes.paragraph) and node.astext() == '':
                 pass
             else:
-                self.body.append('\\sphinxstylethead{\\relax ')
+                self.body.append('\\sphinxstylethead{\\sphinxstyletheadfamily ')
                 context = '\\unskip}\\relax ' + context
         if self.needs_linetrimming:
             self.pushbody([])

tests/test_build_latex.py

@@ -858,8 +858,9 @@ def test_latex_table_tabulars(app, status, warning):
     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)
+            '\\sphinxstylethead{\\sphinxstyletheadfamily \nheader1\n\\unskip}\\relax &'
+            '\\sphinxstylethead{\\sphinxstyletheadfamily \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)
@@ -930,15 +931,15 @@ def test_latex_table_longtable(app, status, warning):
     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'
-            '\\hline\n\\endfirsthead' in table)
+            '\\sphinxstylethead{\\sphinxstyletheadfamily \nheader1\n\\unskip}\\relax &'
+            '\\sphinxstylethead{\\sphinxstyletheadfamily \nheader2\n\\unskip}\\relax '
+            '\\\\\n\\hline\n\\endfirsthead' in table)
     assert ('\\multicolumn{2}{c}%\n'
             '{\\makebox[0pt]{\\sphinxtablecontinued{\\tablename\\ \\thetable{} -- '
             'continued from previous page}}}\\\\\n\\hline\n'
-            '\\sphinxstylethead{\\relax \nheader1\n\\unskip}\\relax &'
-            '\\sphinxstylethead{\\relax \nheader2\n\\unskip}\\relax \\\\\n'
-            '\\hline\n\\endhead' in table)
+            '\\sphinxstylethead{\\sphinxstyletheadfamily \nheader1\n\\unskip}\\relax &'
+            '\\sphinxstylethead{\\sphinxstyletheadfamily \nheader2\n\\unskip}\\relax '
+            '\\\\\n\\hline\n\\endhead' in table)
     assert ('\\hline\n\\multicolumn{2}{r}'
             '{\\makebox[0pt][r]{\\sphinxtablecontinued{Continued on next page}}}\\\\\n'
             '\\endfoot\n\n\\endlastfoot' in table)
@@ -995,9 +996,10 @@ def test_latex_table_complex_tables(app, status, warning):
     table = tables['grid 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 &'
-            '\\sphinxstylethead{\\relax \nheader3\n\\unskip}\\relax \\\\' in table)
+            '\\sphinxstylethead{\\sphinxstyletheadfamily \nheader1\n\\unskip}\\relax &'
+            '\\sphinxstylethead{\\sphinxstyletheadfamily \nheader2\n\\unskip}\\relax &'
+            '\\sphinxstylethead{\\sphinxstyletheadfamily \nheader3\n\\unskip}\\relax '
+            '\\\\' in table)
     assert ('\\hline\ncell1-1\n&\\sphinxmultirow{2}{5}{%\n\\begin{varwidth}[t]'
             '{\\sphinxcolwidth{1}{3}}\n'
             'cell1-2\n\\par\n' in table)