LaTeX: add <prefix>_{TeXcolor,TeXextras} options

And add <type>TextColor and <type>TeXextras for <type>=hint, important, note, tip for variants which do not trigger for sphinxheavybox but still uses sphinxlightbox (suitably enhanced). Similar named TeXcolor and TeXextras options for \sphinxbox.
2025-02-25 18:55:22 -06:00 · 2023-03-19 12:15:57 +01:00 · 2023-03-19 12:15:57 +01:00 · 6bf40599e2
commit 6bf40599e2
parent 0194aae8a5
7 changed files with 206 additions and 71 deletions
--- a/5
+++ b/5
@ -15,6 +15,11 @@ Incompatible changes
 Deprecated
 ----------

+* LaTeX: some internals of the ``sphinxadmonition`` environment have been
+  marked for removal at 7.0.0 in the :file:`sphinxlatexadmonitions.sty`.
+  Custom re-definitions of ``sphinxlightbox`` or ``sphinxheavybox`` will have
+  to be updated if they depended upon them.
+
 Features added
 --------------

--- a/doc/latex.rst
+++ b/doc/latex.rst
@ -1032,6 +1032,29 @@ Do not use quotes to enclose values, whether numerical or strings.

    .. versionadded:: 6.2.0

+|notetextcolors|
+    The optional color for the contents.
+
+    Default: unset (uses ambient text color, a priori black)
+
+    .. versionadded:: 6.2.0
+
+       To be considered experimental until 7.0.0.  These options have aliases
+       ``div.note_TeXcolor`` (etc) described in :ref:`additionalcss`.  Using
+       the latter will let Sphinx switch to a more complex LaTeX code,
+       which supports the customizability described in :ref:`additionalcss`.
+
+|notetexextras|
+    Some extra LaTeX code (such as ``\bfseries``  or ``\footnotesize``)
+    to be executed at start of the contents.
+
+    Default: empty
+
+    .. versionadded:: 6.2.0
+
+       To be considered experimental until 7.0.0.  These options have aliases
+       ``div.note_TeXextras`` (etc) described in :ref:`additionalcss`.
+
 ``noteborder``, ``hintborder``, ``importantborder``, ``tipborder``
    The width of the two horizontal rules.

@ -1093,6 +1116,12 @@ Do not use quotes to enclose values, whether numerical or strings.
 .. |notebgcolors| replace:: ``noteBgColor``, ``hintBgColor``,
                            ``importantBgColor``, ``tipBgColor``

+.. |notetextcolors| replace:: ``noteTextColor``, ``hintTextColor``,
+                            ``importantTextColor``, ``tipTextColor``
+
+.. |notetexextras| replace:: ``noteTeXextras``, ``hintTeXextras``,
+                            ``importantTeXextras``, ``tipTeXextras``
+
 .. |warningbdcolors| replace:: ``warningBorderColor``, ``cautionBorderColor``,
                               ``attentionBorderColor``, ``dangerBorderColor``,
                               ``errorBorderColor``
@ -1129,14 +1158,6 @@ Additional  CSS-like ``'sphinxsetup'`` keys
   ``noteBgColor`` (or ``hintBgColor``, ...) also triggers usage of
   ``sphinxheavybox`` for :dudir:`note` (or :dudir:`hint`, ...).

