Skip to content

Commit

Permalink
LaTeX: make contents, topic, and sidebar separately customizable (sph…
Browse files Browse the repository at this point in the history 
…inx-doc#12704)

Co-authored-by: Bénédikt Tran <[email protected]>
  • Loading branch information
@jfbu @picnixz
jfbu and picnixz authored Aug 19, 2024
1 parent 48a8579 commit 1c131df
Show file tree
Hide file tree
Showing 11 changed files with 410 additions and 176 deletions.
6 changes: 6 additions & 0 deletions CHANGES.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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. and Bénédikt Tran.
* #12474: Support type-dependent search result highlighting via CSS.
Patch by Tim Hoffmann.
* #12652: LaTeX: Add :confval:`math_numsep` support to latex builder.
Expand Down Expand Up @@ -56,6 +59,9 @@ Bugs fixed
Note, the priority of the transform has been changed from 200 to 622,
so that it now runs after the docutils ``Footnotes`` resolution transform.
Patch by Chris Sewell.
* #12778: LaTeX: let :ref:`'sphinxsetup' <latexsphinxsetup>`
``div.topic_box-shadow`` key if used with only one dimension set both
x-offset and y-offset as per documentation.
* #12587: Do not warn when potential ambiguity detected during Intersphinx
resolution occurs due to duplicate targets that differ case-insensitively.
Patch by James Addison.
Expand Down
212 changes: 117 additions & 95 deletions doc/latex.rst
View file

Large diffs are not rendered by default.

111 changes: 89 additions & 22 deletions sphinx/texinputs/sphinx.sty
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -351,6 +351,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}
%
Expand Down Expand Up @@ -398,6 +403,15 @@
% 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} {1pt}% 8.1.0
% 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@[email protected]_border-width}{#1}%
\@nameuse{KV@[email protected]_border-width}{#1}%
\@nameuse{KV@[email protected]_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}
Expand Down Expand Up @@ -445,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}{6.5pt}{6pt}{6.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}
Expand All @@ -463,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@[email protected]_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@[email protected]_padding}{#1}%
\@nameuse{KV@[email protected]_padding}{#1}%
\@nameuse{KV@[email protected]_padding}{#1}%
}%

% Corner radii keys
%
Expand Down Expand Up @@ -492,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@
Expand Down Expand Up @@ -523,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@}
Expand Down Expand Up @@ -556,22 +588,23 @@
% used here. Since 6.2.0, expansion is delayed to time of use as for
% the other dimensions handled above. This is synched with an added
% encapsulation in \dimexpr...\relax by the "setup" from
% sphinxpackageboxes.sty. An induced regression had to be fixed in
% the sphinxShadowBox environment as it was using in an \ifdim the
% \spx@topic@shadow@yoffset macro, now holding by default 4pt+\z@
% rather than an already digested 262144sp. The +\z@ is in case ##2
% is empty.
% sphinxpackageboxes.sty.
\else #1%
\def#6{##1}\def#7{##2+\z@}%
\def#6{##1}%
\if\relax\detokenize{##2}\relax\let#7#6\else\def#7{##2}\fi
\if\relax\detokenize{##3}\relax#4\else#3\fi
\fi
}%
#5none {} {} \@nnil % no shadow by default (except for topic, see below)
}
\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
% topic and sidebar default to no shadow
\spx@tempa{spx@note@} {div.note_}
\spx@tempa{spx@hint@} {div.hint_}
\spx@tempa{spx@important@}{div.important_}
Expand All @@ -585,18 +618,28 @@
\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@sidebar@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
}%

Expand Down Expand Up @@ -639,6 +682,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@}
Expand Down Expand Up @@ -691,7 +736,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}
Expand Down Expand Up @@ -744,10 +793,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.
Expand Down Expand Up @@ -800,8 +858,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
Expand Down Expand Up @@ -882,6 +946,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
Expand Down
Loading

0 comments on commit 1c131df

Please sign in to comment.