From b23036570c839337b90f86735da006b00ddb6731 Mon Sep 17 00:00:00 2001
From: jfbu <2589111+jfbu@users.noreply.github.com>
Date: Sun, 5 Dec 2021 15:43:16 +0100
Subject: [PATCH 1/3] Fix Multi-function declaration in Python domain has
 cramped spacing

Fix #9940

Avoid \pysiglinewithargsret tricks to get correct vertical spacing
in multiline declarations in case mark-up inserts a \phantomsection.

Activate such tricks also in \pysigline, but now with the
\phantomsection test.

Relates #7241, #8980, #8995
---
 sphinx/texinputs/sphinxlatexobjects.sty | 33 ++++++++++++++++++-------
 1 file changed, 24 insertions(+), 9 deletions(-)

diff --git a/sphinx/texinputs/sphinxlatexobjects.sty b/sphinx/texinputs/sphinxlatexobjects.sty
index e00881e53af..3deda5c9460 100644
--- a/sphinx/texinputs/sphinxlatexobjects.sty
+++ b/sphinx/texinputs/sphinxlatexobjects.sty
@@ -1,7 +1,7 @@
 %% MODULE RELEASE DATA AND OBJECT DESCRIPTIONS
 %
 % change this info string if making any custom modification
-\ProvidesFile{sphinxlatexobjects.sty}[2021/01/27 documentation environments]
+\ProvidesFile{sphinxlatexobjects.sty}[2021/12/05 documentation environments]
 
 % Provides support for this output mark-up from Sphinx latex writer:
 %
@@ -91,21 +91,36 @@
 % \relax only ends its "dimen" part
   \py@argswidth=\dimexpr\linewidth+\labelwidth\relax\relax
   \item[{\parbox[t]{\py@argswidth}{\raggedright #1\strut}}]
-% contrarily to \pysiglinewithargsret, we do not do this:
-%  \leavevmode\par\nobreak\vskip-\parskip\prevdepth\dp\strutbox
-% which would give exact vertical spacing if item parbox is multi-line,
-% as it affects negatively more common situation of \pysigline
-% used twice or more in a row for labels sharing common description,
-% due to bad interaction with the \phantomsection in the mark-up
+  \futurelet\sphinx@token\pysigline@preparevspace@i
 }
 \newcommand{\pysiglinewithargsret}[3]{%
   \settowidth{\py@argswidth}{#1\sphinxcode{(}}%
   \py@argswidth=\dimexpr\linewidth+\labelwidth-\py@argswidth\relax\relax
-  \item[{#1\sphinxcode{(}\py@sigparams{#2}{#3}}]
+  \item[{#1\sphinxcode{(}\py@sigparams{#2}{#3}\strut}]
+  \futurelet\sphinx@token\pysigline@preparevspace@i
+}
+\def\pysigline@preparevspace@i{%
+  \ifx\sphinx@token\@sptoken
+   \expandafter\pysigline@preparevspace@again
+   \else\expandafter\pysigline@preparevspace@ii
+  \fi
+}
+\@firstofone{\def\pysigline@preparevspace@again} {\futurelet\sphinx@token\pysigline@preparevspace@i}
+\long\def\pysigline@preparevspace@ii#1{%
+  \ifx\sphinx@token\bgroup\expandafter\@firstoftwo
+  \else
+    \ifx\sphinx@token\phantomsection
+    \else
 % 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}
+% It interacts badly with a follow-up \phantomsection hence the test above
+    \leavevmode\par\nobreak\vskip-\parskip\prevdepth\dp\strutbox
+    \fi
+    \expandafter\@secondoftwo
+  \fi
+  {{#1}}{#1}%
+}
 \newcommand{\pysigstartmultiline}{%
  \def\pysigstartmultiline{\vskip\smallskipamount\parskip\z@skip\itemsep\z@skip}%
  \edef\pysigstopmultiline

From 091c2de1a0d4bba55f806f7c48d586b488e08e30 Mon Sep 17 00:00:00 2001
From: jfbu <2589111+jfbu@users.noreply.github.com>
Date: Sun, 5 Dec 2021 15:52:14 +0100
Subject: [PATCH 2/3] Update CHANGES

---
 CHANGES | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGES b/CHANGES
index 2c41eb1f89c..b34a68378bd 100644
--- a/CHANGES
+++ b/CHANGES
@@ -39,6 +39,8 @@ Bugs fixed
 * #9925: LaTeX: prohibit also with ``'xelatex'`` line splitting at dashes of
   inline and parsed literals
 * #9944: LaTeX: extra vertical whitespace for some nested declarations
+* #9940: Multi-function declaration in Python domain has cramped vertical
+  spacing in latexpdf output
 
 Testing
 --------

From b902d855ba3d146aa811acbd5c05afc3ab1e5325 Mon Sep 17 00:00:00 2001
From: jfbu <2589111+jfbu@users.noreply.github.com>
Date: Fri, 10 Dec 2021 20:34:53 +0100
Subject: [PATCH 3/3] Update CHANGES for #9941

---
 CHANGES | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGES b/CHANGES
index b34a68378bd..d5664e5f42a 100644
--- a/CHANGES
+++ b/CHANGES
@@ -39,8 +39,8 @@ Bugs fixed
 * #9925: LaTeX: prohibit also with ``'xelatex'`` line splitting at dashes of
   inline and parsed literals
 * #9944: LaTeX: extra vertical whitespace for some nested declarations
-* #9940: Multi-function declaration in Python domain has cramped vertical
-  spacing in latexpdf output
+* #9940: LaTeX: Multi-function declaration in Python domain has cramped
+  vertical spacing in latexpdf output
 
 Testing
 --------