diff --git a/doc/latex.rst b/doc/latex.rst index 3ed1e7137..f57965ba0 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1566,11 +1566,17 @@ Refer to :ref:`additionalcss` for important syntax information regarding the other keys. The default configuration uses no shadow, a border-width of ``\fboxrule``, a padding of ``\fboxsep``, rounded corners (with radius ``\fboxsep``) and background and -border colors as for the default rendering of code-blocks. One can modify -these defaults via using ``\sphinxboxsetup{key=value,...}`` or also via -``\sphinxsetup`` but all key names must then be prefixed with ``box_``. +border colors as for the default rendering of code-blocks. -.. hint:: +When a ``\sphinxbox`` usage is nested within another one, it will ignore the +options of the outer one: it first resets all options to their default state +as they were prior to applying the outer box options, then it applies its own +specific ones. + +One can modify these defaults via the command ``\sphinxboxsetup{key=value,...}``. +The effect is cumulative, if one uses this command multiple times. Here the +options are a mandatory argument so are within curly braces, not square +brackets. The comma separated key-value list is to be used within curly braces with ``\sphinxsetup`` (keys must then be prefixed with ``box_``) or diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 86a28dd5b..45a96f5d2 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -836,15 +836,38 @@ will be set to white}% {addstrut}{addstrut@default}% \do{\expandafter\let\csname KV@sphinxbox@\x\expandafter\endcsname \csname KV@sphinx@box_\x\endcsname} -\newcommand\sphinxboxsetup{\setkeys{sphinxbox}} -% Some of these defaults got already set directly. -% As xcolor is perhaps not loaded we can not use =VerbatimColor syntax, -% and must use the \definecolor syntax. -\sphinxboxsetup{border-width=\fboxrule, - padding=\fboxsep, - border-radius=\fboxsep, - border-TeXcolor={RGB}{32,32,32},% default VerbatimBorderColor - background-TeXcolor={gray}{0.95},% default VerbatimColor +% Let \sphinxboxsetup also prepare a "reset", which will be used by nested +% boxes; currently and by laziness this is implemented simply by accumulating +% all passed options inside some storage, in the order they were given, rather +% than saving the box would-be parameters. Advantage is that this will not +% have to be modified if additional keys are added in future (e.g. for +% elliptic corners). Storing obeys TeX groups. (these details would be +% relevant only for some genuine independant LaTeX package and manual user +% authored mark-up, not Sphinx auto mark-up). +\newcommand\sphinxboxsetup[1]{% + \setkeys{sphinxbox}{#1}% + \expandafter\def\expandafter\spx@boxes@sphinxbox@defaults\expandafter + {\spx@boxes@sphinxbox@defaults,#1}% +} +\def\spx@boxes@sphinxbox@reset{% + \begingroup\def\x{\endgroup\setkeys{sphinxbox}}% + \expandafter\x\expandafter{\spx@boxes@sphinxbox@defaults}% +} +% Some of these defaults got already set. But we now list them all explicitly +% for a complete initial configuration of reset storage. +% +\let\spx@boxes@sphinxbox@defaults\@gobble +\sphinxboxsetup{% + border-width=\fboxrule,% <-not really needed to avoid EOL space + padding=\fboxsep,% but done here out of habit + border-radius=\fboxsep,% + box-shadow=none,% +% As xcolor is perhaps not loaded we can not use border-TeXcolor=VerbatimColor +% which would not be compatible with \definecolor syntax. + border-TeXcolor={RGB}{32,32,32},% the default VerbatimBorderColor + background-TeXcolor={gray}{0.95},% the default VerbatimColor + box-shadow-TeXcolor={rgb}{0,0,0},% + addstrut=false% (a final comma here would not hurt) }% \RequirePackage{sphinxpackageboxes} \input{sphinxlatexadmonitions.sty} diff --git a/sphinx/texinputs/sphinxpackageboxes.sty b/sphinx/texinputs/sphinxpackageboxes.sty index 2d2e0a93f..87bc57467 100644 --- a/sphinx/texinputs/sphinxpackageboxes.sty +++ b/sphinx/texinputs/sphinxpackageboxes.sty @@ -222,7 +222,17 @@ % lualatex as then it is by default doing nothing. \leavevmode \begingroup - \sphinxboxsetup{#1}% only "box_" options, with no "box_" prefix + \ifcsname spx@boxes@sphinxbox@isnested\endcsname + % nested boxes reset all box options to be as the \sphinxboxsetup + % defaults, before applying their specific options + \spx@boxes@sphinxbox@reset + \else + % top layer box, toggle the nested flag + \csname spx@boxes@sphinxbox@isnested\endcsname + \fi + % we do not use \sphinxboxsetup as it is a user command extending the + % "reset" storage + \setkeys{sphinxbox}{#1}% \spx@boxes@fcolorbox@setup {box} {sphinxboxBorderColor}