LaTeX: fix 5.1.0 bugs related to topic and contents boxes (#11102)

* Fix #11095 (PDF wrong placement of shadow of topic boxes since 5.1.0) * Fix #11096 (LaTeX shadowsize regression at 5.1.0) * Fix #11099 (shadowrule legacy sphinxsetup key vanished at 5.1.0) * Fix #11101 (LaTeX div.topic_padding of sphinxsetup had wrong name) * Add some checks that various sphinxsetup keys do not break PDF build * Update LaTeX docs * Update CHANGES * Can not use :dudir:`contents` has it links to wrong place
sphinx-doc · Jan 6, 2023 · 7945aeb · 7945aeb
1 parent 77aaa86
commit 7945aeb
Show file tree

Hide file tree

Showing 5 changed files with 135 additions and 18 deletions.
diff --git a/CHANGES b/CHANGES
@@ -1,3 +1,20 @@
+Release 6.1.2 (in development)
+==============================
+
+Bugs fixed
+----------
+
+* #11101: LaTeX: ``div.topic_padding`` key of sphinxsetup documented at 5.1.0 was
+  implemented with name ``topic_padding``
+* #11099: LaTeX: ``shadowrule`` key of sphinxsetup causes PDF build to crash
+  since Sphinx 5.1.0
+* #11096: LaTeX: ``shadowsize`` key of sphinxsetup causes PDF build to crash
+  since Sphinx 5.1.0
+* #11095: LaTeX: shadow of :dudir:`topic` and contents_ boxes not in page
+  margin since Sphinx 5.1.0
+
+  .. _contents: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents
+
 Release 6.1.1 (released Jan 05, 2023)
 =====================================
 

diff --git a/doc/latex.rst b/doc/latex.rst
@@ -933,26 +933,43 @@ Do not use quotes to enclose values, whether numerical or strings.
 ``verbatimsep``
     The separation between code lines and the frame.
 
+    See :ref:`additionalcss` for its alias  ``pre_padding`` and
+    additional keys.
+
     Default: ``\fboxsep``
 
 ``verbatimborder``
-    The width of the frame around :rst:dir:`code-block`\ s.
+    The width of the frame around :rst:dir:`code-block`\ s.  See also
+    :ref:`additionalcss` for ``pre_border-width``.
 
     Default: ``\fboxrule``
 
 ``shadowsep``
-    The separation between contents and frame for :dudir:`contents` and
+    The separation between contents and frame for contents_ and
     :dudir:`topic` boxes.
 
+    See :ref:`additionalcss` for the alias ``div.topic_padding``.
+
     Default: ``5pt``
 
+    .. _contents: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents
+
 ``shadowsize``
     The width of the lateral "shadow" to the right and bottom.
 
+    See :ref:`additionalcss` for ``div.topic_box-shadow`` which allows to
+    configure separately the widths of the vertical and horizontal shadows.
+
     Default: ``4pt``
 
+    .. versionchanged:: 6.1.2
+       Fixed a regression introduced at `5.1.0` which modified unintentionally
+       the width of topic boxes and worse had made usage of this key break PDF
+       builds.
+
 ``shadowrule``
-    The width of the frame around :dudir:`topic` boxes.
+    The width of the frame around :dudir:`topic` boxes.  See also
+    :ref:`additionalcss` for ``div.topic_border-width``.
 
     Default: ``\fboxrule``
 
@@ -987,7 +1004,9 @@ Do not use quotes to enclose values, whether numerical or strings.
     Default: ``{rgb}{1,1,1}`` (white)
 
 |warningborders|
-    The width of the frame.
+    The width of the frame.  See
+    :ref:`additionalcss` for keys allowing to configure separately each
+    border width.
 
     Default: ``1pt``
 
@@ -1146,6 +1165,10 @@ Options for topic boxes:
   | ``div.topic_padding-left``,
   | ``div.topic_padding``,
     again this is a single dimension.  Its default is ``5pt``.
+
+  .. versionchanged:: 6.1.2
+     These keys had been implemented at 5.1.0 without ``div.`` in
+     their names.
 - | ``div.topic_border-top-left-radius``,
   | ``div.topic_border-top-right-radius``,
   | ``div.topic_border-bottom-right-radius``,
@@ -1439,7 +1462,7 @@ Environments
 
   .. versionadded:: 6.1.0
 
-- The :dudir:`contents` directive (with ``:local:`` option) and the
+- The contents_ directive (with ``:local:`` option) and the
   :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``.
 
   .. versionadded:: 1.4.2

diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty
@@ -6,7 +6,7 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2023/01/03 v6.1.0 LaTeX package (Sphinx markup)]
+\ProvidesPackage{sphinx}[2023/01/06 v6.1.2 LaTeX package (Sphinx markup)]
 
 % provides \ltx@ifundefined
 % (many packages load ltxcmds: graphicx does for pdftex and lualatex but
@@ -436,7 +436,7 @@ will be set to white}%
 \let\spx@topic@border@bottom\spx@topic@border@top
 \let\spx@topic@border@left  \spx@topic@border@top
 \expandafter\let\expandafter\KV@sphinx@shadowrule
-                            \csname KV@sphinx@topic_border-width\endcsname
+                            \csname KV@sphinx@div.topic_border-width\endcsname
 \newif\ifspx@topic@border@open % defaults to false (legacy)
 \define@key{sphinx}{div.topic_box-decoration-break}%
            {\begingroup\edef\spx@tempa{#1}\expandafter\endgroup
@@ -445,11 +445,13 @@ will be set to white}%
             \else\spx@topic@border@opentrue\fi}%
 %
 % MEMO: \sphinxshadowsep not used anywhere anymore in code base and to be removed
-\define@key{sphinx}{topic_padding-top}{\def\spx@topic@padding@top{#1}}
-\define@key{sphinx}{topic_padding-right}{\def\spx@topic@padding@right{#1}}
-\define@key{sphinx}{topic_padding-bottom}{\def\spx@topic@padding@bottom{#1}}
-\define@key{sphinx}{topic_padding-left}{\def\spx@topic@padding@left{#1}}
-\define@key{sphinx}{topic_padding}{%
+% Sadly the 5.1.0 definitions forgot the "div." part of the key names
+% Fixed at 6.1.2
+\define@key{sphinx}{div.topic_padding-top}{\def\spx@topic@padding@top{#1}}
+\define@key{sphinx}{div.topic_padding-right}{\def\spx@topic@padding@right{#1}}
+\define@key{sphinx}{div.topic_padding-bottom}{\def\spx@topic@padding@bottom{#1}}
+\define@key{sphinx}{div.topic_padding-left}{\def\spx@topic@padding@left{#1}}
+\define@key{sphinx}{div.topic_padding}{%
    \def\spx@topic@padding@top   {#1}%
    \let\spx@topic@padding@right \spx@topic@padding@top
    \let\spx@topic@padding@bottom\spx@topic@padding@top
@@ -460,7 +462,7 @@ will be set to white}%
 \let\spx@topic@padding@bottom\spx@topic@padding@top
 \let\spx@topic@padding@left  \spx@topic@padding@top
 \expandafter\let\expandafter\KV@sphinx@shadowsep
-                            \csname KV@sphinx@topic_padding\endcsname
+                            \csname KV@sphinx@div.topic_padding\endcsname
 %
 \define@key{sphinx}{div.topic_border-top-left-radius}{\def\spx@topic@radius@topleft{#1}}
 \define@key{sphinx}{div.topic_border-top-right-radius}{\def\spx@topic@radius@topright{#1}}
@@ -504,14 +506,15 @@ will be set to white}%
 \spx@topic@box@shadow@setter 4pt 4pt {} \@nnil
 % Suport for legacy shadowsize, the \sphinxshadowsize \dimen register
 % is not used anymore and should not even be allocated in future
+% This definition was broken at 5.1.0 and fixed at 6.1.2
 \define@key{sphinx}{shadowsize}{%
   \edef\spx@topic@shadow@xoffset{\number\dimexpr#1\relax sp}%
   \let\spx@topic@shadow@yoffset\spx@topic@shadow@xoffset
   \ifdim\spx@topic@shadow@xoffset=\z@
-      \spx@topic@box@withshadowtrue
+      \spx@topic@withshadowfalse
   \else
-      \spx@topic@box@withshadowfalse
-      \spx@topic@box@shadow@insetfalse
+      \spx@topic@withshadowtrue
+      \spx@topic@insetshadowfalse
   \fi
 }%
 \definecolor{sphinxTopicBorderColor}{rgb}{0,0,0}

diff --git a/sphinx/texinputs/sphinxlatexshadowbox.sty b/sphinx/texinputs/sphinxlatexshadowbox.sty
@@ -1,7 +1,7 @@
 %% TOPIC AND CONTENTS BOXES
 %
 % change this info string if making any custom modification
-\ProvidesFile{sphinxlatexshadowbox.sty}[2022/07/03 sphinxShadowBox]
+\ProvidesFile{sphinxlatexshadowbox.sty}[2023/01/06 sphinxShadowBox]
 
 % Provides support for this output mark-up from Sphinx latex writer:
 %
@@ -89,7 +89,9 @@
         \fi
   \ifspx@topic@withshadow
    \ifspx@topic@insetshadow\else
-    \ifdim\spx@topic@shadow@xoffset>\z@\hskip\spx@topic@shadow@xoffset\relax
+    % A strangely unnoticed 5.1.0 breakage of the legacy placement of the
+    % shadow was caused by a lacking minus sign here, fixed at 6.1.2
+    \ifdim\spx@topic@shadow@xoffset>\z@\hskip-\spx@topic@shadow@xoffset\relax
     \fi
    \fi
   \fi

diff --git a/tests/roots/test-root/conf.py b/tests/roots/test-root/conf.py
@@ -38,6 +38,78 @@
 html_context = {'hckey': 'hcval', 'hckey_co': 'wrong_hcval_co'}
 
 latex_additional_files = ['svgimg.svg']
+# some random pdf layout parameters to check they don't break build
+latex_elements = {
+    'sphinxsetup': """
+  verbatimwithframe,
+  verbatimwrapslines,
+  verbatimforcewraps,
+  verbatimmaxoverfull=1,
+  verbatimmaxunderfull=5,
+  verbatimhintsturnover=true,
+  verbatimcontinuesalign=l,
+  VerbatimColor={RGB}{242,242,242},
+  VerbatimBorderColor={RGB}{32,32,32},
+  VerbatimHighlightColor={RGB}{200,200,200},
+  pre_box-decoration-break=slice,
+  pre_border-top-left-radius=20pt,
+  pre_border-top-right-radius=0pt,
+  pre_border-bottom-right-radius=20pt,
+  pre_border-bottom-left-radius=0pt,
+  verbatimsep=1pt,
+  pre_padding=5pt,% alias to verbatimsep
+  pre_border-top-width=5pt,
+  pre_border-right-width=10pt,
+  pre_border-bottom-width=15pt,
+  pre_border-left-width=20pt,
+  pre_border-width=3pt,% overrides all previous four
+  verbatimborder=2pt,% alias to pre_border-width
+%
+  shadowrule=1pt,
+  shadowsep=10pt,
+  shadowsize=10pt,
+  div.topic_border-width=2pt,% alias to shadowrule 
+  div.topic_padding=6pt,% alias to shadowsep
+  div.topic_box-shadow=5pt,% overrides/alias shadowsize
+%
+  noteBorderColor={RGB}{204,204,204},
+  hintBorderColor={RGB}{204,204,204},
+  importantBorderColor={RGB}{204,204,204},
+  tipBorderColor={RGB}{204,204,204},
+%
+  noteborder=5pt,
+  hintborder=5pt,
+  importantborder=5pt,
+  tipborder=5pt,
+%
+  warningborder=3pt,
+  cautionborder=3pt,
+  attentionborder=3pt,
+  errorborder=3pt,
+%
+  dangerborder=3pt,
+  div.danger_border-width=10pt,
+  div.danger_background-TeXcolor={rgb}{0,1,0},
+  div.danger_border-TeXcolor={rgb}{0,0,1},
+  div.danger_box-shadow=20pt -20pt,
+  div.danger_box-shadow-TeXcolor={rgb}{0.5,0.5,0.5},
+%
+  warningBorderColor={RGB}{255,119,119},
+  cautionBorderColor={RGB}{255,119,119},
+  attentionBorderColor={RGB}{255,119,119},
+  dangerBorderColor={RGB}{255,119,119},
+  errorBorderColor={RGB}{255,119,119},
+  warningBgColor={RGB}{255,238,238},
+  cautionBgColor={RGB}{255,238,238},
+  attentionBgColor={RGB}{255,238,238},
+  dangerBgColor={RGB}{255,238,238},
+  errorBgColor={RGB}{255,238,238},
+%
+  TableRowColorHeader={rgb}{0,1,0},
+  TableRowColorOdd={rgb}{0.5,0,0},
+  TableRowColorEven={rgb}{0.1,0.1,0.1},
+""",
+}
 
 coverage_c_path = ['special/*.h']
 coverage_c_regexes = {'function': r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'}