Support for code-specific styles via Pygments; multiple code styles in one document

[hmedina]

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 the language (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?

[hmedina]

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: