Why deprecate the html_codeblock_linenos_style option?

[2bndy5]

Is your feature request related to a problem? Please describe.
We've been porting the mkdocs-material theme to sphinx-immaterial, and found the the mkdocs-material theme uses tables to represent literal code blocks with line numbers. With Sphinx's default setting

html_codeblock_linenos_style = "inline"

We found a few problems:

1. The line numbers are copied to the clipboard when using clipboard.js.
2. The CSS inherited from mkdocs-material cannot distinguish line numbers from the rest of the literal code block. Thus no intended CSS gets used.
3. Line numbers scroll horizontally with the rest of the literal code block. Ideally, we expect the line numbers to be statically positioned while horizontally scrolling the rest of the literal code block.

Describe the solution you'd like
Please don't deprecate the html_codeblock_linenos_style config option in Sphinx v6.0.

Describe alternatives you've considered
For now, we're thinking of having the sphinx-immaterial theme assert the option to use

html_codeblock_linenos_style = "table"

When/If Sphinx v6.0 removes the option, we're going to have to overwrite the visit_literal_block() to restore this functionality.

Additional context

I talked with @tk0miya at the Sphinx(jp) hack-a-thon event, and we discussed that there is no need to leave table output in the future.

I've read #7879 (comment), but I don't see any good rationality to deem the option deprecated. The sphinx builtin themes aren't the only themes that supply their own CSS (we don't inherit any CSS from sphinx builtin themes). If writing CSS for code blocks with line numbers (using "table") is too complex, then leave it to the theme designers to choose how to set the option - don't deprive them of the option all together.

We're not as flexible as we'd like to be concerning CSS changes. This is because we need to minimize the possible merge conflicts when merging in updates from the mkdocs-material theme. Same reason goes for using clipboard.js instead of executablebooks/sphinx-copy-button extension (though this isn't as strict a requirement as keeping the CSS unaltered).

Original issue for the sphinx-immaterial theme is jbms/sphinx-immaterial#26

[mgeier]

The reason for the deprecation is (as mentioned in #7879) accessibility: #7849.

If writing CSS for code blocks with line numbers (using "table") is too complex

It's not. This is not the reason.

leave it to the theme designers to choose how to set the option - don't deprive them of the option all together.

The reason for not providing a choice is to help blind people.

[2bndy5]

I'm having trouble imagining any literal code blocks being comprehend-able via screen readers because of syntactical convention (snake casing vs camel casing vs improper casing).

Nonetheless, having the line numbers be statically positioned (& separate from the rest of literal code blocks) is obviously a visual preference. I still think deprecating the option all together is too utilitarian. I'm ok with the default (inline) favoring accessibility standards.

ps - I'm not as familiar with accessibility standards as I should be for web development. Upon first glance, I don't see an easy workaround using table with WAI-ARIA specs.

[AA-Turner]

I removed this in #10471 along with the other deprecated items.

Our options seem to be

1. revert that change. Not ideal for accessibility as noted above, although it doesn't break sphinx-immaterial
2. refactor the inline line number functionality so that it works for sphinx-immaterial

(2) would obviously be my preference. What would be required, and is it even possible?

A

[2bndy5]

Our theme is rather rigid. We can't make a lot of changes to CSS or JS because that would cause annoying merge conflict with mkdocs-material theme (our sphinx-immaterial theme's upstream).

Our theme needs the line numbers in a separate column of a 1-row table. It may not be pleasing to accessibility standards, but that doesn't seem to be a high priority for our upstream mkdocs sources.

If option 1 is completely off the table, then we'll have to patch it back in ourselves. The current default behavior does not behave well with sphinx-immaterial theme, so we've hard-coded the config's old table behavior. The mkdocs upstream theme relies on pymdownx.superfences which doesn't offer an option to generate the inline behavior used as a default here.

[2bndy5]

Just mentioning that clipboard.js will copy the line numbers of a code block that are inlined with the code. Seems like this deprecation will gain accessibility, but lose convenience (visually and functionally).

[2bndy5]

@AA-Turner As far as option 2, I think we can get away with wrapping the inline line numbers with special attributes. The following is one way in which superfences output inline line numbers, but notice the lack of #text in the span.

<code>
  <span class="linenos" data-linenos="1 ">
    ::before
  </span>import foo.bar
</code>

I think there's some fancy JS taking the data-linenos attribute's value and putting it into the pseudo element before.

---

I've opened an issue with our upstream mkdocs src to support inline behavior: squidfunk/mkdocs-material#4061

[AA-Turner]

Is clipboard.js a hard requirement? Can something be done to teach it about the inline approach?

A

[2bndy5]

As far as I can tell, the data-linenos approach is the workaround to clipboard.js (which is a hard requirement) - at least for superfences. I'd rather change CSS than work with merge conflicts in JS (which is actually using RXJS - so a completely different JS like syntax).

In fact, the popular sphinx-copybutton extension from executablebooks uses clipboard.js, and the inline behavior is still being addressed: executablebooks/sphinx-copybutton#138.

[AA-Turner]

This is a blocker issue for 6.0.

A

[2bndy5]

Agreed. The only solution I can think of is to monkeypatch literal blocks in sphinx v6+.

[AA-Turner]

For 6.0.0, we will revert the removal and delay the deprecation, unless things have moved on in the JS side.

A