LaTeX: implement support for custom background color

Some styles set the background_color to #ffffff, in such cases we
ignore that because the default Sphinx PDF light gray is nicer.

This also handles a "default" text color, but some testing shoud be
done.

Author: jfbu

sphinx/highlighting.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 from functools import partial
 from hashlib import md5
 from importlib import import_module
@@ -21,6 +22,7 @@
     guess_lexer,
 )
 from pygments.styles import get_style_by_name
+from pygments.token import Token
 from pygments.util import ClassNotFound
 
 from sphinx.locale import __
@@ -247,22 +249,7 @@ def get_stylesheet(self, selectors: list[int] | str | None = None) -> str:
                 return formatter.get_style_defs('.highlight')  # type: ignore [no-untyped-call]
         else:
             if selectors:
-                if isinstance(selectors, str):
-                    _tex_name = md5(selectors.encode()).hexdigest()[:6]  # noqa: S324
-                    for d, l in [
-                        ('0', 'G'),
-                        ('1', 'H'),
-                        ('2', 'I'),
-                        ('3', 'J'),
-                        ('4', 'K'),
-                        ('5', 'L'),
-                        ('6', 'M'),
-                        ('7', 'N'),
-                        ('8', 'O'),
-                        ('9', 'P'),
-                    ]:
-                        _tex_name = _tex_name.replace(d, l)
-                else:
+                if not isinstance(selectors, str):
                     logger.error(
                         __(
                             'Encountered %s in selectors field; expected a string '
@@ -274,10 +261,67 @@ def get_stylesheet(self, selectors: list[int] | str | None = None) -> str:
                     )
                     # not using '' as we don't want \PYG being overwritten.
                     _tex_name = 'INVALID'
+                    selectors = 'default'  # TODO: make more informed choice?
+                _tex_name = md5(selectors.encode()).hexdigest()[:6]  # noqa: S324
+                for d, l in [
+                    ('0', 'G'),
+                    ('1', 'H'),
+                    ('2', 'I'),
+                    ('3', 'J'),
+                    ('4', 'K'),
+                    ('5', 'L'),
+                    ('6', 'M'),
+                    ('7', 'N'),
+                    ('8', 'O'),
+                    ('9', 'P'),
+                ]:
+                    _tex_name = _tex_name.replace(d, l)
                 stylesheet = self.formatter(
                     style=selectors, commandprefix='PYG' + _tex_name
                 ).get_style_defs()
                 sphinx_redefs = ''
+                bc = self.get_style(selectors).background_color
+                if bc is not None:
+                    bc = bc.lstrip('#').lower()
+                    # The xcolor LaTeX package requires 6 hexadecimal digits
+                    if len(bc) == 3:
+                        bc = bc[0] * 2 + bc[1] * 2 + bc[2] * 2
+                    # We intercept a purely white background, so that PDF will use Sphinx
+                    # light gray default, rather, or the user VerbatimColor global choice.
+                    # TODO: argue pros and cons.
+                    if bc != 'ffffff':
+                        sphinx_redefs = (
+                            '% background color for above style, "HTML" syntax\n'
+                            f'\\def\\sphinxPYG{_tex_name}bc{{{bc}}}\n'
+                        )
+                # TODO: THIS MAY NOT BE THE RIGHT THING TO DO.
+                # TODO: REMOVE NEXT COMMENTS.
+                # I wanted to try with
+                # solarized-light which will use #657b83 but my sample code-block
+                # has no token not using a color so I could not confirm it does work.
+                # (indeed solarized-light uses \textcolor everywhere in its stylesheet,
+                #  so I modified manually LaTeX output to confirm the whole thing
+                #  actually worked as expected).
+                # I have not for lack of time searched for a pygments style defining
+                # such a color and not using \textcolor everywhere.
+                # The idea is to avoid invisible text on dark background which I believe
+                # I have experienced in the past when using dark background via injection
+                # of \sphinxsetup using raw:: latex directive.
+                base_style = self.get_style(selectors).styles[Token]
+                if base_style:  # could look like 'italic #000 bg:#ffffff'
+                    match = re.match(
+                        r'#([0-9a-fA-F]{3,6})(?:\s+bg:#([0-9a-fA-F]{3,6}))?', base_style
+                    )
+                    if match is not None:
+                        tc = match.group(1)
+                        if len(tc) == 3:
+                            tc = tc[0] * 2 + tc[1] * 2 + tc[2] * 2
+                        sphinx_redefs += (
+                            '% text default color for above style, "HTML" syntax\n'
+                            f'\\def\\sphinxPYG{_tex_name}tc{{{tc}}}\n'
+                        )
+                # TODO: what should we do for the color used to emphasize lines?
+                # It is VerbatimHightlightColor.
             else:
                 stylesheet = formatter.get_style_defs()
                 sphinx_redefs = _LATEX_ADD_STYLES

sphinx/writers/latex.py

@@ -2295,8 +2295,19 @@ def visit_literal_block(self, node: Element) -> None:
                     **highlight_args,
                 )
             if _texstylename:
+                # There is no a priori "VerbatimTextColor" set, except is user employed
+                # the sphinxsetup with pre_TeXcolor.  We could query the TeX boolean
+                # ifspx@opt@pre@withtextcolor but the @ letter is annoying here.  So
+                # let's simply add a group level and not worry about testing if this
+                # or other things pre-exist so we don't have to reset.
                 self.body.append(
-                    CR + f'\\def\\sphinxpygmentsstylename{{{_texstylename}}}'
+                    f'{CR}\\begingroup\\def\\sphinxpygmentsstylename{{{_texstylename}}}%'
+                    f'{CR}\\ifdefined\\sphinxPYG{_texstylename}bc'
+                    f'{CR}    \\sphinxsetup{{VerbatimColor={{HTML}}'
+                    f'{{\\sphinxPYG{_texstylename}bc}}}}%{CR}\\fi'
+                    f'{CR}\\ifdefined\\sphinxPYG{_texstylename}tc'
+                    f'{CR}    \\sphinxsetup{{pre_TeXcolor={{HTML}}'
+                    f'{{\\sphinxPYG{_texstylename}tc}}}}%{CR}\\fi'
                 )
             if self.in_footnote:
                 self.body.append(CR + r'\sphinxSetupCodeBlockInFootnote')
@@ -2314,8 +2325,6 @@ def visit_literal_block(self, node: Element) -> None:
             # get consistent trailer
             hlcode = hlcode.rstrip()[:-14]  # strip \end{Verbatim}
             if self.table and not self.in_footnote:
-                # TODO: probably add a % at end to avoid a space token if for a
-                #       block with style-light option
                 hlcode += r'\end{sphinxVerbatimintable}'
             else:
                 hlcode += r'\end{sphinxVerbatim}'
@@ -2327,7 +2336,7 @@ def visit_literal_block(self, node: Element) -> None:
             if hllines:
                 self.body.append(r'\sphinxresetverbatimhllines' + CR)
             if _texstylename:
-                self.body.append(r'\let\sphinxpygmentsstylename\undefined' + CR)
+                self.body.append(r'\endgroup' + CR)
             raise nodes.SkipNode
 
     def depart_literal_block(self, node: Element) -> None: