fix: deprecate pygments related variable to correct typos (pydata#1614)

* refactor: rename variables

fix: change the html_theme options to match pygments name
fix: rollback package deps

Previous HEAD was c227736

* Apply suggestions from code review

---------

Co-authored-by: Daniel McCloy <dan@mccloy.info>

src/pydata_sphinx_theme/__init__.py

@@ -12,7 +12,7 @@
 from sphinx.builders.dirhtml import DirectoryHTMLBuilder
 from sphinx.errors import ExtensionError
 
-from . import edit_this_page, logo, pygment, short_link, toctree, translator, utils
+from . import edit_this_page, logo, pygments, short_link, toctree, translator, utils
 
 __version__ = "0.15.3"
 
@@ -26,6 +26,16 @@ def update_config(app):
     theme_options = utils.get_theme_options_dict(app)
     warning = partial(utils.maybe_warn, app)
 
+    # TODO: DEPRECATE after v1.0
+    themes = ["light", "dark"]
+    for theme in themes:
+        if style := theme_options.get(f"pygment_{theme}_style"):
+            theme_options[f"pygments_{theme}_style"] = style
+            warning(
+                f'The parameter "pygment_{theme}_style" was renamed to '
+                f'"pygments_{theme}_style" (note the "s" on "pygments").'
+            )
+
     # Validate icon links
     if not isinstance(theme_options.get("icon_links", []), list):
         raise ExtensionError(
@@ -269,7 +279,7 @@ def setup(app: Sphinx) -> Dict[str, str]:
     app.connect("html-page-context", update_and_remove_templates)
     app.connect("html-page-context", logo.setup_logo_path)
     app.connect("html-page-context", utils.set_secondary_sidebar_items)
-    app.connect("build-finished", pygment.overwrite_pygments_css)
+    app.connect("build-finished", pygments.overwrite_pygments_css)
     app.connect("build-finished", logo.copy_logo_images)
 
     # https://www.sphinx-doc.org/en/master/extdev/i18n.html#extension-internationalization-i18n-and-localization-l10n-using-i18n-api

src/pydata_sphinx_theme/pygment.py → src/pydata_sphinx_theme/pygments.py

@@ -1,4 +1,4 @@
-"""Handle pygment css.
+"""Handle Pygments css.
 
 inspired by the Furo theme
 https://github.com/pradyunsg/furo/blob/main/src/furo/__init__.py
@@ -75,7 +75,7 @@ def overwrite_pygments_css(app: Sphinx, exception=None):
             fallback = pygments_styles[0]  # should resolve to "default"
 
         # see if user specified a light/dark pygments theme:
-        style_key = f"pygment_{light_or_dark}_style"
+        style_key = f"pygments_{light_or_dark}_style"
         style_name = theme_options.get(style_key, None)
         # if not, use the one we set in `theme.conf`:
         if style_name is None and hasattr(app.builder, "theme"):
@@ -98,6 +98,6 @@ def overwrite_pygments_css(app: Sphinx, exception=None):
             dark_theme = style_name
 
     # re-write pygments.css
-    pygment_css = Path(app.builder.outdir) / "_static" / "pygments.css"
-    with pygment_css.open("w") as f:
+    pygments_css = Path(app.builder.outdir) / "_static" / "pygments.css"
+    with pygments_css.open("w") as f:
         f.write(get_pygments_stylesheet(light_theme, dark_theme))

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

@@ -31,8 +31,8 @@ header_links_before_dropdown = 5
 header_dropdown_text = More
 switcher =
 check_switcher = True
-pygment_light_style = a11y-high-contrast-light
-pygment_dark_style = a11y-high-contrast-dark
+pygments_light_style = a11y-high-contrast-light
+pygments_dark_style = a11y-high-contrast-dark
 logo =
 surface_warnings = True
 back_to_top_button = True
@@ -53,3 +53,7 @@ footer_end = theme-version
 secondary_sidebar_items = page-toc, edit-this-page, sourcelink
 show_version_warning_banner = False
 announcement =
+
+# DEPRECATED (remove after 1.0 release)
+pygment_light_style =
+pygment_dark_style =

tests/sites/deprecated/conf.py

@@ -22,6 +22,8 @@
 # Base options, we can add other key/vals later
 html_theme_options = {
     "surface_warnings": True,
+    "pygment_light_style": "monokai",
+    "pygment_dark_style": "tango",
 }
 
 html_sidebars = {"section1/index": ["sidebar-nav-bs.html"]}

tests/test_build.py

@@ -834,8 +834,8 @@ def test_pygments_fallbacks(sphinx_build_factory, style_names, keyword_colors) -
     confoverrides = {
         "html_theme_options": {
             **COMMON_CONF_OVERRIDES,
-            "pygment_light_style": style_names[0],
-            "pygment_dark_style": style_names[1],
+            "pygments_light_style": style_names[0],
+            "pygments_dark_style": style_names[1],
         },
     }
     sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build(
@@ -879,7 +879,10 @@ def test_deprecated_build_html(sphinx_build_factory, file_regression) -> None:
     # check the deprecation warnings
     warnings = sphinx_build.warnings.strip("\n").split("\n")
     warnings = [w.lstrip("\x1b[91m").rstrip("\x1b[39;49;00m\n") for w in warnings]
-    expected_warnings = ("",)
+    expected_warnings = (
+        'The parameter "pygment_dark_style" was renamed to',
+        'The parameter "pygment_light_style" was renamed to',
+    )
     assert len(warnings) == len(expected_warnings)
     for exp_warn in expected_warnings:
         assert exp_warn in sphinx_build.warnings