Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

LaTeX: make contents, topic, and sidebar separately customizable #12704

Merged
merged 35 commits into from
Aug 19, 2024
Merged

LaTeX: make contents, topic, and sidebar separately customizable #12704

Show file tree
Hide file tree
Changes from 27 commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
e903f38
LaTeX: make contents, topic, and sidebar separately customizable
jfbu Jul 28, 2024
d6c0614
Let titlerow macro auto-detect if using or not icon
jfbu Jul 29, 2024
0f1d446
Docs
jfbu Jul 29, 2024
bf34ac6
Mark-up glitch in docs
jfbu Jul 29, 2024
07adb47
LaTeX docs missing updates
jfbu Jul 29, 2024
e5e3866
LaTeX docs again, mainly pre-existing typos
jfbu Jul 29, 2024
0ed2afa
Merge branch 'master' into latex_contents_vs_topic_vs_sidebar
jfbu Jul 31, 2024
019d31c
Update LaTeX code comments
jfbu Jul 31, 2024
617b80c
Update CHANGES for PR #12704
jfbu Jul 31, 2024
ed08c49
Again LaTeX code comments
jfbu Jul 31, 2024
22ab8d1
Merge branch 'master' into latex_contents_vs_topic_vs_sidebar
jfbu Aug 8, 2024
8ee7838
Use 2pt for sidebar top border width to better match the bottom 1pt+2pt
jfbu Aug 8, 2024
fcb2607
Update docs
jfbu Aug 8, 2024
e01347a
Merge branch 'master' into latex_contents_vs_topic_vs_sidebar
jfbu Aug 11, 2024
2d94c60
Update doc/latex.rst
jfbu Aug 12, 2024
6825831
No default shadow for sidebar, thinner borders, docs updates
jfbu Aug 13, 2024
81df7cf
Fix shadowsize key got broken for sidebar
jfbu Aug 13, 2024
6d27446
Apply suggestion to doc/latex.rst
jfbu Aug 13, 2024
b48973f
Apply a suggestion to doc/latex.rst
jfbu Aug 13, 2024
5eff50e
Fix #12778
jfbu Aug 13, 2024
4de5e37
Update CHANGES.rst with #12778 fix
jfbu Aug 13, 2024
c0054d2
Use [topic] explicitly for sphinxtopic wrapper of sphinxShadowBox
jfbu Aug 13, 2024
7f633d8
Use \newcommand* for \sphinxstyletopictitle and friends
jfbu Aug 13, 2024
cb795d6
Add test
jfbu Aug 13, 2024
67fff70
Dear Ruff your style is not my taste!
jfbu Aug 13, 2024
97a4323
Ruff: calm down now!
jfbu Aug 13, 2024
ed06f03
Merge branch 'master' into latex_contents_vs_topic_vs_sidebar
jfbu Aug 17, 2024
6626dfe
Update doc/latex.rst (suggestion 1)
jfbu Aug 19, 2024
75ae998
Apply suggestions from code review
jfbu Aug 19, 2024
842a770
Line wrap after 8.1.0 (and one 7.4.0) in multiple versionchanged
jfbu Aug 19, 2024
b46ef6e
A full stop
jfbu Aug 19, 2024
1b920aa
Better wording for horizontal shadows extending into margin
jfbu Aug 19, 2024
fc148fd
Use indents of 2 spaces not 4 at some locations in LaTeX code
jfbu Aug 19, 2024
3df4ce0
Update CHANGES.rst
jfbu Aug 19, 2024
279d761
One more versionchanged linewrap in doc/latex.rst
jfbu Aug 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGES.rst
View file
Open in desktop
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`,
picnixz marked this conversation as resolved.
Show resolved Hide resolved
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.
* #12743: No longer exit on the first warning when
Expand All @@ -50,6 +53,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: 116 additions & 96 deletions doc/latex.rst
View file
Open in desktop

Large diffs are not rendered by default.

111 changes: 89 additions & 22 deletions sphinx/texinputs/sphinx.sty
View file
Open in desktop
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 @@ -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}
%
Expand Down Expand Up @@ -397,6 +402,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}%
jfbu marked this conversation as resolved.
Show resolved Hide resolved
}%
\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 @@ -444,9 +458,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 @@ -462,8 +480,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}%
jfbu marked this conversation as resolved.
Show resolved Hide resolved
\@nameuse{KV@[email protected]_padding}{#1}%
\@nameuse{KV@[email protected]_padding}{#1}%
}%

% Corner radii keys
%
Expand Down Expand Up @@ -491,9 +514,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 @@ -522,6 +552,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 @@ -555,22 +587,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 @@ -584,18 +617,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 @@ -638,6 +681,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 @@ -690,7 +735,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 @@ -743,10 +792,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 @@ -799,8 +857,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 @@ -881,6 +945,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