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

jsquyres · 2023-08-19T18:57:33Z

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).

The text was updated successfully, but these errors were encountered:

jsquyres · 2023-08-19T19:09:34Z

Filed PR #1506 which potentially fixes the issue.

The sphinx_rtd_theme does not properly handle wrapping long lines in table cells when rendering to HTML due to a CSS issue (see readthedocs/sphinx_rtd_theme#1505). Until the issue is fixed upstream in sphinx_rtd_theme, we can simply override the CSS here. This commit overrides the CSS in conf.py and also touches up some places where we previously tried to work around the lack of word wrapping. Signed-off-by: Jeff Squyres <[email protected]>

The sphinx_rtd_theme does not properly handle wrapping long lines in table cells when rendering to HTML due to a CSS issue (see readthedocs/sphinx_rtd_theme#1505). Until the issue is fixed upstream in sphinx_rtd_theme, we can simply override the CSS here (in conf.py). The PRRTE docs don't use the RST ".. list-table::" directive much, so this change won't really have much of an effect here. However, OMPI and PMIx were updated with this conf.py change, so we might as well keep all 3 projects more-or-less in sync. Signed-off-by: Jeff Squyres <[email protected]>

The sphinx_rtd_theme does not properly handle wrapping long lines in table cells when rendering to HTML due to a CSS issue (see readthedocs/sphinx_rtd_theme#1505). Until the issue is fixed upstream in sphinx_rtd_theme, we can simply override the CSS here. This commit overrides the CSS in conf.py and also touches up some places where we previously tried to work around the lack of word wrapping. Signed-off-by: Jeff Squyres <[email protected]>

The sphinx_rtd_theme does not properly handle wrapping long lines in table cells when rendering to HTML due to a CSS issue (see readthedocs/sphinx_rtd_theme#1505). Until the issue is fixed upstream in sphinx_rtd_theme, we can simply override the CSS here (in conf.py). The PRRTE docs don't use the RST ".. list-table::" directive much, so this change won't really have much of an effect here. However, OMPI and PMIx were updated with this conf.py change, so we might as well keep all 3 projects more-or-less in sync. Signed-off-by: Jeff Squyres <[email protected]>

The sphinx_rtd_theme does not properly handle wrapping long lines in table cells when rendering to HTML due to a CSS issue (see readthedocs/sphinx_rtd_theme#1505). Until the issue is fixed upstream in sphinx_rtd_theme, we can simply override the CSS here. This commit overrides the CSS in conf.py and also touches up some places where we previously tried to work around the lack of word wrapping. Signed-off-by: Jeff Squyres <[email protected]> (cherry picked from commit 8e9a24f)

jsquyres · 2023-08-24T23:42:23Z

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, snide/wyrm#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?

The sphinx_rtd_theme does not properly handle wrapping long lines in table cells when rendering to HTML due to a CSS issue (see readthedocs/sphinx_rtd_theme#1505). Until the issue is fixed upstream in sphinx_rtd_theme, we can simply override the CSS here. This commit overrides the CSS in conf.py and also touches up some places where we previously tried to work around the lack of word wrapping. Signed-off-by: Jeff Squyres <[email protected]> (cherry picked from commit 9b3bdf8)

The sphinx_rtd_theme does not properly handle wrapping long lines in table cells when rendering to HTML due to a CSS issue (see readthedocs/sphinx_rtd_theme#1505). Until the issue is fixed upstream in sphinx_rtd_theme, we can simply override the CSS here (in conf.py). The PRRTE docs don't use the RST ".. list-table::" directive much, so this change won't really have much of an effect here. However, OMPI and PMIx were updated with this conf.py change, so we might as well keep all 3 projects more-or-less in sync. Signed-off-by: Jeff Squyres <[email protected]> (cherry picked from commit 9ef7478)

The sphinx_rtd_theme does not properly handle wrapping long lines in table cells when rendering to HTML due to a CSS issue (see readthedocs/sphinx_rtd_theme#1505). Until the issue is fixed upstream in sphinx_rtd_theme, we can simply override the CSS here. This commit overrides the CSS in conf.py and also touches up some places where we previously tried to work around the lack of word wrapping. Signed-off-by: Jeff Squyres <[email protected]> (cherry picked from commit 9b3bdf8)

The sphinx_rtd_theme does not properly handle wrapping long lines in table cells when rendering to HTML due to a CSS issue (see readthedocs/sphinx_rtd_theme#1505). Until the issue is fixed upstream in sphinx_rtd_theme, we can simply override the CSS here (in conf.py). The PRRTE docs don't use the RST ".. list-table::" directive much, so this change won't really have much of an effect here. However, OMPI and PMIx were updated with this conf.py change, so we might as well keep all 3 projects more-or-less in sync. Signed-off-by: Jeff Squyres <[email protected]> (cherry picked from commit 9ef7478)

jcphill · 2023-09-22T13:49:48Z

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

The sphinx-rtd-theme currently disables word wrap in table cells due to a bug: readthedocs/sphinx_rtd_theme#1505 This is fixed by overriding the CSS and enabling word wrapping.

The sphinx_rtd_theme does not properly handle wrapping long lines in table cells when rendering to HTML due to a CSS issue (see readthedocs/sphinx_rtd_theme#1505). Until the issue is fixed upstream in sphinx_rtd_theme, we can simply override the CSS here. This commit overrides the CSS in conf.py and also touches up some places where we previously tried to work around the lack of word wrapping. Signed-off-by: Jeff Squyres <[email protected]>

Korne127 · 2024-07-30T17:14:43Z

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'.

Previously, tables with much text in a row had had scroll bars to scroll through all the text instead of automatic line breaks. This is due to an open issue in the sphinx read the docs theme (readthedocs/sphinx_rtd_theme#1505). A workaround has been implemented to fix this until the issue is resolved. Additionally, grid tables have been replaced by list tables. This allows explicitly setting the width of the columns and makes it easier to change the tables in the future.

capital-G · 2024-09-28T10:47:35Z

This is still a thing in 3.0 :/ Thanks for mentioned fixes!

jsquyres added Bug A bug Needed: replication Bug replication is required labels Aug 19, 2023

jsquyres linked a pull request Aug 19, 2023 that will close this issue

Fix word wrapping in RST list-table #1506

Open

jsquyres mentioned this issue Aug 21, 2023

docs: fix HTML word wapping in table cells open-mpi/ompi#11868

Merged

jsquyres mentioned this issue Aug 21, 2023

docs: fix HTML word wapping in table cells openpmix/prrte#1778

Merged

jsquyres mentioned this issue Aug 21, 2023

v5.0.x: docs: fix HTML word wapping in table cells open-mpi/ompi#11870

Merged

This was referenced Sep 4, 2023

Multiple commits openpmix/openpmix#3143

Merged

Multiple commits openpmix/openpmix#3144

Merged

Multiple commits openpmix/prrte#1784

Merged

Multiple commits openpmix/prrte#1785

Merged

jsstevenson mentioned this issue May 13, 2024

docs: fix typos and clean up table ga4gh/vrs#495

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

jsquyres commented Aug 19, 2023 •

edited

Loading

jsquyres commented Aug 19, 2023

jsquyres commented Aug 24, 2023

jcphill commented Sep 22, 2023

Korne127 commented Jul 30, 2024 •

edited

Loading

capital-G commented Sep 28, 2024

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

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

Comments

jsquyres commented Aug 19, 2023 • edited Loading

Problem

Reproducible Project

Error Logs/Results

Expected Results

Environment Info

jsquyres commented Aug 19, 2023

jsquyres commented Aug 24, 2023

jcphill commented Sep 22, 2023

Korne127 commented Jul 30, 2024 • edited Loading

capital-G commented Sep 28, 2024

jsquyres commented Aug 19, 2023 •

edited

Loading

Korne127 commented Jul 30, 2024 •

edited

Loading