Using Custom Pygments Styles, Take 2 #1121

[8thHalfHour]

Problem

The "solution" that was mentioned in Issue (#1121) cites looking at the pygments passage of the RTD theme configuration docs for the answer. That entire segment in the documentation currently reads:

The style name to use for Pygments highlighting of source code. If not set, either the theme's default style or 'sphinx' is
selected for HTML output.

Changed in version 0.3: If the value is a fully-qualified name of a custom Pygments style class, this is then used as custom style.

So, if I look only at these brief statements, I could infer that all I need to do to include a custom Pygments style is to add it to pygments_style = ['some_file_name.css'] in the Sphinx project'sconf.py using "a fully-qualified name of a custom Pygments style class".

However, this answer is clearly inadequate, not only because it invalidates my own experience trying to get this to work, but also by negating the ridiculous number of contrasting questions and opinions about this very issue throughout the entire Internet and even within the issues that have been presented on this repo. I had opened this issue initially in hopes of beginning a conversation and continue them on the previous issue, but since that was closed, I will try to ask as many as I can here (some may be entirely irrelevant, though, which could have been ruled out had we been able to have a conversation in that issue):

1. Is the Pygments style “class” in that description the same as the file name? (In CSS, usually a “class” is one tiny portion of a css file, so this is confusing. If there is somewhere that “class” is defined specifically for the RTD theme and/or Sphinx itself, it might help to either link to that statement within your pygments_style explanation, or change the statement to include something like “. . . of a custom Pygments style class, as defined by “class” here where here represents a link to the definition.

   . . . On the other hand, if “class” here means the file name of the css file, then state that in the statement instead of “class”, like “. . . of a custom Pygments style by its filename, including the file extension” or “excluding the file extension”, depending on which is actually what the RTD theme or Sphinx expects.

2. What is the definition of “fully-qualified” in this statement? For instance, does it just mean that l need to specify a custom Pygments css file in relationship to the html_static_path settings like the ones used by thehtml_css_files = ['css/custom1.css','css/custom2.css',... etc]setting? For example, would this work: pygments_style = ['css/some_file_name.css']? If not, please either provide an example of what “fully-qualified”means in this situation, or explain it more clearly. “Fully qualified” could mean the actual path on the system it’s installed on (i.e, /Volumes/Sphinx_installation_path/, or include the domain name if Sphinx docs are being hosted on a web server such as Jekyll or Hugo or NGINX. There is really no way to know from the existing statement.

   For the sake of easy consumption and clarity, these situations should probably be addressed — either individually to clarify how to set the path to custom Pygments themes — and/or the process of adding the custom theme needs to be simplified to work like the other options, i.e., in relationship to the html_static_path.

3. Does the filename of a custom Pygments style need to be exactly pygments.ext or can it have any filename?

   NOTE: I used .ext because in Missing list styling #4, I ask what file types and languages are supported as Pygments styles in RTD/Sphinx — some questions about adding custom Pygments styles on the Internet say that they have found success by installing the pygments_style.py like any other Python package and then just declaring it in the conf.py. This may work in some situations, as it clearly it has for some people — or they are experiencing some odd bug that seems to work properly. Either way, this is confusing and when and why this might work should be addressed.

4. If I have a Pygments some_file_name.py (or other format) file, does it need to be converted to a css file using something like pygmentize -S [style] -f html -a .parent > [style].css? (Pygments itself does not use css files natively, which is why this question comes up:

   (Philosophy: the styles aren’t written in CSS syntax since this way they can be used for a variety of formatters.)
   Source: https://pygments.org/docs/styles/)

   Stating the format the Pygments file should be in would be helpful information, even if it is obvious to RTD developers.

5. If RTD does support *.py (or other theme file formats/languages) Pygments styles natively, can they also be placed in a custom folder and specified like in Maintain image size ratio #2 above? For example, would this work: pygments_style = [‘scripts/some_file_name.py‘]? (. . . or however “fully qualified” ends up being defined — the question posed in Maintain image size ratio #2 above.)

6. Will a custom Pygments style completely replace the default style being used in the RTD Sphinx theme, or overlap it? For instance, if not all styles and classes in a custom Pygments theme are used compared to the default RTD theme pygments style, will those styles shine through? This could potentially affect any aspect of fonts that are displayed, etc, — or any other part of what a pygments style covers. If this is the case, it should be addressed in your description of how to add custom Pygments styles.

   One RTD Issue (Choosing pygments monokai style #166) where this arises mentions needing to use a source/_templates/layout.html file with specifications like:

   {# layout.html #}
   {# Import the theme's layout. #}
   {% extends "!layout.html" %}
   
   {% set css_files = css_files + ['_static/pygments.css'] %}
   

   Before specifying the pygments_style = ['css/pygments.css'], and then the custom theme will work.

   But another person in that issue then states that no, it will only overwrite parts of the default style, and to fix it, to do something like this:

   A not-so-nice workaround:

   templates/layout.html

   {% extends "!layout.html" %}
   
   {% set css_files = css_files + ['_static/css/reset-syntax.css', '_static/pygments.css'] %}
   

   Then they add a reset like this:

   static/css/reset-syntax.css

   .highlight * {
      color: black;
      font-weight: normal;
      font-style: normal;
      background-color: transparent;
   }
   

   . . . And then that person states that this will supposedly allow a custom Pygments style to actually overwrite the RTD default.

   If this is the case, though, and custom Pygments styles require special setup in order to present properly and not allow the default RTD Pygments styles to bleed through, this needs to be mentioned, as does and the officially recommended method of implementation.

7. How to enable inline code highlighting for a custom Pygments style when used with the RTD theme? Or must these be addressed in a custom css file as mentioned in the Stack Overflow question here: Sphinx RTD theme: Change color of inline code? Or is that only an issue if the custom Pygments style doesn’t include styling like code.literal {color: #[color] !important; background-color: #[color] !important;}?

   That’s all I can think of at the moment. Hopefully a more productive conversation will come from this issue, and anything not mentioned or requiring clarification will be requested. Thank you for your time.

Reproducible Project

N/A

Error Logs/Results

The issues that arise from the lack of clarity in the official docs concerning this issue are numerous and easily located with a simple Google search for problems adding custom Pygments styles to the RTD theme or by performing an Issue search on this repo.

Expected Results

It should be made very clear in the official RTD documentation: a) how to add custom Pygments styles, including inline highlighting options, to the RTD Sphinx theme, and b) whether or not the custom Pygments style is looked at instead of the default RTD Pygments style or as an overlay.

Environment Info

• Python Version: v3.9.3
• Sphinx Version: v3.5.3
• RTD Theme Version: v0.5.2

[Blendify]

Again not sure why you are asking here, this is not a theme issue but an issue for Sphinx

The Sphinx documentation reference to a Python class, this is inferred because the sphinx documentation is documenting a python configuration file, and nowhere does it mention 'CSS'.

This should be as simple as the following, however, I think there is a bug where pygments_style thinks it should be a string when it could be a class. You may want to create an issue with sphinx to figure out what the proper way to create a new style. It would be nice if sphinx added Sphinx.add_pygments_style() to its API.

from pygments.style import Style
from pygments.token import Keyword, Name, Comment, String, Error, Number, Operator, Generic

class YourStyle(Style):
    default_style = ""
    styles = {
        Comment:                'italic #888',
        Keyword:                'bold #005',
        Name:                   '#f00',
        Name.Function:          '#0f0',
        Name.Class:             'bold #0f0',
        String:                 'bg:#eee #111'
    }

pygments_style = YourStyle

Will a custom Pygments style completely replace the default style being used in the RTD Sphinx theme,

The payments theme will be replaced with yours, there is no need to override the HTML templates.

How to enable inline code highlighting for a custom Pygments style when used with the RTD theme

Inline literals are not parsed with pygments, what you are asking for is currently not possible; create a feature request for sphinx.

[8thHalfHour]

Aha, thank you for letting me know that this is a Sphinx issue and not a RTD theme issue; I will open a ticket over there. As for inline syntax highlighting, it is currently possible, though there seem to be just as many issues out there about how to get that to work, too. I will bridge that topic with them, as well. I also appreciate your comment about how to get custom pygments styles working. I will give it a shot!

[humitos]

Closing since an issue was opened upstream.