-.. versionadded:: 6.2.0
-
-   All "admonition" directives as well as :dudir:`topic` and contents_ now
-   support their respective ``box-decoration-break`` to be set to ``slice``.
-   Formerly, only :rst:dir:`code-block` did.  It is undecided though if this
-   should inhibit the display of a bottom shadow, if set.  Currently the shadow,
-   if set, is shown nevertheless but this is to be considered unstable.
-
 Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be optionally
 imported from some genuine CSS external file, but currently they have to be used
 via the ``'sphinxsetup'`` interface (or the ``\sphinxsetup`` LaTeX command
@ -1260,7 +1281,8 @@ forget the underscore separating the prefix from the property names.
  margin.
 - | ``<prefix>_border-TeXcolor``,
  | ``<prefix>_background-TeXcolor``,
-  | ``<prefix>_box-shadow-TeXcolor``.
+  | ``<prefix>_box-shadow-TeXcolor``,
+  | ``<prefix>_TeXcolor``.
    These are colors.

  The shadow color defaults in all cases to ``{rgb}{0,0,0}`` i.e. to black.
@ -1272,14 +1294,34 @@ forget the underscore separating the prefix from the property names.
  For all other types, the border color defaults to black and the background
  color to white.

+  The ``<prefix>_TeXcolor`` stands for the CSS property "color", i.e. it
+  influences the text color of the contents.  As for the three other options,
+  the naming ``TeXcolor`` is to stress that the input syntax is the TeX one
+  for colors not an HTML/CSS one.  If set, a ``\color`` command is inserted at
+  start of the directive contents; for admonitions, this happens after the
+  heading which reproduces the admonition type.
+
+- ``<prefix>_TeXextras``: if set, its value must be some LaTeX command or
+  commands, for example ``\itshape``.  These commands will be inserted at the
+  start of the contents; for admonitions, this happens after the heading which
+  reproduces the admonition type.
+
 .. note::

-   - Prior to 6.2.0, rounded corners forced a constant border width, the
+   - All directives support ``box-decoration-break`` to be set to ``slice``.
+
+     .. versionchanged:: 6.2.0
+
+        Formerly, only :rst:dir:`code-block` did.  The default remains
+        ``clone`` for all other directives, but this will probably change at
+        7.0.0.
+
+   - Prior to 6.2.0, rounded corners forced a constant border width: the
     separate settings were ignored in favor of the sole
     ``<prefix>_border-width``.  Now (up to) 4 distinct radii happily cohabit
     with (up to) 4 distinct border widths.

-   - Inset shadows are currently incompatible with rounded corners.  In case
+   - Inset shadows are incompatible with rounded corners.  In case
     both are specified the inset shadow will simply be ignored.

     .. versionchanged:: 6.2.0
@ -1287,6 +1329,28 @@ forget the underscore separating the prefix from the property names.
        Formerly it was to the contrary the rounded corners which were ignored
        in case an inset shadow was specified.

+   - ``<prefix>_TeXcolor`` and ``<prefix>_TeXextras`` are new with 6.2.0.
+
+     Usefulness is doubtful in the case of :rst:dir:`code-block`:
+
+     - ``pre_TeXcolor`` will influence only the few non-Pygments highlighted
+       tokens; it does color the line numbers, but if one wants to color
+       *only* them one has to go through the ``fancyvrb`` interface.
+
+     - ``pre_TeXextras=\footnotesize`` for example may be replaced by usage of
+       the :confval:`latex_elements` key ``'fvset'``.  For ``'lualatex'`` or
+       ``'xelatex'`` Sphinx includes in the preamble already
+       ``\fvset{fontsize=\small}`` and this induces ``fancyvrb`` into
+       overriding a ``\footnotesize`` coming from ``pre_TeXextras``.  One has
+       to use ``pre_TeXextras=\fvset{fontsize=\footnotesize}`` syntax.
+       Simpler to set directly the :confval:`latex_elements` key
+       ``'fvset'``...
+
+     Consider these options experimental and that some implementation details
+     may change.  For example if the ``pre_TeXextras`` LaTeX commands were put
+     by Sphinx in another location it could override the ``'fvset'`` effect,
+     perhaps this is what will be done in a future release.
+
   - Rounded boxes are done using the pict2e_ interface to some basic PDF
     graphics operations.  If this LaTeX package can not be found the build
     will proceed and render all boxes with straight corners.
@ -1553,6 +1617,8 @@ Here is the complete list of keys:
  ``border-bottom-right-radius``, ``border-bottom-left-radius``,
 - ``box-shadow``,
 - ``border-TeXcolor``, ``background-TeXcolor``, ``box-shadow-TeXcolor``,
+  ``TeXcolor``,
+- ``TeXextras``,
 - and ``addstrut`` which is a boolean key, i.e. to be used as ``addstrut=true``,
  or ``addstrut`` alone where ``=true`` is omitted, or ``addstrut=false``.

@ -1560,7 +1626,7 @@ This last key is specific to ``\sphinxbox`` and it means to add a ``\strut``
 so that heights and depths are equalized across various instances,
 independently of text content.  The combination ``addstrut,
 padding-bottom=0pt, padding-top=1pt``  is often satisfactory.  The default is
-``addstrut=false``.e
+``addstrut=false``.

 Refer to :ref:`additionalcss` for important syntax information regarding the
 other keys.  The default
@ -1578,43 +1644,40 @@ 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
-   ``\sphinxboxsetup``.  In contrast key-value options given to ``\sphinxbox``
-   must be within square brackets, are they are... options.  See examples
-   below.
-
-A utility ``\newsphinxbox`` is provided to create a new boxing macro, say
-``\foo`` which will act exactly like ``\sphinxbox`` but with a possibly
-different set of initial default option values.  Here is some example:
+Here is some example of use:

 .. code-block:: latex

   latex_elements = {
       'preamble': r'''
-   % define a sphinxbox with some defaults:
-   \newsphinxbox[border-width=4pt,%
-                 border-radius=4pt,%
-                 background-TeXcolor=yellow!20]{\foo}
-   % use this \foo to redefine rendering of some text elements:
-   \protected\def\sphinxguilabel#1{\foo{#1}}
-   \protected\def\sphinxmenuselection#1{\foo[background-TeXcolor=green!20,
-                                             border-width=1pt,
-                                             box-shadow=3pt 3pt,
-                                             box-shadow-TeXcolor=gray]{#1}}
-   % and this one will use \sphinxbox directly
-   % one can also add options within square brackets as in usage of \foo above
-   \protected\def\sphinxkeyboard#1{\sphinxbox{\sphinxcode{#1}}}
+   % modify globally the defaults
+   \sphinxboxsetup{border-width=2pt,%
+                   border-radius=4pt,%
+                   background-TeXcolor=yellow!20}
+   % configure some styling element with some extra specific options:
+   \protected\def\sphinxkeyboard#1{\sphinxbox[border-TeXcolor=green]{\sphinxcode{#1}}}
   ''',
   }

-In the above example, you can probably use ``\renewcommand`` syntax if you
-prefer (with ``[1]`` in place of ``#1`` then).  There is also
-``\renewsphinxbox`` which one can imagine inserting in the midst of a document
-via the :dudir:`raw` directive, so that from that point on, all the custom
-text elements using ``\foo`` will start using re-defined box parameters,
-without having to redefine for example ``\sphinxguilabel`` as it already uses
-``\foo``.
+A utility ``\newsphinxbox`` is provided to create a new boxing macro, say
+``\foo`` which will act exactly like ``\sphinxbox`` but with a given extra
+configuration:
+
+.. code-block:: latex
+
+   % the specific options to \foo are within brackets
+   \newsphinxbox[border-radius=0pt, box-shadow=2pt 2pt]{\foo}
+   % then use this \foo, possibly with some extra options still:
+   \protected\def\sphinxguilabel#1{\foo{#1}}
+   \protected\def\sphinxmenuselection#1{\foo[box-shadow-TeXcolor=gray]{#1}}
+
+Boxes rendered with ``\foo`` obey as the ones using directly ``\sphinxbox``
+the current configuration as set possibly mid-way in document via
+``\sphinxboxsetup`` (from a :dudir:`raw` LaTeX mark-up), the only difference
+is that they have an initial additional set of default extras.
+
+In the above examples, you can probably use ``\renewcommand`` syntax if you
+prefer it to ``\protected\def`` (with ``[1]`` in place of ``#1`` then).


 Environments
--- a/sphinx/texinputs/sphinx.sty
+++ b/sphinx/texinputs/sphinx.sty
@ -565,7 +565,7 @@ will be set to white}%
 }%

 % Color keys
-% (three of them: border, background, shadow)
+% (four of them: border, background, shadow and the text color)
 %
 % Some problems due to legacy naming scheme which had diverging conventions
 % for code-blocks (VerbatimBorderColor, VerbatimColor) and admonitions
@ -591,9 +591,10 @@ will be set to white}%
  \expandafter\spx@tempb
  \csname if#1withshadowcolor\expandafter\endcsname
  \csname if#1withbordercolor\expandafter\endcsname
