Wrap table cells for a better responsive table experience + fix print

[benjaoming]

Fixes

• Wide table handling is not flexible, how to override the CSS? #117
• Tables don't scale readthedocs.org#2161

Adds:

• Wrapping for <td>s on desktop sizes
• Visible overflow and wrapping on printed media

Does not wrap <th> on purpose, this leaves a bit of control for people who wanna force the width of certain columns.

Please observe the great amount of projects working around the issue with related commits, issues and PRs.

Quotes:

@kmike

Why not have relevant CSS fixed by default? Are there cases when it is desirable to truncate the information in table, be it a tablet screen or a computer screen? On tablets existing tables are even worse because horizontal scroll of individual elements is hard on touch interfaces. On macs there is no indication that table can be horizontally scrolled because scrollbars are hidden by default; they don't appear even on hover, you need to actually start scrolling to see the scrollbars.

@agjohnson

This was a design decision for the theme around table wrapping, though I agree that the experience around wide tables on large displays is generally poor.

Before

I agree that this may look nicer, but that's only because the example table doesn't have a lot of text in its <td>s!

After

Printing

There's now a higher probability that tables will print:

FAQ

Q: Why no overflow: visible on desktop tables?

A: Because horizontal scrolling is completely off in the theme, so the table would be cropped like this :/

[benjaoming]

I'm also convinced that for readability, now that wrapping is introduced, we need vertical-align: top for <td> which has to go through a separate rule.

Displays like this:

[dpdani]

Hi,
I probably have a corner case with this issue: in my docs, there's a table in which the first column always has preformatted text which is pretty long and overlaps with the next table cell.
See here at page 12 and forward.
Would this corner-case be fixed by this PR?

[benjaoming]

@dpdani No, the CSS that changes print media is about printing HTML through a browser, your report is generated with a different ruleset for Latex. I'm not sure why, but if you read up on how Latex works and about how in penalises and optimizes its layout to have as little penalty as possible, you'll get the idea why this can happen.

[dpdani]

@benjaoming Ok thank you.

[Blendify]

FYI, this is a sensitive change, so the review might take a while as we test.

[benjaoming]

@Blendify sounds good! Thanks for taking time to test it!

[benjaoming]

@ericholscher @agjohnson questions or concerns here that I can respond to?

[mitya57]

+1 for this change. I was wondering why one of the tables looks so weird, and found that white-space: nowrap rule. Changing it to normal makes it look much better.

Before:

After:

[krzychb]

Hi RTD team,

What are the prospects to have this PR merged?

This bug is really annoying.

Here is my story:

• First I was avoiding tables that have long sentences.
• Then I switched to using Definition Lists. This is acceptable as an alternative for two column tables, but does not work if you have three or more columns with text that should be wrapped.
• Finally, being confronted with multiple column tables with a lot of text that is hard to read because of this issue, I have no choice but to patch this nice theme. I found a patch by Rackspace Documentation Guides that eventually brought me to this PR ready and waiting, vintage 2017 🍷

Looking forward to see this PR merged.
Documentation by RTD will be better without crappy tables like below you have to scroll left and right to be able to read it:

[Blendify]

We will have a look as soon as the next release is out.

[Blendify]

We will have a look as soon as the next release is out.

[benjaoming]

@agjohnson

agjohnson removed the PR: ready for review label 14 days ago

What does that mean?

PR is rebased to latest master.

[Blendify]

@agjohnson

agjohnson removed the PR: ready for review label 14 days ago

What does that mean?

PR is rebased to latest master.

This can be ignored, it was automated. All the labels for rtfd were synced so some were removed.

[stsewd]

@benjaoming we don't use that label anymore on rtd, now we use work in progress (not ready for review) or 'not label' (ready for review if ci pass) flow

[benjaoming]

Okay, it's ready for review... and has been since June 2017 😄

[lalten]

What are the chances of getting this reviewed/merged in the foreseeable future?

[benjaoming]

Adding this for additional reference to the extensive workarounds for this issue: OpenShot/openshot-qt#1272

[benjaoming]

Fixed a bit of SASS syntax and merged latest master in.

Understanding that this PR will change how existing tables are displayed by default, but I think it's an entirely desirable change. One hack will still exist to keep very wide columns because nowrap is maintained on <th> (I would actually want to remove that if no one objects)

What do other themes do?

Short answer: They wrap text in table cells.

As there aren't any specific worries associated with the change and I see other themes with text wrap in table cells, I think this would still be the way forward.

Examples of other themes with wrapping:

• Alabaster: https://sphinx-themes.org/sample-sites/default-alabaster/kitchen-sink/tables/
• Furo: https://sphinx-themes.org/sample-sites/furo/kitchen-sink/tables/
• PyData: https://sphinx-themes.org/sample-sites/pydata-sphinx-theme/kitchen-sink/tables/
• Material: https://sphinx-themes.org/sample-sites/sphinx-material/kitchen-sink/tables/
• Karma: https://sphinx-themes.org/sample-sites/karma-sphinx-theme/kitchen-sink/tables/

(I didn't find an example of the opposite)

[agjohnson]

Bumping the release on this, 1.1 is a bug fix release.