LaTeX: reset options in nested \sphinxbox'es

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
+border colors as for the default rendering of code-blocks.
-these defaults via using ``\sphinxboxsetup{key=value,...}`` or also via
-``\sphinxsetup`` but all key names must then be prefixed with ``box_``.
 
-.. 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

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}}
+% Let \sphinxboxsetup also prepare a "reset", which will be used by nested
-% Some of these defaults got already set directly.
+% boxes; currently and by laziness this is implemented simply by accumulating
-% As xcolor is perhaps not loaded we can not use =VerbatimColor syntax,
+% all passed options inside some storage, in the order they were given, rather
-% and must use the \definecolor syntax.
+% than saving the box would-be parameters.  Advantage is that this will not
-\sphinxboxsetup{border-width=\fboxrule,
+% have to be modified if additional keys are added in future (e.g. for
-                padding=\fboxsep,
+% elliptic corners).  Storing obeys TeX groups.  (these details would be
-                border-radius=\fboxsep,
+% relevant only for some genuine independant LaTeX package and manual user
-                border-TeXcolor={RGB}{32,32,32},%  default VerbatimBorderColor
+% authored mark-up, not Sphinx auto mark-up).
-                background-TeXcolor={gray}{0.95},% default VerbatimColor
+\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}

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}