Include source in highlighting warnings (#11150)

If pygments fails to lex a source string as the specified highlight
language, Sphinx prints a warning.  Previously, that warning did not
include the actual source text, although it does include location
information.

However, in some cases the location information may be missing, there
may be multiple highlighted literals on the same line, or the rST is
automatically generated somehow.  In such cases, it can be difficult
to determine the source text that led to the error.

With this change, the source text is included in the warning.

sphinx/highlighting.py

@@ -170,8 +170,8 @@ def highlight_block(self, source: str, lang: str, opts: dict | None = None,
             if lang == 'default':
                 pass  # automatic highlighting failed.
             else:
-                logger.warning(__('Could not lex literal_block as "%s". '
-                                  'Highlighting skipped.'), lang,
+                logger.warning(__('Could not lex literal_block %r as "%s". '
+                                  'Highlighting skipped.'), source, lang,
                                type='misc', subtype='highlighting_failure',
                                location=location)
             lexer = self.get_lexer(source, 'none', opts, force, location)

tests/test_build_html.py

@@ -34,7 +34,7 @@
 %(root)s/index.rst:\\d+: WARNING: unknown option: '&option'
 %(root)s/index.rst:\\d+: WARNING: citation not found: missing
 %(root)s/index.rst:\\d+: WARNING: a suitable image for html builder not found: foo.\\*
-%(root)s/index.rst:\\d+: WARNING: Could not lex literal_block as "c". Highlighting skipped.
+%(root)s/index.rst:\\d+: WARNING: Could not lex literal_block .* as "c". Highlighting skipped.
 """
 
 

tests/test_build_latex.py

@@ -35,7 +35,7 @@
 %(root)s/index.rst:\\d+: WARNING: unknown option: '&option'
 %(root)s/index.rst:\\d+: WARNING: citation not found: missing
 %(root)s/index.rst:\\d+: WARNING: a suitable image for latex builder not found: foo.\\*
-%(root)s/index.rst:\\d+: WARNING: Could not lex literal_block as "c". Highlighting skipped.
+%(root)s/index.rst:\\d+: WARNING: Could not lex literal_block .* as "c". Highlighting skipped.
 """
 
 

tests/test_highlighting.py

@@ -97,7 +97,8 @@ def test_default_highlight(logger):
 
     # python: raises error if highlighting failed
     ret = bridge.highlight_block('reST ``like`` text', 'python')
-    logger.warning.assert_called_with('Could not lex literal_block as "%s". '
-                                      'Highlighting skipped.', 'python',
+    logger.warning.assert_called_with('Could not lex literal_block %r as "%s". '
+                                      'Highlighting skipped.',
+                                      'reST ``like`` text', 'python',
                                       type='misc', subtype='highlighting_failure',
                                       location=None)