LaTeX: make contents, topic, and sidebar separately customizable

CHANGES.rst

@@ -28,6 +28,9 @@ Features added
 
 * #11328: Mention evaluation of templated content during production of static
   output files.
+* #12704: LaTeX: make :dudir:`contents <table-of-contents>`, :dudir:`topic`,
+  and :dudir:`sidebar` directives separately customizable for PDF output.
+  Patch by Jean-François B.
 * #12474: Support type-dependent search result highlighting via CSS.
   Patch by Tim Hoffmann.
 

sphinx/texinputs/sphinx.sty

@@ -9,7 +9,7 @@
 % by the Sphinx LaTeX writer.
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2024/07/01 v7.4.0 Sphinx LaTeX package (sphinx-doc)]
+\ProvidesPackage{sphinx}[2024/07/28 v8.1.0 Sphinx LaTeX package (sphinx-doc)]
 
 % provides \ltx@ifundefined
 % (many packages load ltxcmds: graphicx does for pdftex and lualatex but
@@ -350,6 +350,11 @@
 % is handled as an admonition with the same customizability. And the
 % todo directive.
 %
+% 8.1.0: style separately topic, contents, and sidebar directives
+% ---------------------------------------------------------------
+%
+% And use some title row also for them (but without icon, per default).
+%
 \def\spxstring@none{none}
 \def\spxstring@clone{clone}
 %
@@ -397,6 +402,16 @@
 %          macro prefix   option prefix   legacy option    init value
 \spx@tempa{spx@pre@}      {pre_}          {verbatimborder} {0.4pt}
 \spx@tempa{spx@topic@}    {div.topic_}    {shadowrule}     {0.5pt}% mod. at 7.4.0
+\spx@tempa{spx@contents@} {div.contents_} {shadowrule}     {0.5pt}% 8.1.0
+\spx@tempa{spx@sidebar@}  {div.sidebar_}  {shadowrule}     {2pt}%   8.1.0
+\@nameuse{KV@sphinx@div.sidebar_border-bottom-width}{1pt}
+% let legacy shadowrule key set all topic/contents/sidebar border
+% keys to the common value given by user to shadowrule
+\def\KV@sphinx@shadowrule #1{%
+    \@nameuse{KV@sphinx@div.topic_border-width}{#1}%
+    \@nameuse{KV@sphinx@div.contents_border-width}{#1}%
+    \@nameuse{KV@sphinx@div.sidebar_border-width}{#1}%
+}%
 \spx@tempa{spx@note@}     {div.note_}     {noteborder}     {0.5pt}
 \spx@tempa{spx@hint@}     {div.hint_}     {hintborder}     {0.5pt}
 \spx@tempa{spx@important@}{div.important_}{importantborder}{0.5pt}
@@ -444,9 +459,13 @@
 % In order for perfect exact same vertical alignment of contents from all such
 % directives, the value of horizontal border-width+padding is kept constant
 % (equal to 7.5pt since 7.4.0).
+% 8.1.0 styles separately topic, contents, and sidebar.
 %         #1 macro prefix #6 option prefix   top right bottom left
 \spx@tempa{spx@pre@}      {pre_}            {3pt}{3pt}{3pt}{3pt}
-\spx@tempa{spx@topic@}    {div.topic_}      {10pt}{7pt}{12pt}{7pt}
+\spx@tempa{spx@topic@}    {div.topic_}      {6pt}{7pt}{6pt}{7pt}% mod. at 8.1.0
+% contents styling inherits at 8.1.0 the former 7.4.0 topic defaults
+\spx@tempa{spx@contents@} {div.contents_}   {10pt}{7pt}{12pt}{7pt}%   8.1.0
+\spx@tempa{spx@sidebar@}  {div.sidebar_}    {6pt}{5.5pt}{6pt}{5.5pt}% 8.1.0
 % 7.4.0 drops legacy settings which linked strangely padding with border width
 \spx@tempa{spx@note@}     {div.note_}       {6pt}{7pt}{6pt}{7pt}
 \spx@tempa{spx@hint@}     {div.hint_}       {6pt}{7pt}{6pt}{7pt}
@@ -462,8 +481,13 @@
 \spx@tempa{spx@box@}      {box_}            {3pt}{3pt}{3pt}{3pt}
 % define legacy verbatimsep key as alias of pre_padding key
 \expandafter\let\expandafter\KV@sphinx@verbatimsep\csname KV@sphinx@pre_padding\endcsname
-% define legacy shadowsep key as alias of div.topic_padding key
-\expandafter\let\expandafter\KV@sphinx@shadowsep\csname KV@sphinx@div.topic_padding\endcsname
+% let legacy shadowsep key set all topic/contents/sidebar padding
+% keys to the common value given by user to shadosep
+\def\KV@sphinx@shadowsep #1{%
+    \@nameuse{KV@sphinx@div.topic_padding}{#1}%
+    \@nameuse{KV@sphinx@div.contents_padding}{#1}%
+    \@nameuse{KV@sphinx@div.sidebar_padding}{#1}%
+}%
 
 % Corner radii keys
 %
@@ -491,9 +515,16 @@
 % - the 3pt is used (which is normal value of \fboxsep).
 % - some admonitions use rounded corners as well.
 % - topic boxed have only their bottom right corner rounded.
+% At 8.1.0 topic, contents and sidebar separately styled.
 %          macro prefix    option prefix     tl   tr   br   bl
 \spx@tempa{spx@pre@}      {pre_}            {3pt}{3pt}{3pt}{3pt}
-\spx@tempa{spx@topic@}    {div.topic_}      \z@  \z@  {12pt} \z@
+% use four rounded corners (and no shadow) for topic at 8.1.0
+\spx@tempa{spx@topic@}    {div.topic_}      {8pt}{8pt}{8pt}{8pt}
+% contents inherits at 8.1.0 the 7.4.0 former styling of topic
+\spx@tempa{spx@contents@} {div.contents_}   \z@  \z@  {12pt} \z@
+% make sidebard distinctive as we can't really safely implement
+% it with text flowing around it, but rather as a full width block
+\spx@tempa{spx@sidebar@}  {div.sidebar_}    {12pt}\z@ {12pt} \z@
 \spx@tempa{spx@note@}     {div.note_}       {5pt}{5pt}{5pt}{5pt}
 \spx@tempa{spx@hint@}     {div.hint_}       {5pt}{5pt}{5pt}{5pt}
 \spx@tempa{spx@important@}{div.important_}  \z@\z@\z@\z@
@@ -522,6 +553,8 @@
 %          macro prefix
 \spx@tempa{spx@pre@}
 \spx@tempa{spx@topic@}
+\spx@tempa{spx@contents@}% 8.1.0
+\spx@tempa{spx@sidebar@}% 8.1.0
 \spx@tempa{spx@note@}
 \spx@tempa{spx@hint@}
 \spx@tempa{spx@important@}
@@ -569,8 +602,14 @@
 }
 \spx@tempa{spx@pre@}      {pre_}
 \spx@tempa{spx@topic@}    {div.topic_}
-% This corresponds to the legacy parameters of ShadowBox
-    \spx@topic@shadow@setter 4pt 4pt {} \@nnil
+\spx@tempa{spx@contents@} {div.contents_}
+\spx@tempa{spx@sidebar@}  {div.sidebar_}
+% This corresponds to the legacy parameters for topic/contents/sidebar,
+% but they are now only kept for contents
+    \spx@contents@shadow@setter 4pt 4pt {} \@nnil
+% sidebar has only small shadow at bottom
+    \spx@sidebar@shadow@setter  0pt 2pt {} \@nnil
+% topic has no shadow, nothing additional to do here
 \spx@tempa{spx@note@}     {div.note_}
 \spx@tempa{spx@hint@}     {div.hint_}
 \spx@tempa{spx@important@}{div.important_}
@@ -584,18 +623,27 @@
 \spx@tempa{spx@error@}    {div.error_}
 \spx@tempa{spx@box@}      {box_}
 
-% Support for legacy shadowsize (topic/contents)
+% Support for legacy shadowsize (topic/contents/sidebar)
 % This definition was broken due to a typo at 5.1.0 and got fixed at 6.1.2
 % MEMO: at 6.2.0 this no longer does \number\dimexpr in an \edef.  Reason is to
 % keep in sync with div.topic_box-shadow handling of xoffset and yoffset.
 \define@key{sphinx}{shadowsize}{%
   \def\spx@topic@shadow@xoffset{#1}%
-  \let\spx@topic@shadow@yoffset\spx@topic@shadow@xoffset
+  \let\spx@contents@shadow@xoffset\spx@topic@shadow@xoffset
+  \let\spx@topic@shadow@yoffset   \spx@topic@shadow@xoffset
+  \let\spx@contents@shadow@yoffset\spx@topic@shadow@xoffset
+  \let\spx@sidebar@shadow@yoffset \spx@topic@shadow@xoffset
   \ifdim\dimexpr\spx@topic@shadow@xoffset=\z@
       \spx@topic@withshadowfalse
+      \spx@contents@withshadowfalse
+      \spx@sidebar@withshadowfalse
   \else
       \spx@topic@withshadowtrue
       \spx@topic@insetshadowfalse
+      \spx@contents@withshadowtrue
+      \spx@contents@insetshadowfalse
+      \spx@sidebar@withshadowtrue
+      \spx@sidebar@insetshadowfalse
   \fi
 }%
 
@@ -638,6 +686,8 @@
 %          macro prefix
 \spx@tempa{spx@pre@}
 \spx@tempa{spx@topic@}
+\spx@tempa{spx@contents@}
+\spx@tempa{spx@sidebar@}
 \spx@tempa{spx@note@}
 \spx@tempa{spx@hint@}
 \spx@tempa{spx@important@}
@@ -690,7 +740,11 @@
                                 \csname KV@sphinx@pre_background-TeXcolor\endcsname
 % (6.2.0 modified some internal namings for the colors of topic boxes)
 %          macro prefix   option prefix     color name prefix
-\spx@tempa{spx@topic@}    {div.topic_}      {sphinxtopic}% (no legacy interface)
+% There was no legacy interface for topic/contents/sidebar
+% 8.1.0 allows separate styling for topic/contents/sidebar
+\spx@tempa{spx@topic@}    {div.topic_}      {sphinxtopic}
+\spx@tempa{spx@contents@} {div.contents_}   {sphinxcontents}
+\spx@tempa{spx@sidebar@}  {div.sidebar_}    {sphinxsidebar}
 \spx@tempa{spx@note@}     {div.note_}       {sphinxnote}
 \spx@tempa{spx@hint@}     {div.hint_}       {sphinxhint}
 \spx@tempa{spx@important@}{div.important_}  {sphinximportant}
@@ -743,10 +797,19 @@
 
     % At 7.4.0, let topic/contents boxes acquire background and border colours
     % and give the shadow some colour other than black
-    \setkeys{sphinx}{div.topic_border-TeXcolor=sphinx-admonition-bordercolor,
-                     div.topic_background-TeXcolor=sphinx-admonition-bgcolor,
-                     div.topic_box-shadow-TeXcolor={RGB}{108,108,108},
-                   }
+    % 8.1.0 styles separately topic/contents/sidebar
+    % topic has no shadow but we keep 7.4.0 color in case it gets needed
+    \setkeys{sphinx}{%
+        div.topic_border-TeXcolor=sphinx-admonition-bordercolor,
+        div.topic_background-TeXcolor=sphinx-admonition-bgcolor,
+        div.topic_box-shadow-TeXcolor={RGB}{108,108,108},
+        div.contents_border-TeXcolor=sphinx-admonition-bordercolor,
+        div.contents_background-TeXcolor=sphinx-admonition-bgcolor,
+        div.contents_box-shadow-TeXcolor={RGB}{108,108,108},
+        div.sidebar_border-TeXcolor=sphinx-admonition-bordercolor,
+        div.sidebar_background-TeXcolor=sphinx-admonition-bgcolor,
+        div.sidebar_box-shadow-TeXcolor=sphinx-admonition-bordercolor!80,% #9eacaf
+    }
 
 
 % 7.4.0 lets all types of admonitions style especially their titlss.
@@ -799,8 +862,14 @@
   div.error_title-background-TeXcolor=sphinx-error-title-bgcolor,
   div.error_title-foreground-TeXcolor=sphinx-error-title-fgcolor,
 %
-% TODO: implement todo (sic)
-%
+% 8.1.0 add title rows, but will not use icons per default, so
+% the fgcolor setting will be used only if user uses title-icon key
+  div.topic_title-background-TeXcolor=sphinx-admonition-title-bgcolor,
+  div.topic_title-foreground-TeXcolor=sphinx-admonition-title-fgcolor,
+  div.contents_title-background-TeXcolor=sphinx-admonition-title-bgcolor,
+  div.contents_title-foreground-TeXcolor=sphinx-admonition-title-fgcolor,
+  div.sidebar_title-background-TeXcolor=sphinx-note-title-bgcolor,
+  div.sidebar_title-foreground-TeXcolor=sphinx-note-title-fgcolor,
 }
 
 % 7.4.0 Support for icons in admonition titles
@@ -881,6 +950,9 @@
   div.attention_title-icon = \spx@faIcon{exclamation-triangle},
   div.danger_title-icon    = \spx@faIcon{radiation},
   div.error_title-icon     = \spx@faIcon{times-circle},
+% MEMO: the new at 8.1.0 defaults for contents/topic/sidebar directives
+% use no icons, they use \sphinxdotitlerow which detects automatically
+% whether title-icon key has been set or not.
 }
 
 \newif\ifspx@opt@box@addstrut

sphinx/texinputs/sphinxlatexadmonitions.sty

@@ -1,15 +1,12 @@
 %% NOTICES AND ADMONITIONS
 %
 % change this info string if making any custom modification
-\ProvidesPackage{sphinxlatexadmonitions}[2024/07/01 v7.4.0 admonitions]
+\ProvidesPackage{sphinxlatexadmonitions}[2024/07/28 v8.1.0 admonitions]
 
 % Provides support for this output mark-up from Sphinx latex writer:
 %
 % - sphinxseealso environment added at 6.1.0.
 %
-% At 7.4.0 it too now uses sphinxheavybox, and has the same associated
-% sphinxsetup CSS keys as admonitions do.
-%
 % - sphinxtodo environment added at 7.4.0.
 %
 % - sphinxadmonition (environment)
@@ -19,16 +16,21 @@
 %     sphinxheavybox since 6.2.0),
 %   - warning, caution, attention, danger, error to use sphinxheavybox.
 %
-% At 7.4.0 all admonitions use sphinxheavybox.
+%   Since 7.4.0 all admonitions use sphinxheavybox.
 %
 % - All environments sphinxnote, sphinxwarning, etc... can be redefined as
 %   will by user. Thay have a single parameter #1 which is the title.
 %
-% - The default sphinxnote, sphinxwarning, etc... use associated
-%   one-argument macros \sphinxstylenotetitle, \sphinxstylewarningtitle, etc
-%   which can be redefined.  Their default is to use \sphinxdotitlerowwithicon
-%   to typeset the title in a coloured header row at top of the
-%   admonition. (new with 7.4.0)
+% - Also redefinable by user are the one-argument commands
+%   * \sphinxstylenotetitle,
+%   * \sphinxstylewarningtitle,
+%   * etc.... one for each admonition type (also seealso and todo).
+%
+% - At 7.4.0, all commands of previous item use \sphinxdotitlerow.
+%   (the 7.4.0 name, still usable, was \sphinxdotitlerowwithicon; the 8.1.0
+%   version is also used for topic, contents and sidebar directives, see
+%   sphinxlatexshadowbox.sty, and handles both "with icon" and "without
+%   icon" situations).
 %
 % The sphinxlightbox environment is kept for backward compatiblity, for user
 % custom code which used it via custom definitions done in preamble or via
@@ -42,20 +44,21 @@
 % (the 7.4.0 redefined \sphinxstylenotetitle will not work in sphinxlightbox,
 %  so \sphinxstrong{#1}<space> which was its former default is used above).
 
-%
-% Requires:
-\RequirePackage{sphinxpackageboxes}
-% 7.4.0 removes unneeded \spx@boxes@border
-\RequirePackage{framed}% used by sphinxheavybox
-%
 % Dependencies (they do not need to be defined at time of loading):
 %
 % - of course the various colour and dimension options handled via sphinx.sty
-%
 % - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
+% - \savenotes/\spewnotes from sphinxpackagefootnote.sty
+% - \ifspx@inframed defined in sphinx.sty
+% - \spx@boxes@fcolorbox@setup from sphinxpackageboxes.sty
+%
+\RequirePackage{framed}
+% Those are required either before or after by sphinx.sty anyhow, but for
+% clarity we list them here:
+\RequirePackage{sphinxlatexgraphics}
+\RequirePackage{sphinxpackagefootnote}
+\RequirePackage{sphinxpackageboxes}
 %
-% - \savenotes/\spewnotes from sphinxpackagefootnote (for sphinxheavybox)
-
 % Provides: (also in sphinxlatexliterals.sty)
 % Only needed here by legacy (deprecated) sphinxlightbox environment.
 \providecommand*\sphinxvspacefixafterfrenchlists{%
@@ -300,10 +303,15 @@
   % workaround some LaTeX "feature" of \end command (i.e. can't use "sphinx#1" here)
   {\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}
 
+% TODO: allow these next three settings to be customized individually.
+%       This can however already be done at user level by \renewcommand
+%       inside renew'ed environments sphinxnote, sphinxhint etc...
 \newcommand\sphinxtitlerowtoppadding{5pt}
 \newcommand\sphinxtitlerowbottompadding{3pt}
 \newcommand\sphinxtitlerowaftericonspacecmd{\hskip0.5em\relax}
-\newcommand\sphinxdotitlerowwithicon[2]{% #1=type, #2=heading (without final colon)
+% 7.4.0 used this longer name:
+\newcommand\sphinxdotitlerowwithicon{\sphinxdotitlerow}
+\newcommand\sphinxdotitlerow[2]{% #1=type, #2=heading (without final colon)
    \begingroup
      \kern-\spx@boxes@padding@top
      \parskip\z@skip % the \parskip business is a workaround to a vertical
@@ -325,16 +333,24 @@
      \spx@boxes@withshadowfalse
      \sphinxcolorlet{spx@boxes@backgroundcolor}{sphinx#1TtlBgColor}%
      \spx@boxes@fcolorbox{%
-        \makebox[\linewidth][l]{%
-         \textcolor{sphinx#1TtlFgColor}{%
+        \parbox[t]{\linewidth}{% 7.4.0 used \makebox, but wrapping of long titles
+                               % is needed for generic admonition or topic box.
+         \sphinxAtStartPar
+         % 8.1.0 auto-drops extra space if no icon
+         \sbox\z@{\@nameuse{sphinx#1TtlIcon}}%
+         \ifdim\wd\z@>\z@
+          \textcolor{sphinx#1TtlFgColor}{%
             \@nameuse{sphinx#1TtlIcon}%
             % This macro is located here and not after the closing brace
             % for reasons of fall-back \spx@faIcon definition in sphinx.sty
             % in case fontawesome5 package not found.
             \sphinxtitlerowaftericonspacecmd
-         }%
+          }%
+         \fi
          \sphinxstrong{#2}%
-         \strut}%
+         \strut
+         \par
+        }%
       }%
      \kern-\spx@boxes@padding@right
      \par
@@ -347,17 +363,17 @@
 % \sphinxremovefinalcolon{#1} will typeset #1 without the colon.
 % Legacy definitions (done in sphinxlatexstyletext.sty) were all using
 % a boring plain \sphinxstrong{#1}, now we use a coloured title row.
-\newcommand\sphinxstylenotetitle     [1]{\sphinxdotitlerowwithicon{note}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstylehinttitle     [1]{\sphinxdotitlerowwithicon{hint}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyleimportanttitle[1]{\sphinxdotitlerowwithicon{important}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyletiptitle      [1]{\sphinxdotitlerowwithicon{tip}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstylewarningtitle  [1]{\sphinxdotitlerowwithicon{warning}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstylecautiontitle  [1]{\sphinxdotitlerowwithicon{caution}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyleattentiontitle[1]{\sphinxdotitlerowwithicon{attention}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyledangertitle   [1]{\sphinxdotitlerowwithicon{danger}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyleerrortitle    [1]{\sphinxdotitlerowwithicon{error}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyleseealsotitle  [1]{\sphinxdotitlerowwithicon{seealso}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyletodotitle     [1]{\sphinxdotitlerowwithicon{todo}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstylenotetitle     [1]{\sphinxdotitlerow{note}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstylehinttitle     [1]{\sphinxdotitlerow{hint}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstyleimportanttitle[1]{\sphinxdotitlerow{important}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstyletiptitle      [1]{\sphinxdotitlerow{tip}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstylewarningtitle  [1]{\sphinxdotitlerow{warning}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstylecautiontitle  [1]{\sphinxdotitlerow{caution}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstyleattentiontitle[1]{\sphinxdotitlerow{attention}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstyledangertitle   [1]{\sphinxdotitlerow{danger}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstyleerrortitle    [1]{\sphinxdotitlerow{error}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstyleseealsotitle  [1]{\sphinxdotitlerow{seealso}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstyletodotitle     [1]{\sphinxdotitlerow{todo}{\sphinxremovefinalcolon{#1}}}
 %
 % A utility to remove a final colon.  Removing last token is not easy in
 % LaTeX, and there are additional complications: