LaTeX: fix style arg lacking, refactor to achieve full LaTeX support

Author: jfbu

sphinx/builders/latex/__init__.py

@@ -4,7 +4,6 @@
 
 import os
 import os.path
-import re
 import warnings
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -281,9 +280,6 @@ def add_block_style(self, style: str) -> None:
         """Add a styler to the tracker of highlighting styles."""
         if style not in self.specialized_highlighters:
             pb = highlighting.PygmentsBridge(dest='latex', stylename=style)
-            pb.formatter_args['commandprefix'] = 'PYG' + re.sub(
-                r'[^a-zA-Z]', 'Z', style
-            )
             self.specialized_highlighters[style] = pb
 
     def get_bridge_for_style(self, style: str) -> highlighting.PygmentsBridge | None:
@@ -303,10 +299,11 @@ def write_stylesheet(self) -> None:
             f.write('\\NeedsTeXFormat{LaTeX2e}[1995/12/01]\n')
             f.write(
                 '\\ProvidesPackage{sphinxhighlight}'
-                '[2022/06/30 stylesheet for highlighting with pygments]\n'
+                '[2025/06/15 stylesheet for highlighting with pygments]\n'
             )
             f.write(
-                '% Its contents depend on pygments_style configuration variable.\n\n'
+                '% Its contents depend on pygments_style configuration variable.\n'
+                '% And also on encountered code-blocks :style-light: options.\n\n'
             )
             f.write(highlighter.get_stylesheet())
             if self.specialized_highlighters:

sphinx/highlighting.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-import re
 from functools import partial
+from hashlib import md5
 from importlib import import_module
 from typing import TYPE_CHECKING
 
@@ -74,24 +74,26 @@
 % to fix problems for the 5.0.0 inline code highlighting (captions!).
 % The \text is from amstext, a dependency of sphinx.sty.  It is here only
 % to avoid build errors if for some reason expansion is in math mode.
-\def\PYG{override}Zbs{{\text\textbackslash}}
-\def\PYG{override}Zus{{\_}}
-\def\PYG{override}Zob{{\{{}}
-\def\PYG{override}Zcb{{\}}}}
-\def\PYG{override}Zca{{\text\textasciicircum}}
-\def\PYG{override}Zam{{\&}}
-\def\PYG{override}Zlt{{\text\textless}}
-\def\PYG{override}Zgt{{\text\textgreater}}
-\def\PYG{override}Zsh{{\#}}
-\def\PYG{override}Zpc{{\%}}
-\def\PYG{override}Zdl{{\$}}
-\def\PYG{override}Zhy{{\sphinxhyphen}}% defined in sphinxlatexstyletext.sty
-\def\PYG{override}Zsq{{\text\textquotesingle}}
-\def\PYG{override}Zdq{{"}}
-\def\PYG{override}Zti{{\text\textasciitilde}}
+\def\PYGZbs{{\text\textbackslash}}
+\def\PYGZus{{\_}}
+\def\PYGZob{{\{{}}
+\def\PYGZcb{{\}}}}
+\def\PYGZca{{\text\textasciicircum}}
+\def\PYGZam{{\&}}
+\def\PYGZlt{{\text\textless}}
+\def\PYGZgt{{\text\textgreater}}
+\def\PYGZsh{{\#}}
+\def\PYGZpc{{\%}}
+\def\PYGZdl{{\$}}
+\def\PYGZhy{{\sphinxhyphen}}% defined in sphinxlatexstyletext.sty
+\def\PYGZsq{{\text\textquotesingle}}
+\def\PYGZdq{{"}}
+\def\PYGZti{{\text\textasciitilde}}
 \makeatletter
 % use \protected to allow syntax highlighting in captions
-\protected\def\PYG{override}#1#2{{\PYG{override}@reset\PYG{override}@toks#1+\relax+{{\PYG{override}@do{{#2}}}}}}
+\def\PYG@#1#2{{\PYG@reset\PYG@toks#1+\relax+{{\PYG@do{{#2}}}}}}
+\protected\def\PYG{\csname PYG\ifdefined\sphinxpygmentsstylename
+                   \sphinxpygmentsstylename\else @\fi\endcsname}
 \makeatother
 """
 
@@ -246,24 +248,37 @@ def get_stylesheet(self, selectors: list[int] | str | None = None) -> str:
         else:
             if selectors:
                 if isinstance(selectors, str):
-                    tex_name = re.sub(r'[^a-zA-Z]', 'Z', selectors)
+                    _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:
                     logger.error(
                         __(
-                            'Encountered %s in selectors field; expected a string for the '
-                            'LaTeX formatter, using default values as fallback.\n'
-                            'Please report his error.'
+                            'Encountered %s in selectors field; expected a string '
+                            'for the LaTeX formatter.  Please report this error.'
                         ),
                         type(selectors),
                         type='misc',
                         subtype='highlighting_failure',
                     )
-                    tex_name = ''
+                    # not using '' as we don't want \PYG being overwritten.
+                    _tex_name = 'INVALID'
                 stylesheet = self.formatter(
-                    commandprefix='PYG' + tex_name
+                    style=selectors, commandprefix='PYG' + _tex_name
                 ).get_style_defs()
-                sphinx_redefs = _LATEX_ADD_STYLES.format(override=tex_name)
+                sphinx_redefs = ''
             else:
                 stylesheet = formatter.get_style_defs()
-                sphinx_redefs = _LATEX_ADD_STYLES.format(override='')
+                sphinx_redefs = _LATEX_ADD_STYLES
             return stylesheet + sphinx_redefs

sphinx/writers/latex.py

@@ -8,6 +8,7 @@
 
 import re
 from collections import defaultdict
+from hashlib import md5
 from pathlib import Path
 from typing import TYPE_CHECKING, cast
 
@@ -2258,6 +2259,7 @@ def visit_literal_block(self, node: Element) -> None:
             opts = self.config.highlight_options.get(lang, {})
 
             # As blocks are processed, we discover specified styles.
+            _texstylename = ''
             if node.get('style-light'):
                 code_style = node.get('style-light')
                 self.builder.add_block_style(style=code_style)
@@ -2275,6 +2277,20 @@ def visit_literal_block(self, node: Element) -> None:
                         location=node,
                         **highlight_args,
                     )
+                    _texstylename = md5(code_style.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'),
+                    ]:
+                        _texstylename = _texstylename.replace(d, l)
             else:
                 hlcode = self.highlighter.highlight_block(
                     node.rawsource,
@@ -2284,6 +2300,10 @@ def visit_literal_block(self, node: Element) -> None:
                     location=node,
                     **highlight_args,
                 )
+            if _texstylename:
+                self.body.append(
+                    CR + f'\\def\\sphinxpygmentsstylename{{{_texstylename}}}'
+                )
             if self.in_footnote:
                 self.body.append(CR + r'\sphinxSetupCodeBlockInFootnote')
                 hlcode = hlcode.replace(r'\begin{Verbatim}', r'\begin{sphinxVerbatim}')
@@ -2300,6 +2320,8 @@ 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}'
@@ -2310,6 +2332,8 @@ def visit_literal_block(self, node: Element) -> None:
             self.body.append(CR + hlcode + CR)
             if hllines:
                 self.body.append(r'\sphinxresetverbatimhllines' + CR)
+            if _texstylename:
+                self.body.append(r'\let\sphinxpygmentsstylename\undefined' + CR)
             raise nodes.SkipNode
 
     def depart_literal_block(self, node: Element) -> None: