Hard to read abc table

[jtrakk]

It's not easy to read the ABC table because of the horizontal scrollbar. I've seen on some project's docs (can't remember which) a wide code-block that expands horizontally when you mouse-over it.

[njsmith]

I agree that that scrollbar is pretty awful. I'm just clueless about HTML/JS/graphic design so I don't know how to make it work better :-). If anyone has any ideas, please speak up...

[stevenjackson121]

I'm also clueless about HTML/JS/graphic design, but my best google-fu led me to https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html as the simplest "how to fix" guide. The code contained there is identical to what appears in this thread readthedocs/sphinx_rtd_theme#117, which is referenced by many projects in commits fixing this same issue.

[njsmith]

Oh great find! We already have some override CSS in docs/source/_static/hackrtd.css, so I guess we could try dropping that text in there and see how that looks? (I guess it can't look much worse...) Anyone want to try making a PR?

[stevenjackson121]

I gave it a try. I'm not happy with how it looks right now, but I'm not sure how to make it better.

The overflow: visible is very ugly as the table hangs past the white background), but it may be more usable even if it's ugly. The wrapping within table cells is a definite improvement. The wrapping of text within table headers is somewhere in between. It also looks awkward but is probably worth it to have a table that isn't so wide and make it easier to actually use (especially if the overflow visible gets removed).

I think the best way to avoid the overflow vs scrollbar issue is just to have narrower tables. The text wrapping helps, but because long function references like wait_send_all_might_not_block() are over 200 px (and cannot be broken across lines), 5 column tables can still end up over 1000 px after padding which is obviously way above the 800 px background.

I tried looking for a way to make these references smaller, but you get into so many tradeoffs I'm quickly getting out of my depth:
1.) You could try to display first 10 characters only with "<...>" appended as in wait_send_<...> to limit the worst case to something more manageable. I don't even know how to do this, but it would probably be my preference, hopefully it could expand on mouseover (not having seen it actually implemented, take that with a grain of salt).
2.) You could make text smaller obviously, but I have no idea whether to make all table text smaller, all text in the offending table smaller, all text in the offending column smaller, or all text in just the offending cell smaller (consistency is nice, but so are tables actually being displayable all at once)... The advantage here is you can see (and copy paste) the entire function name at once, but it looks weirder IMO

I thought of other options I can't remember now, but none that seemed like clear winners.

[jtrakk]

This page has a code block that expands on hover. The relevant CSS seems to be in its post.css. It even works with js disabled.

@media (min-width: 768px) {
  div.highlighter-rouge:hover {
    width: 900px; /* 1.5x of the article width */
  }
}