Merge pull request #8997 from jfbu/latex_pysigline

LaTeX: improve behavious of `\pysigline` and `\pysiglinewithargsret` in case of multi-line signature

CHANGES

@@ -92,6 +92,7 @@ Bugs fixed
 * #8915: html theme: The translation of sphinx_rtd_theme does not work
 * #8342: Emit a warning if a unknown domain is given for directive or role (ex.
   ``:unknown:doc:``)
+* #7241: LaTeX: No wrapping for ``cpp:enumerator``
 * #8711: LaTeX: backticks in code-blocks trigger latexpdf build warning (and font
   change) with late TeXLive 2019
 * #8253: LaTeX: Figures with no size defined get overscaled (compared to images
@@ -101,6 +102,9 @@ Bugs fixed
   Pygments style
 * #8925: LaTeX: 3.5.0 ``verbatimmaxunderfull`` setting does not work as
   expected
+* #8980: LaTeX: missing line break in ``\pysigline``
+* #8995: LaTeX: legacy ``\pysiglinewithargsret`` does not compute correctly
+  available  horizontal space and should use a ragged right style
 * #8911: C++: remove the longest matching prefix in
   :confval:`cpp_index_common_prefix` instead of the first that matches.
 * C, properly reject function declarations when a keyword is used

sphinx/texinputs/sphinxlatexobjects.sty

@@ -58,11 +58,14 @@
 
 % {fulllineitems} is the main environment for object descriptions.
 %
-\newcommand{\py@itemnewline}[1]{%
-  \kern\labelsep
-  \@tempdima\linewidth
-  \advance\@tempdima \labelwidth\makebox[\@tempdima][l]{#1}%
-  \kern-\labelsep
+% With 4.0.0 \pysigline (and \pysiglinewithargsret), used in a fulllineitems
+% environment the #1 will already be of the width which is computed here, i.e.
+% the available width on line, so the \makebox becomes a bit superfluous
+\newcommand{\py@itemnewline}[1]{% macro used as \makelabel in fulllineitems
+% Memo: this presupposes \itemindent is 0pt
+  \kern\labelsep  % because \@labels core latex box does \hskip-\labelsep
+  \makebox[\dimexpr\linewidth+\labelwidth\relax][l]{#1}%
+  \kern-\labelsep % because at end of \@labels box there is \hskip\labelsep
 }
 
 \newenvironment{fulllineitems}{%
@@ -76,13 +79,27 @@
 %
 \newlength{\py@argswidth}
 \newcommand{\py@sigparams}[2]{%
-  \parbox[t]{\py@argswidth}{#1\sphinxcode{)}#2}}
-\newcommand{\pysigline}[1]{\item[{#1}]}
+  % The \py@argswidth has been computed in \pysiglinewithargsret to make this
+  % occupy full available width on line.
+  \parbox[t]{\py@argswidth}{\raggedright #1\sphinxcode{)}#2\strut}%
+  % final strut is to help get correct vertical separation in case of multi-line
+  % box with the item contents. 
+}
+\newcommand{\pysigline}[1]{%
+% the \py@argswidth is available we use it despite its name (no "args" here)
+% the \relax\relax is because \py@argswidth is a "skip" variable and the first
+% \relax only ends its "dimen" part
+  \py@argswidth=\dimexpr\linewidth+\labelwidth\relax\relax
+  \item[{\parbox[t]{\py@argswidth}{\raggedright #1\strut}}]
+% this strange incantation is because at its root LaTeX in fact did not
+% imagine a multi-line label, it is always wrapped in a horizontal box at core
+% LaTeX level and we have to find tricks to get correct interline distances.
+  \leavevmode\par\nobreak\vskip-\parskip\prevdepth\dp\strutbox}
 \newcommand{\pysiglinewithargsret}[3]{%
   \settowidth{\py@argswidth}{#1\sphinxcode{(}}%
-  \addtolength{\py@argswidth}{-2\py@argswidth}%
-  \addtolength{\py@argswidth}{\linewidth}%
-  \item[{#1\sphinxcode{(}\py@sigparams{#2}{#3}}]}
+  \py@argswidth=\dimexpr\linewidth+\labelwidth-\py@argswidth\relax\relax
+  \item[{#1\sphinxcode{(}\py@sigparams{#2}{#3}}]
+  \leavevmode\par\nobreak\vskip-\parskip\prevdepth\dp\strutbox}
 \newcommand{\pysigstartmultiline}{%
  \def\pysigstartmultiline{\vskip\smallskipamount\parskip\z@skip\itemsep\z@skip}%
  \edef\pysigstopmultiline