-  \csname if#1withbackgroundcolor\endcsname
+  \csname if#1withbackgroundcolor\expandafter\endcsname
+  \csname if#1withtextcolor\endcsname
 }%
-\def\spx@tempb#1#2#3{\newif#1\newif#2\newif#3}%
+\def\spx@tempb#1#2#3#4{\newif#1\newif#2\newif#3\newif#4}%
 %          macro prefix
 \spx@tempa{spx@pre@}
 \spx@tempa{spx@topic@}
@ -612,15 +613,18 @@ will be set to white}%
  \expandafter\spx@tempb
  \csname #1withbordercolortrue\expandafter\endcsname
  \csname #1withbackgroundcolortrue\expandafter\endcsname
-  \csname #1withshadowcolortrue\endcsname
+  \csname #1withshadowcolortrue\expandafter\endcsname
+  \csname #1withtextcolortrue\endcsname
 }
-\def\spx@tempb#1#2#3#4#5{% #4 = option prefix, #5 = color name prefix
-  \define@key{sphinx}{#4border-TeXcolor}%
-     {#1\spx@defineorletcolor{#5BorderColor}##1\relax}%
-  \define@key{sphinx}{#4background-TeXcolor}%
-     {#2\spx@defineorletcolor{#5BgColor}##1\relax}%
-  \define@key{sphinx}{#4box-shadow-TeXcolor}%
-     {#3\spx@defineorletcolor{#5ShadowColor}##1\relax}%
+\def\spx@tempb#1#2#3#4#5#6{% #5 = option prefix, #6 = color name prefix
+  \define@key{sphinx}{#5border-TeXcolor}%
+     {#1\spx@defineorletcolor{#6BorderColor}##1\relax}%
+  \define@key{sphinx}{#5background-TeXcolor}%
+     {#2\spx@defineorletcolor{#6BgColor}##1\relax}%
+  \define@key{sphinx}{#5box-shadow-TeXcolor}%
+     {#3\spx@defineorletcolor{#6ShadowColor}##1\relax}%
+  \define@key{sphinx}{#5TeXcolor}%
+     {#4\spx@defineorletcolor{#6TextColor}##1\relax}%
 }
 %          macro prefix    option prefix    color name prefix
 \spx@tempa{spx@pre@}      {pre_}            {Verbatim}
@ -662,9 +666,44 @@ will be set to white}%
    \spx@tempa{div.error_}      {error}

    % Keep legacy sphinxsetup <type>BorderColor for <type>=note, hint, ...
+    % which will not trigger sphinxheavybox
+    % Add "legacy" hintTextColor etc... that will not trigger sphinxheavybox
    \def\spx@tempa#1#2{% #1 = CSS like option prefix, #2 = legacy option prefix
      \expandafter\let\csname KV@sphinx@#2BorderColor\expandafter\endcsname
                      \csname KV@sphinx@#1border-TeXcolor\endcsname
+      \expandafter\let\csname KV@sphinx@#2TextColor\expandafter\endcsname
+                      \csname KV@sphinx@#1TeXcolor\endcsname
+    }
+    \spx@tempa{div.note_}       {note}
+    \spx@tempa{div.hint_}       {hint}
+    \spx@tempa{div.important_}  {important}
+    \spx@tempa{div.tip_}        {tip}
+
+% The TeXextras key
+%
+\def\spx@tempa#1{% #1 = macro prefix
+  \expandafter\spx@tempb\csname #1TeXextras\endcsname
+}
+\def\spx@tempb#1#2{% #2 = option prefix
+  \define@key{sphinx}{#2TeXextras}{\def#1{##1}}%
+}
+%          macro prefix   option prefix
+\spx@tempa{spx@pre@}      {pre_}
+\spx@tempa{spx@topic@}    {div.topic_}
+\spx@tempa{spx@note@}     {div.note_}
+\spx@tempa{spx@hint@}     {div.hint_}
+\spx@tempa{spx@important@}{div.important_}
+\spx@tempa{spx@tip@}      {div.tip_}
+\spx@tempa{spx@warning@}  {div.warning_}
+\spx@tempa{spx@caution@}  {div.caution_}
+\spx@tempa{spx@attention@}{div.attention_}
+\spx@tempa{spx@danger@}   {div.danger_}
+\spx@tempa{spx@error@}    {div.error_}
+\spx@tempa{spx@box@}      {box_}
+    % Add "legacy" hintTeXextras etc... that will not trigger sphinxheavybox
+    \def\spx@tempa#1#2{% #1 = CSS like option prefix, #2 = legacy option prefix
+      \expandafter\let\csname KV@sphinx@#2TeXextras\expandafter\endcsname
+                      \csname KV@sphinx@#1TeXextras\endcsname
    }
    \spx@tempa{div.note_}       {note}
    \spx@tempa{div.hint_}       {hint}
@ -678,7 +717,7 @@ will be set to white}%
 % re-created and they do not trigger the "heavybox" as their meaning will not
 % be modified in the loop below contrarily to their CSS counterparts
 % div.note_border-TeXcolor and div.note_border-width, and to the noteBgColor
-% next.
+% etc... which are handled below.
 %
 % This goes via rather hardcore TeX here.
 \def\spx@tempa#1{\if\relax#1\expandafter\@gobble
@ -712,13 +751,15 @@ will be set to white}%
          {border-top-left-radius}{border-top-right-radius}%
          {border-bottom-right-radius}{border-bottom-left-radius}%
          {box-shadow}%
-          {border-TeXcolor}{background-TeXcolor}{box-shadow-TeXcolor}%
+          {border-TeXcolor}{background-TeXcolor}{box-shadow-TeXcolor}{TeXcolor}%
+          {TeXextras}%
 \relax

 % Now we add at 6.2.0 <type>BgColor et al. options which will trigger the
 % "heavybox" as they are \let to the div.<type>_background-TeXColor option
 % which has already been enhanced to set the boolean for rendering via
-% "heavybox".  This is in contrast with legacy <type>BorderColor.
+% "heavybox".  This is in contrast with legacy <type>BorderColor,
+% and with the new <type>TeXcolor and <type>TeXextras.
    \def\spx@tempa#1#2{% #1 = CSS like option prefix, #2 = legacy style option prefix
      \expandafter\let\csname KV@sphinx@#2BgColor\expandafter\endcsname
                      \csname KV@sphinx@#1background-TeXcolor\endcsname
@ -854,8 +895,8 @@ will be set to white}%
          {border-top-left-radius}{border-top-right-radius}%
          {border-bottom-right-radius}{border-bottom-left-radius}%
          {box-shadow}%
-          {border-TeXcolor}{background-TeXcolor}{box-shadow-TeXcolor}%
-          {addstrut}{addstrut@default}%
+          {border-TeXcolor}{background-TeXcolor}{box-shadow-TeXcolor}{TeXcolor}%
+          {TeXextras}{addstrut}{addstrut@default}%
 \do{\expandafter\let\csname KV@sphinxbox@\x\expandafter\endcsname
                    \csname KV@sphinx@box_\x\endcsname}
 % Let \sphinxboxsetup also prepare a "reset", which will be used by nested
@ -889,6 +930,7 @@ will be set to white}%
                border-TeXcolor={RGB}{32,32,32},%  the default VerbatimBorderColor
                background-TeXcolor={gray}{0.95},% the default VerbatimColor
                box-shadow-TeXcolor={rgb}{0,0,0},%
+                TeXextras={},%
                addstrut=false% (a final comma here would not hurt)
               }%
 \RequirePackage{sphinxpackageboxes}
--- a/sphinx/texinputs/sphinxlatexadmonitions.sty
+++ b/sphinx/texinputs/sphinxlatexadmonitions.sty
@ -37,14 +37,19 @@
 \newenvironment{sphinxseealso}[1]{\sphinxstrong{#1:}\par\nopagebreak}{}

 % This \dimen register is a legacy relic from Sphinx 1.5 which is used now
-% only for sphinxlightbox.  It is set-up in sphinxadmonition environment.
+% only for sphinxlightbox.  It is set in the sphinxadmonition environment.
 \newdimen\spx@notice@border

-% The color spx@notice@bordercolor is set in sphinxadmonition environment.
+% 6.2.0: add support for the <type>_TeXcolor options for text color.
+% 6.2.0: use directly sphinx<type>BorderColor, not spx@notice@bordercolor,
+%        as the latter will probably be removed altogether at 7.0.0
 \newenvironment{sphinxlightbox}{%
+  % done in sphinxadmonition but its place should be here
+  % \spx@notice@border \dimexpr\csname spx@\spx@noticetype @border\endcsname\relax
  \par
-  \noindent{\color{spx@notice@bordercolor}%
-            \rule{\linewidth}{\spx@notice@border}}\par\nobreak
+  \noindent{\color{sphinx\spx@noticetype BorderColor}%
+            \rule{\linewidth}{\spx@notice@border}}%
+  \par\nobreak
  {\parskip\z@skip\noindent}%
  }
  {%
@ -52,7 +57,7 @@
  % (we can't cancel that any earlier \vskip introduced a potential pagebreak)
  \sphinxvspacefixafterfrenchlists
  \nobreak\vbox{\noindent\kern\@totalleftmargin
-      {\color{spx@notice@bordercolor}%
+      {\color{sphinx\spx@noticetype BorderColor}%
       \rule[\dimexpr.4\baselineskip-\spx@notice@border\relax]
             {\linewidth}{\spx@notice@border}}\hss}\allowbreak
  }% end of sphinxlightbox environment definition
@ -203,14 +208,24 @@
 \newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading
  % can't use #1 directly in definition of end part
  \def\spx@noticetype {#1}%
-  % set the parameters common to lightbox and heavybox environments
-  \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
-  \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
-  % At 6.2.0 this \spx@notice@border is used only for note, hint, important,
-  % and tip.  And only if they are rendered via sphinxlightbox
-  \spx@notice@border \dimexpr\csname spx@#1@border\endcsname\relax
+      % At 6.2.0, these definitions of spx@notice@bordercolor and
+      % spx@notice@bgcolor serve nothing at all for sphinxheavybox.  And the
+      % sphinxlightbox uses sphinx<type>BorderColor directly.  Not removing
+      % though, in case some people have redefined sphinxlightbox (or even
+      % sphinxheavybox) and expect these things to exist.
+      %
+      % This is marked for removal at 7.0.0.
+      \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
+      \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
+      \spx@notice@border \dimexpr\csname spx@#1@border\endcsname\relax
  % trigger the sphinx<type> environment, #2=heading is passed as argument
-  \begin{sphinx#1}{#2}}
+  \begin{sphinx#1}{#2}%
+  % 6.2.0 support of div.<type>_TeX{color,extras} options
+  \csname ifspx@\spx@noticetype @withtextcolor\endcsname
+         \color{sphinx\spx@noticetype TextColor}%
+  \fi
+  \csname spx@\spx@noticetype @TeXextras\endcsname
+  }
  % workaround some LaTeX "feature" of \end command (can't use "sphinx#1" here)
  {\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}

--- a/sphinx/texinputs/sphinxlatexliterals.sty
+++ b/sphinx/texinputs/sphinxlatexliterals.sty
@ -775,6 +775,9 @@
     % As fancyvrb Verbatim will do \@minipagefalse itself, let's simplify things.
     \everypar{}%
     \color@begingroup % protect against color leaks (upstream framed.sty bug)
+     \ifspx@pre@withtextcolor\color{VerbatimTextColor}\fi % mostly shadowed by
+                                % Pygments highlighting anyhow
+     \spx@pre@TeXextras
     % will fetch its optional arguments if any
     \OriginalVerbatim
 }%
--- a/sphinx/texinputs/sphinxlatexshadowbox.sty
+++ b/sphinx/texinputs/sphinxlatexshadowbox.sty
@ -97,6 +97,10 @@
    \@setminipage
    }%
    \color@begingroup % workaround upstream framed.sty bug
+    \csname ifspx@topic@withtextcolor\endcsname
+      \color{sphinxtopicTextColor}%
+    \fi
+    \spx@topic@TeXextras
  }%
  {% insert the "endminipage" code
    \par\unskip
--- a/sphinx/texinputs/sphinxpackageboxes.sty
+++ b/sphinx/texinputs/sphinxpackageboxes.sty
@ -81,6 +81,7 @@
 % spx@boxes@bordercolor
 % spx@boxes@backgroundcolor
 % spx@boxes@shadowcolor
+% spx@boxes@textcolor

 %%%%%%%%%%%%%%%%
 % "setup" macro
@ -232,6 +233,7 @@
    \setkeys{sphinxbox}{#1}%
    \spx@boxes@fcolorbox@setup{box}%
    \spx@boxes@shadowinbboxtrue% inline sphinx boxes include shadow in bbox
+    \ifspx@box@withtextcolor\color{sphinxboxTextColor}\fi
    %
    % MEMO: the fcolorbox@{rectangle,rounded} draw the contents (which here
    % will be encapsulated as \box\z@) last, i.e.  after shadow, background,
@ -254,6 +256,7 @@
    % color pop's would not have caused trouble I guess as long as the color
    % insertions for shadow, background, border are correctly balanced.
    \setbox0\hbox\bgroup\aftergroup\spx@boxes@sphinxbox@a
+    \afterassignment\spx@box@TeXextras
    \let\next=%
 }
 \def\spx@boxes@sphinxbox@a{\spx@boxes@fcolorbox{%
@ -338,7 +341,7 @@
 % It is up to the caller to take extra steps if the border and padding must go
 % into margin as well (see sphinxlatexliterals.sty for how this is done in
 % \spx@verb@FrameCommand).
-% 
+%
 % In usage as a "FrameCommand" with framed.sty, the argument will already be a
 % collection of TeX boxes (and interline glues).
 %
@ -636,7 +639,7 @@
     \ifspx@boxes@insetshadow
       \spx@boxes@withshadowfalse % ignore inset shadow
     \fi
-   \fi   
+   \fi
   % reserve space to external shadow if on left
   \ifspx@boxes@withshadow
    \ifspx@boxes@shadowinbbox