inline code doesn't respect dark theme

[braxtons12]

Using inline code, eg via:

in docutils.conf:

[restructuredtext parser]
syntax_highlight = short

and in an rst file:

.. role:: cpp(code)
    :language: cpp
    :class: highlight
    
  This is my :cpp:`inline code!`

Results in the code using a light theme, even when the dark theme is active. This should be changed to be dynamic like code blocks

[choldgraf]

Hmm - I suspect that this may be because our inline code selector uses the Sphinx inline structure instead of the docutils structure.

Can you share an HTML website with the built docs not working?

[12rambau]

I think there are 2 pygments.css used (https://sphinxcontrib-inlinesyntaxhighlight.readthedocs.io/en/latest/) so we would need to duplicate the dark one as well. I tried to use the code you provided and it seems I can't build it using make html.

How do you build your documentation?

[braxtons12]

... I tried to use the code you provided and it seems I can't build it using make html.

How do you build your documentation?

I use the doxygen + sphinx + breathe workflow, but doxygen + breathe aren't relevant/affecting the issue here.

This is my conf.py (with doxygen and breathe related things commented out) And for an example index.rst:

hyperion-utils
*****************

This is my :cpp:`inline code!`

I build using make html

[choldgraf]

Can you share an HTML snippet of the paragraph with the inline code that is not working? This is what we would need to check against our CSS

[braxtons12]

Here's the generated html

I think the relevant bit is:

  <section id="hyperion-utils">
<h1>hyperion-utils<a class="headerlink" href="#hyperion-utils" title="Permalink to this heading">#</a></h1>
<p>This is my <code class="code highlight cpp docutils literal highlight-cpp"><span class="kr">inline</span><span class="w"> </span><span class="n">code</span><span class="o">!</span><span class="w"></span></code></p>
</section>

[12rambau]

ok I copy-pasted your code snipet inside a test documentation and everything worked as expected:

Maybe one of your extensions is rewriting the pygments.css file. Can you try to do a minimal reproducible example with as few extensions as possible so we understand where it's coming from?

[choldgraf]

also double check that you are running the latest release candidate, not the latest stable release.

[braxtons12]

This html is produced w/ no extensions enabled at all

This is the corresponding conf.py

running pip show pydata-sphinx-theme gives the version as 0.10.0rc2

[drammock]

@braxtons12 your conf.py on lines 72-73 says:

    "pygment_light_style": "manni",
    "pygment_dark_style": "manni",

Wouldn't you expect the highlighting to be the same in that case?

[braxtons12]

Wouldn't you expect the highlighting to be the same in that case?

I guess that depends on what you mean by "the same". I would expect that "the same" here means stylistically equivalent, so for dark mode you get a dark equivalent (or in light mode you get a light equivalent if the chosen theme was "dark").

I.E. I would expect that for light mode w/ a "light" theme, it looks exactly like in the theme gallery and that for dark mode, the syntax colors are unchanged but the background color is swapped for a dark one and grayscale "colors" have their value inverted.

This allows using the same colorset for both light + dark so you don't end up with two totally stylistically different themes for each mode.

That's the current visual behavior for code blocks (the current behavior might actually invert the value on all colors in dark mode, but I can't tell visually), so I'd expect inline code to follow the same behavior.

[12rambau]

to perform the highlight coloring of the code blocks (and inline code) we are relying on Pygments (https://pygments.org) which is already providing a solid number of coloring schemes. The only thing we enforce is the background to make sure its the same as the background color of the selected theme (specifically the dark one which is not exactly black).

In short if you want to have 2 highlighting colors you'll need to select a "dark" and a "light" scheme (or rely on ours).

[drammock]

I.E. I would expect that for light mode w/ a "light" theme, it looks exactly like in the theme gallery and that for dark mode, the syntax colors are unchanged but the background color is swapped for a dark one and grayscale "colors" have their value inverted.

That's a reasonable expectation, but is in fact not how Pygments works.

As for why it doesn't work that way: IMO it's not easy to come up with enough colors that are distinct from one another, and sufficiently high-contrast against both dark and light background colors, to make one theme work well in the way you suggest. Even if you allow for "reversing" grayscale colors, where do you draw the line between what counts as "grayscale" and not? Do only "pure" grays get reversed, or also slightly-reddish-grays? It's not obvious to me that there's one correct answer there. Pygments could try to be clever, but I'd bet that it's pretty hard to make an automated "convert light theme to dark theme" algorithm that would end up with results that look as good as what a human would do.

This allows using the same colorset for both light + dark so you don't end up with two totally stylistically different themes for each mode.

That's why there are pairs like "solarized-light" and "solarized-dark" or "gruvbox-light" and "gruvbox-dark" here.

[braxtons12]

The only thing we enforce is the background to make sure its the same as the background color of the selected theme (specifically the dark one which is not exactly black)

Right now for code blocks, using the same theme for light + dark mode, more is being changed than just the background color:

Both of those screenshots are using:

    "pygment_light_style": "manni",
    "pygment_dark_style": "manni",

In short if you want to have 2 highlighting colors you'll need to select a "dark" and a "light" scheme (or rely on ours).

All I'm asking for is that inline code follows the same behavior as code blocks instead of this:

That's why there are pairs like "solarized-light" and "solarized-dark" or "gruvbox-light" and "gruvbox-dark" here.

if the pydata theme supports all pygments styles, then the docs need updated, as the link on this page points here instead

[12rambau]

Right now for code blocks, using the same theme for light + dark mode, more is being changed than just the background color:

welcom in the fantastic world of color illusion. the colors are exactly the same but as the background changes your eyes feel them differently.

All I'm asking for is that inline code follows the same behavior as code blocks instead of this

I want to investigate why the background is not changing, that is a bug. The color on the other hand is a feature (again we are and we will continue to rely on the fine tailored Pygments styles)

if the pydata theme supports all pygments styles, then the docs need updated, as the link on this page points here instead

That's an open-source repository, if you think we should change the link, I'm happy to review a PR (there's an "edit this page" on every documentation section)

[braxtons12]

welcom in the fantastic world of color illusion. the colors are exactly the same but as the background changes your eyes feel them differently.

I understand that, when I said "more is being changed than just the background color", I'm specifically talking about the grayscale text, IE how checked_add is white in the first image, but black in the second, using the same pygments style. Note I'm NOT complaining about that (it's desired), just trying to point out that there is in fact more than just a background color change happening.

That's an open-source repository, if you think we should change the link, I'm happy to review a PR (there's an "edit this page" on every documentation section)

Done

[braxtons12]

I want to investigate why the background is not changing, that is a bug. The color on the other hand is a feature (again we are and we will continue to rely on the fine tailored Pygments styles)

Accidentally stumbled on this, but it turns out that this behavior isn't dark mode specific. If a dark pygments theme is used in light mode, inline code will be rendered with a dark background while code blocks will be rendered with a light background:

Both images are generated using

    "pygment_light_style": "one-dark",
    "pygment_dark_style": "one-dark",

[drammock]

Right now for code blocks, using the same theme for light + dark mode, more is being changed than just the background color:

I cannot reproduce this. I just hard-coded our theme to use tango for both light and dark themes by changing this:

https://github.com/pydata/pydata-sphinx-theme/blob/5d3520540062f231ab1f72cee1a308e27a054466/src/pydata_sphinx_theme/init.py#L784-L785

and what I see when I build the docs locally is this:

EDIT: note that in these screenshots the foreground color of the inline code does change subtly between light and dark modes (from rgb(221, 158, 194) to rgb(232, 62, 140)), but that is because it is not styled by pygments; it is simply "preformatted text" (not lexed as a particular programming language) and so its color is handled by our theme's CSS rules (not Pygments' CSS). If I edit that page to add some lexed inline code, I get this:

...which indeed looks like a bug; we should (as you say) be altering the background color on the inline lexed code the same way we do for code blocks.

[braxtons12]

I cannot reproduce this. I just hard-coded our theme to use tango for both light and dark themes by changing this:

minimal example: conf.py index.rst generated html

screencaps:

It's not really relevant though. IMO that's preferred.

The point of this whole issue/thread is the background differences.

[drammock]

right, agreed. see my edited post just above yours.

[braxtons12]

right, agreed. see my edited post just above yours.

Ah yeah, I see that now

[12rambau]

I tested on the latest version of the theme

with the following .rst:

hyperion-utils
**************

.. role:: python(code)
   :language: python

:python:`import sphinx`

.. code-block:: python

   import sphinx

the colored output looks just fine to me:

maybe the works from #838 has changed the behavior. Can someone test it again to let me know if it still need to be worked on?

[drammock]

@12rambau maybe it's enough to add an example of it to our docs? I'm not sure the best place; maybe a new section on this page: https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/light-dark.html that just says "here are examples of preformatted text (sphinx colors it) inline lexed code (pygments colors it) and code blocks (also pygments)?

edit: yes probably was #838 that fixed it