line numbers could use better visual distinction

[2bndy5]

At first, this felt like a personal style choice, but I've been adding custom CSS to all my docs that use this theme.

.linenos {
  background-color: var(--md-default-bg-color--light);
  margin-right: 0.5rem;
}

which transforms

into something a little more "legible" like so

---

I was wondering if this CSS change should be considered for this theme. Additionally, I kinda like how line numbers look in the mkdocs-material upstream

[jbms]

I agree that the current version is not good, and that the mkdocs-material styling is better.

I don't use line numbers in the tensorstore documentation so I didn't notice the issue.

Ideally we can avoid modifying the css at all, since mkdocs-material may already have some suitable rules, and just modify the HTML output from sphinx to work with it to produce the desired line number styling.

[2bndy5]

code-blocks in mkdocs-material are a stylized table in which the line numbers are a separate column and the literal code is another column. My first impression is that the code-block directive would have to overridden to produce this table structure. I don't think it would be simple matter of adding mkdocs-material classes to the html elements since the SCSS specifically looks for td and tr within an element using highlightable class attribute.

[2bndy5]

I just noticed the furo theme renders code blocks' line numbers like so

using

.highlight span.linenos {
  box-shadow: -.0625rem 0 var(--color-foreground-border) inset;
  display: inline-block;
  margin-right: .875rem;
}

This closely resembles mkdocs-material's code-blocks look, but the furo theme doesn't support changes in font-size (deeming such changes as "unstable").

[2bndy5]

Today, I had an idea to override the code-block directive with a theme specific implementation. That way we don't have to keep deviating from upstream CSS and simulate the HTML output that the CSS is expecting. Objections/thoughts?

[jbms]

Yeah that could be reasonable. We are already overriding the HTML rendering of literal in inlinesyntaxhighlight.py --- we could similarly override the HTML rendering of literal_block docutils nodes, which is what the code-block directive generates (see the visit_literal_block method in sphinx/writers/html{,5}.py for the existing implementation in sphinx).

The only question would be whether there are other sphinx extensions that may be relevant that will break if we switch to a table layout, and if so, whether it is worth it.

You could see what code is used in mkdocs to render the code blocks with line numbers --- ultimately mkdocs uses the same pygments package to highlight code.

[2bndy5]

whether it is worth it.

I forgot to mention that overriding the code-block directive could also offer users a way to implement adding code annotations. Although, I doubt a majority of sphinx users would take advantage of such an option. It would mostly be utilized by users migrating from mkdocs.

This is all speculative as I've clearly not researched the idea yet. (Thanks for the leads).

With all this in mind, I'm starting to lean toward an independent sphinx extension.

[2bndy5]

I just noticed the "copy to clipboard" button copies the entire contents of the literal block including line numbers when apparent.

[2bndy5]

Geez! This simple addition to conf.py fixed this issue entirely:

html_codeblock_linenos_style = "table"

This seems to use the upstream CSS for line numbers, and the "copy to clipboard" button only copies the literal block's content (not the line numbers).

Unfortunately, this config option has been deprecated as of sphinx v4.0 (according to the sphinx docs). I would propose that this theme automatically asserts this config option. When the option is completely removed from sphinx, we can look at overriding the visit_literal_block() to restore the functionality.

[jbms]

I think it might be possible to have the theme set this option automatically by registering a handler for theconfig-inited event.

[2bndy5]

Yeah, that's what I did to test my proposal, and it worked like a charm.