Merge pull request #7142 from septatrix/html-auxiliary-pygments-style

Add option for auxiliary pygments styles

doc/theming.rst

@@ -63,6 +63,11 @@ Python :mod:`ConfigParser` module) and has the following structure:
   highlighting.  This can be overridden by the user in the
   :confval:`pygments_style` config value.
 
+* The **pygments_dark_style** setting gives the name of a Pygments style to use
+  for highlighting when the CSS media query ``(prefers-color-scheme: dark)``
+  evaluates to true. It is injected into the page using
+  :meth:`~Sphinx.add_css_file()`.
+
 * The **sidebars** setting gives the comma separated list of sidebar templates
   for constructing sidebars.  This can be overridden by the user in the
   :confval:`html_sidebars` config value.

sphinx/builders/html/__init__.py

@@ -271,6 +271,19 @@ class StandaloneHTMLBuilder(Builder):
             style = 'sphinx'
         self.highlighter = PygmentsBridge('html', style)
 
+        if self.theme:
+            dark_style = self.theme.get_config('theme', 'pygments_dark_style', None)
+        else:
+            dark_style = None
+
+        if dark_style is not None:
+            self.dark_highlighter = PygmentsBridge('html', dark_style)
+            self.add_css_file('pygments_dark.css',
+                              media='(prefers-color-scheme: dark)',
+                              id='pygments_dark_css')
+        else:
+            self.dark_highlighter = None
+
     def init_css_files(self) -> None:
         for filename, attrs in self.app.registry.css_files:
             self.add_css_file(filename, **attrs)
@@ -484,7 +497,7 @@ class StandaloneHTMLBuilder(Builder):
             'parents': [],
             'logo': logo,
             'favicon': favicon,
-            'html5_doctype': html5_ready and not self.config.html4_writer
+            'html5_doctype': html5_ready and not self.config.html4_writer,
         }
         if self.theme:
             self.globalcontext.update(
@@ -719,6 +732,10 @@ class StandaloneHTMLBuilder(Builder):
         with open(path.join(self.outdir, '_static', 'pygments.css'), 'w') as f:
             f.write(self.highlighter.get_stylesheet())
 
+        if self.dark_highlighter:
+            with open(path.join(self.outdir, '_static', 'pygments_dark.css'), 'w') as f:
+                f.write(self.dark_highlighter.get_stylesheet())
+
     def copy_translation_js(self) -> None:
         """Copy a JavaScript file for translations."""
         if self.config.language is not None:

tests/roots/test-theming/test_theme/test-theme/theme.conf

@@ -1,3 +1,4 @@
 [theme]
 inherit = classic
 sidebars = globaltoc.html, searchbox.html
+pygments_dark_style = monokai

tests/test_build_html.py

@@ -1526,6 +1526,11 @@ def test_html_pygments_for_classic_theme(app):
     assert style.__name__ == 'SphinxStyle'
 
 
+@pytest.mark.sphinx('html', testroot='basic')
+def test_html_dark_pygments_style_default(app):
+    assert app.builder.dark_highlighter is None
+
+
 @pytest.mark.sphinx(testroot='basic', srcdir='validate_html_extra_path')
 def test_validate_html_extra_path(app):
     (app.confdir / '_static').makedirs()

tests/test_theming.py

@@ -11,8 +11,8 @@
 import os
 
 import alabaster
-import pytest
 
+import pytest
 from sphinx.theming import ThemeError
 
 
@@ -117,6 +117,22 @@ def test_staticfiles(app, status, warning):
     assert '<meta name="testopt" content="optdefault" />' in result
 
 
+@pytest.mark.sphinx(testroot='theming',
+                    confoverrides={'html_theme': 'test-theme'})
+def test_dark_style(app, status, warning):
+    style = app.builder.dark_highlighter.formatter_args.get('style')
+    assert style.__name__ == 'MonokaiStyle'
+
+    app.build()
+    assert (app.outdir / '_static' / 'pygments_dark.css').exists()
+
+    result = (app.outdir / 'index.html').read_text()
+    assert '<link rel="stylesheet" href="_static/pygments.css" type="text/css" />' in result
+    assert ('<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" '
+            'rel="stylesheet" type="text/css" '
+            'href="_static/pygments_dark.css" />') in result
+
+
 @pytest.mark.sphinx(testroot='theming')
 def test_theme_sidebars(app, status, warning):
     app.build()