Table cell text does not wrap in ".. list-table::"

jsquyres commented 1 year ago

Problem

When using the sphinx_rtd_theme, text does not wrap in RST .. list-table:: cells like it does with the default Sphinx HTML theme. For example, the default Sphinx HTML builder theme renders like this:

(FWIW: the LaTeX and text Sphinx builders also render with wrapped text in the cell)

But the sphinx_rtd_theme renders the same RST like this:

The HTML difference between the two appears to be that the sphinx_rtd_theme has this set:

.wy-table-responsive table td, .wy-table-responsive table th {
    white-space: nowrap;
    white-space-collapse: collapse;
    text-wrap: nowrap;
}

Reproducible Project

conf.py:

html_theme = 'sphinx_rtd_theme'

index.rst:

Hello world.

.. list-table::
   :header-rows: 1
   :widths: 10 25

   * - Col 1
     - Col 2

   * - Content
     - This is a long sentence that should wrap nicely in the rendered
       table, but just to make sure, we'll make it super, extra,
       incredibly long.

Error Logs/Results

$ rm -rf _build && sphinx-build -M html . _build 
Running Sphinx v6.2.1
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                        
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                         
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

Expected Results

I expect the words to wrap in the cell, like they do with the default Sphinx HTML builder theme, and with other Sphinx builders.

Environment Info

Python Version: 3.11.4
Sphinx Version: 6.2.1
RTD Theme Version: same results with 1.3.0rc1 and 1.2.2 (didn't manually test back further). This behavior has been around for a long time; I didn't realize that other Sphinx themes / builders wrapped words in a cell until very recently (which is why I didn't file this issue until now).

jsquyres commented 1 year ago

Filed PR #1506 which potentially fixes the issue.

jsquyres commented 1 year ago

I noted on PR #1506:

I am not an expert in front-end dev things, but it looks like theme.css might actually be generated, and the source of the wy-table-responsive CSS stanzas comes from https://github.com/snide/wyrm/blob/master/sass/wyrm_core/_table.sass#L144-L151

Unfortunately, it looks like wyrm_core hasn't changed since early 2015. Indeed, https://github.com/snide/wyrm/pull/13 is a PR about sphinx_rtd_theme, but it has sat there unmodified and un-merged since 2018. I'm guessing that filing a PR over there to change the upstream source is unlikely to get merged.

What's the best way to get word wrapping enabled in sphinx_rtd_theme tables?

jcphill commented 11 months ago

I think you can remove the "Needed: replication" label since the issue is visible at https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/lists_tables.html#list-tables

Korne127 commented 1 month ago

For anyone else who finds this in the future (like me), here's a tutorial on how to fix this so you don't have to look through all these linked commits:

The CSS code that fixes this and needs to be embedded is:

.wy-table-responsive table td, .wy-table-responsive table th {
    white-space: normal;
}

(One project uses table.reece-wrap instead of table, but that's just because they explicitly marked the tables with :class: reece-wrap, so this won't generally work).

To include this CSS code, some projects set a custom CSS file as the html_style like html_style = 'custom.css' in conf.py. This file needs to include @import 'css/theme.css'; in the beginning to use the theme and only override parts of it. However, what I think is even better is to use html_css_files = ["custom.css"]. This explicitly loads CSS files additionally to the theme and allows overriding specific components and therefore doesn't require any @import 'css/theme.css'.

readthedocs / sphinx_rtd_theme