Rendering of Definition List/Option List/Field List

[bearsh]

Problem

Definition List/Option List/Field List are rendered differently on ReadTheDocs than in a local build. See attached screenshots:

on https://sphinx-rtd-theme.readthedocs.io/en/0.5.0/

local build:

Environment Info

• Python Version: 3.6.8
• Sphinx Version: 3.1.2
• RTD Theme Version: 0.5.0

[jobec]

Same here.
The CSS code seems to have disappeared completely.

[jobec]

It seems to have disappeared in commit ff594d2 by @agjohnson

[agjohnson]

Oops, I see the issue. Nothing disappeared, but the versioned docs are being built with sphinx_rtd_theme==0.4.3 still. The last PR build looks fine:
https://sphinx-rtd-theme--981.org.readthedocs.build/en/981/demo/lists_tables.html#definition-lists

PR builds use the local version of the theme, not a pinned version of the PyPI theme. I'd prefer if the versioned docs are built using the local theme as well -- that is, 0.5.0 docs use the local 0.5.0 of the theme -- but I think there were some objections to that previously.

[bearsh]

@agjohnson thanks for the info.

so the design change was intended. that's good to know although I'm not 100% happy with it. I like it for the field list but not for the definition list. for the option list I'm uncertain... a little bit off topic but is the a easy way to revert it locally (css override) for the definition list but leave it for the field list?

[jobec]

To bring back the definition list style, I added this CSS via a custom stylesheet file:

.rst-content dl:not(.docutils) dt:first-child {
  margin-top: 0;
}
.rst-content dl:not(.docutils) dt {
  display: table;
  margin: 6px 0;
  font-size: 90%;
  line-height: normal;
  background: #e7f2fa;
  color: #2980B9;
  border-top: solid 3px #6ab0de;
  padding: 6px;
  position: relative;
}

@agjohnson , are you 100% sure the removal of those styles was intentional, rather than by mistake?

[agjohnson]

The intended styles are available at https://sphinx-rtd-theme--981.org.readthedocs.build/en/981/demo/lists_tables.html#definition-lists

These styles match sphinx_rtd_theme version 0.4.2 with the Sphinx html4 writer. The first image you posted, sphinx_rtd_theme with the Sphinx html5 writer, is mostly buggy display, those were not intended to be the styles.

Custom CSS should not be required, use 0.5.0 and the HTML5 writer.

@agjohnson , are you 100% sure the removal of those styles was intentional, rather than by mistake?

Yes, intentional, to match the display styles of sphinx_rtd_theme 0.4.3 and html4 writer. 0.4.3 does not support the html5 writer.

[sbslee]

Hello! I’m very glad I found this because I believe I'm experiencing a similar issue. In my case, the option lists are rendered very stylishly on my local laptop, but they look really ugly in the web.

This is what I see from my local laptop:

This is what's rendered on the web (https://pypgx.readthedocs.io/en/latest/commands.html#options):

@agjohnson, how can I tell readthedocs to use the "HTML5 writer" and sphinx_rtd_theme==0.5.0? I tried simply adding sphinx==3.1.2 and sphinx_rtd_theme==0.5.0 to the reqruements_dev.txt file, but it didn't do the trick. I also tried explicitly telling readthedocs to use the changed reqruements_dev.txt file in Project > Admin > Advanced Settings > "Requirements file" but it didn't work. Finally, I tried wiping build environment because of this issue but without success. It seems, no matter what I do, readthedocs keeps using lower versions of sphinx and sphinx_rtd_theme (i.e. sphinx<2 sphinx-rtd-theme<0.5 readthedocs-sphinx-ext<1.1), as shown in my latest build attempt.

Would greatly appreciate if you or anyone else can help me start enjoying the beautiful rendering of readthedocs again!

[Daltz333]

Add the following to your conf.py

# Enable HTML5 writer support
html_experimental_html5_writer = True

[sbslee]

@Daltz333 Thank you very much for the reply! I followed your advice for one of my projects, and it is now showing the intended style for the option lists (thanks to html5), except they are still in "buggy display" as agjohnson mentioned above (https://stargazer.readthedocs.io/en/latest/documentation.html#options). I think it's because RTD is still using a lower version of sphinx_rtd_theme (the build history says it used v0.4.3). If you don't, could you please teach me how to properly specify a higher version of sphinx_rtd_theme (==v0.5.0)?

[Daltz333]

@sbslee To specify a version of sphinx_rtd_theme, you'll need to create a requirements.txt file with the line

sphinx_rtd_theme==0.5.0

and then point RTD to this in your RTD interface, or through a RTD configuration file.

[sbslee]

@Daltz333 Thank you! I totally forgot about the existence of the RTD configuration file (.readthedocs.yml)! I got it confused with the conf.py file. Once I updated the configuration file, it finally successfully installed sphinx_rtd_theme==0.5.0. However, it seems the "buggy display" is still there (https://stargazer.readthedocs.io/en/latest/documentation.html#options) and I don't know what the problem is anymore... As per agjohnson's advise, I am using sphinx_rtd_theme==0.5.0 and html5.

[Daltz333]

I also reproduced the issue. Even when specifying the HTML4 builder. I'm quite sure it's an issue when using Sphinx > 3. Since this repo uses an extremely old version of Sphinx for some reason.

[sbslee]

Hi, I just wanted to give an update to those who might be interested: For whatever reason, my website started displaying the option lists properly. I didn't change anything, it just got fixed (I'm using HTML5 and sphinx_rtd_theme==0.5.0; for more information, read above). My guess is it has to do with cookies/cache being updated (but I'm not an expert on this)?

[Daltz333]

@sbslee what version of Sphinx do you use btw?

[sbslee]

@Daltz333 Looking at the latest build history (https://readthedocs.org/projects/stargazer/builds/11578782/), I think Sphinx-1.8.5 was used to generate the website.

[adam-grant-hendry]

@agjohnson This has persisted into version 0.5.0. The CSS style provided by @jobec fixed my issue. Will this be fixed?

[sebazza]

Just a quick note to anyone else who may find themselves here, looking for a solution to the misplaced CSS for these lists. If using pip, make sure your requirements.txt file has version 0.5.0 for sphinx-rtd-theme (I was using 0.5.0rc1).

sphinx-rtd-theme==0.5.0

And run pip install -r requirements.txt, to ensure the right package version is installed. This is key. Use pip list to verify the installed package versions.

Once I has updated to the latest release and rebuilt the HTML using Sphinx, these lists formatted correctly.

[Blendify]

This has been fixed except for the spacing issues with lists, to keep track of that issue see #1029. For those still experiencing the other issues make sure you are using spinx_rtd_theme 0.5.1 or greater and are not using the html4 writer.