Support for code-specific styles via Pygments; multiple code styles in one document #13524
Replies: 5 comments 2 replies
-
I've posted some work in my fork at https://github.com/hmedina/sphinx , focusing on the HTML side. The prototype is working. The affected directives get an option that serves as an override for the default style. Actually, two options, one for light style, another for dark style (whether a theme uses both is theme dependent; Sphinx already tracks the light and dark Pygments separately). These then serve to add elements to the CSS file, using selectors to override defaults. For a sample document: |
Beta Was this translation helpful? Give feedback.
-
For HTML builds, Sphinx handles dark/light modes in two different CSS files. What's the rationale for this? |
Beta Was this translation helpful? Give feedback.
-
I've tested the rest of the builders (except AppleHelp and DocTest), and results are good. For most, this has no impact as they did not support highlighting in the first place (e.g. man, TexInfo, GetText). The LaTeX and HTML family builders appear to work correctly. |
Beta Was this translation helpful? Give feedback.
-
(continued from #13611 (comment))
In PDF, the text is per default black in code-blocks. On light backgrounds this shows well. I had experimented in the past in PDF output with Pygments styles suitable for dark backgrounds. I am really short on time now, but my memory was that the Pygments output LaTeX mark-up wasn't completely equivalent to what is achieved in HTML/CSS, and it could be observed that some tokens were not attributed a light color and were basically not visible on Pygments style background color. Using the root token color attribute as per you suggested and which I implemented via a suitable configuration of the text color in the code-block appears to be a good automatic solution (I think it will also affect line numbers if the lines are numbered which may be good or bad). When time permits I can check all 70 or so styles I have installed at my place. Extensive testing however can be done only if the PR is real candidate for merging upstream.
In my opinion, it would look very weird if all especially styled blocks were to obey in PDF this choice of "white" background. This would contrast with the non-especially styled blocks. To re-enforce some kind of uniformity one would have to globally set the VerbatimColor key of
Thanks for investigation. This is good news. |
Beta Was this translation helpful? Give feedback.
-
Responding here to @AA-Turner
Currently, Sphinx does not support using more than one style for code blocks, even if these are Pygments styles with Pygments lexers and Pygments tokens. Such a restriction appeared to be more of "nobody has built it yet" rather than based on principle. This feature is already present in other toolchains (e.g. LaTeX & Minted, Typst). Allowing more than one style per document increases the expressive power of this tool. It mirrors how admonitions can render with different styles (e.g. green tips vs. blue rationales vs. yellow warnings). Beyond my own use-case, I could imagine using style overrides to distinguish compiler versions for code that's "the same language" (gcc vs. msvc ? pascal vs. delphi ?), to further highlight the difference between languages that may not be obvious at first glance, or even for syntactically-valid code that's bad practice. As I link in the PR, a brief comment can be found at #9105 (comment) I hope the above is convincing in terms of the value added by this feature. In terms of the implementation, I am aware every line added adds a maintenance cost; if there are alternative implementations that would be easier to maintain, I'm more than open to suggestions. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
Use case & problem
I have a document that displays code in two different languages. Both are idiosyncratic and do not conform to the standard tokens managed by Pygments, and so I wrote them lexers, tokens, and stylers (hosted at hmedina/Pygments_Kappa_plugin). As that plugin utilizes the Pygments API to declare its components, it works fine with the
pygmentize
program and the rest of that stack. However, for Sphinx, the restriction of "one style per document" (see #9105 (comment)) is a problem, as the style for one language does not apply cleanly to the other. I also don't see a reason why it should apply cleanly; different languages express different things, and so in the general sense, their styles can be specific to whatever they're trying to express.Desired experience
I would like an experience similar to what I had when using LaTeX and Minted, where each code block gets its own language and style specification, rather than having a universal style for all code blocks across the document.
Path forward?
It appears to me an appropriate point to add this functionality to is the
literalinclude
directive and its siblings (i.e.code-block
,sourcecode
,code
), as they already allow one to specify thelanguage
(but not it's style). The way Minted handles scope, it creates a unique string for each code block, and scopes settings to that. That approach could work for Sphinx, in keeping with a single CSS sheet. Before I go diving into the code, I am looking to start a conversation; does this seem like useful to others? should I look at other parts? are there stumbling blocks I should be aware of? are there easier ways to achieve this?Beta Was this translation helpful? Give feedback.
All reactions