rendering wrong in docutils 0.17 (unordered list, maybe more?)

[rkdarst]

I am giving this issue a broad title to collect other issues.

Problem

With docutils 0.17, it seems that bullet points don't render properly (the marker is missing), spacing too little (see images below)

An immediate fix is already in sphinx_rtd_theme==0.5.2 (just released), see (#1111, #1112 for issues, #1114 for fix), but that seems to only pin docutils==0.16 so other things that broke should still be tracked. I tested using the sphinx_rtd_theme docs themselves. #1112 shows this with a problem in the sidebar.

With 0.16:

With 0.17:

I originally thought this was another Sphinx problem, but it seems to not be present in the default Sphinx theme, but (only/at least) sphinx_rtd_theme.

Reproducible Project

sphinx_rtd_theme with docutils==0.16. Installed from the master branch pip install docutils=0.17 immediately after.

git clone https://github.com/readthedocs/sphinx_rtd_theme
cd sphinx_rtd_theme
git checkout ca2719b
pip install -e . -r docs/requirements.txt docutils==0.17
(cd docs ; make clean html)
# open build/html/changelog.html, does not work
pip install docutils==0.16
# refresh page, works

Error Logs/Results

none I see as relevant

Expected Results

...

Environment Info

• Python Version: Python 3.7.3
• Sphinx Version: Sphinx 3.5.3
• RTD Theme Version: ca2719b

Package                       Version   Location                          
----------------------------- --------- ----------------------------------
alabaster                     0.7.12    
Babel                         2.9.0     
certifi                       2020.12.5 
chardet                       4.0.0     
docutils                      0.16      
idna                          2.10      
imagesize                     1.2.0     
Jinja2                        2.11.3    
MarkupSafe                    1.1.1     
packaging                     20.9      
pip                           18.1      
pkg-resources                 0.0.0     
Pygments                      2.8.1     
pyparsing                     2.4.7     
pytz                          2021.1    
requests                      2.25.1    
setuptools                    40.8.0    
six                           1.15.0    
snowballstemmer               2.1.0     
Sphinx                        3.5.3     
sphinx-rtd-theme              0.5.2     /home/$USER/git/sphinx_rtd_theme
sphinxcontrib-applehelp       1.0.2     
sphinxcontrib-devhelp         1.0.2     
sphinxcontrib-htmlhelp        1.0.3     
sphinxcontrib-httpdomain      1.7.0     
sphinxcontrib-jsmath          1.0.1     
sphinxcontrib-qthelp          1.0.3     
sphinxcontrib-serializinghtml 1.1.4     
urllib3                       1.26.4    

See also

• Docutils 0.17 changelog: https://docutils.sourceforge.io/RELEASE-NOTES.html#id46 (lists changes in outputs)
• Newest docutils (v0.17) breaks rendering sphinx-doc/sphinx#9061 (sidebar again, looks like sphinx_rtd_theme in that example). I first reported this issue there but it could'nt be reproduced, seems to be sphinx_rtd_theme but not the default theme
• Plus some more PRs around sphinx-doc/sphinx

[Blendify]

In the 0.17 changelog, I do not see any mention of changes to unordered list. Perhaps this is a bug in sphinx?

[bugwelle]

This can also be seen in this project's docs as well:

• https://sphinx-rtd-theme.readthedocs.io/en/0.5.1/changelog.html
• https://sphinx-rtd-theme.readthedocs.io/en/latest/changelog.html

0.5.1	latest

By hard-coding docutils to v0.16, everything is back to normal:

pip3 install sphinx sphinx-rtd-theme docutils==0.16 

Edit:// My bad, the first post also mentions the changelog as an example 🤦

[rkdarst]

Yes, that's an example of the problem. When I was first trying to debug it I downgraded Sphinx, but it didn't help. I also tried the default Sphinx theme and unordered lists were OK. Of course, it could still be a bug whose root is somewhere else, but is only visible here... Unfortunately I haven't had time to go deeper, but now everyone has an example to look at.

[stsewd]

there was an error in the requirements #1118, docs from the theme should be good now https://sphinx-rtd-theme.readthedocs.io/en/latest/changelog.html

[Blendify]

I still want to address docutils 0.17 and sphinx4 support for the upcoming 1.0 release.

[1313e]

Names of a table of contents are now also rendered incorrectly in the contents menu on the left it seems.
This can be seen in my last render of my CMasher docs: https://cmasher.readthedocs.io/index.html
The table of contents names are now in white and left-aligned instead of blue and center-aligned.

[stsewd]

@1313e you need to set the theme version explicitly to 0.5.2 https://github.com/1313e/CMasher/blob/master/docs/requirements_docs.txt, the default version may not be the latest see https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html#don-t-rely-on-implicit-dependencies

[1313e]

Alright, will fix that.
However, docutils v0.17 will still cause the issue I mentioned.

[Blendify]

The issue with docutils 0.17 is the change from <div class="section"> to <section>.
Our css selector for lists is .section ol we will need to update our css to fix this.

I will have a fix out soon.

[Blendify]

Looked into this and we need to fix our css for the new semantic tags <main>, <section>, <header>, <footer>, <aside>, <figure>, and <figcaption>.

[GregDMeyer]

I have deeply read the above and am still a little confused which packages exactly I need to pin to get this to work. The docs build fine locally, but still don't have bullets on readthedocs.

My docs (most recent iteration of) requirements.txt, although I've found that many different combinations seem to successfully build locally and break on readthedocs:

Sphinx==5.3.0
ipykernel==6.21.0
nbsphinx==0.8.12
sphinx_rtd_theme==1.2.0rc2
myst-parser==0.18.1
docutils==0.18.1

My .readthedocs.yaml:

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

python:
  install:
  - requirements: docs/requirements.txt

edit: I should note that I've found that when I pin docutils==0.16, I get this error when building locally, I guess because I am using myst:

ERROR: Error in "include" directive:
unknown option: "parser".

.. include:: pubs.md
   :parser: myst_parser.sphinx_

[benjaoming]

@GregDMeyer since you are using Read the Docs, can you create a build with the configuration and point to the build log and a page where the issue is demonstrated? Thanks 🙏

[GregDMeyer]

@benjaoming Thanks for following up! I actually got it working since then by doing pip freeze > requirements.txt---pinning literally every package to the same version that I have locally. This doesn't feel like a particularly clean solution though ;-)

I just tried to revert to a commit where it was broken in order to give you an example in case you want to dig further, and... the docs look fine, from the exact same commit that was broken before. Is there some sort of caching or something that could cause this to happen? In any case, my bullet points look fine now, so I guess no biggie, I'm fine to not spend any more time worrying about it!