Add support for light and dark Pygments style

[Dsibe]

First, thank you so much for creating the Sphinx Awesome theme!

Currently, it seems like Sphinx Awesome can only support one Pygments style. While this is great, this behavior does not work well with both dark and light themes. Depending on the selected Pygments style, it will only function well with either light or dark themes, but not both.

It would be fantastic to add support for two separate Pygments styles: one for dark mode and another for light mode.

For example, you can see how the PyData theme implements separate styles (see "Configure Pygments theme"):

html_theme_options = {
   ...
   "pygment_light_style": "tango",
   "pygment_dark_style": "monokai"
}

https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/styling.html#configure-pygments-theme

[kai687]

Thanks for your kind words. I'll take a look how the pydata-sphinx-theme implemented this.

[Adrian8115]

Hope this gets added some day, will be really helpful!

[kai687]

Just wanted to note my observations so that I don't forget.

• Sphinx natively supports setting different color themes with pygments_style and pygments_style_dark. I don't think this theme supports this out-of-the-box due to the way I add the CSS.
• What doesn't work with the way Sphinx handles these different color schemes is the manual theme switcher. So, if you select light mode but your OS preference is set to dark mode, the light mode highlighting colors will be used.
• The Furo and Pydata Sphinx themes use a workaround, effectively bypassing the built-in Sphinx options.

I'm not keen on maintaining custom code that works around Sphinx's (or Pygments in this case) features. I've tried doing this in earlier versions of this theme, and it was painful, because even updates of minor versions often caused things to break.

So, I want to suggest this workaround for now:

1. Select a theme you want to use in light mode with the pygments_style option.

2. Create a custom CSS file with your dark mode colors:

   1. Run pygmentize -S <THEME> -f html > pygments-dark.css. Choose your syntax highlighting theme <THEME> here.
   2. Prepend every line in this file with .dark. So instead of .c { color: ...} you would have .dark .c { color: ... }.
   3. Add this file as custom CSS to your Sphinx project.

[softwareentrepreneer]

Just wanted to note my observations so that I don't forget.

• Sphinx natively supports setting different color themes with pygments_style and pygments_style_dark. I don't think this theme supports this out-of-the-box due to the way I add the CSS.
• What doesn't work with the way Sphinx handles these different color schemes is the manual theme switcher. So, if you select light mode but your OS preference is set to dark mode, the light mode highlighting colors will be used.
• The Furo and Pydata Sphinx themes use a workaround, effectively bypassing the built-in Sphinx options.

I'm not keen on maintaining custom code that works around Sphinx's (or Pygments in this case) features. I've tried doing this in earlier versions of this theme, and it was painful, because even updates of minor versions often caused things to break.

So, I want to suggest this workaround for now:

1. Select a theme you want to use in light mode with the pygments_style option.

2. Create a custom CSS file with your dark mode colors:

   1. Run pygmentize -S <THEME> -f html > pygments-dark.css. Choose your syntax highlighting theme <THEME> here.
   2. Prepend every line in this file with .dark. So instead of .c { color: ...} you would have .dark .c { color: ... }.
   3. Add this file as custom CSS to your Sphinx project.

It seems like you can prepend ".dark" by using:
pygmentize -S <THEME> -f html -a .dark > pygments-dark.css

[kai687]

Even better!