Broken version of docutils doesn't render lists correctly

[esnyder-rve]

I'm working on a new layout for processing algorithms, and noticed a bug in docutils. Unordered lists weren't receiving bullets and were being styled with list-style: none;.

Issue:

Resolved:

The solution to this problem is reverting docutils to a previous version by explicitly adding docutils and the version to the REQUIREMENTS.txt file like:

docutils==0.6

[SrNetoChan]

I have confirmed this building it locally, but it seems to still be working correctly on the website. Maybe It differences in the building platform? @rduivenvoorde Do you know if we still use 20.04?

@esnyder-rve why docutils 0.6? it's from 2009. The newest version is from 0.19.

[DelazJ]

Hi
This issue happens only if you (re)pip install -r REQUIREMENTS.txt your environment in the venv file so will affect newcomers but shouldn't affect our server whose environment is not rebuilt every time afaik. The versions there are not the latest ones.
There have been some issues with recent versions of docutils/sphinx/rtd and I think things are getting stable now. Regarding the suggestion to move back to docutils 0.16, note that rtd theme at 1.2.0rc3 already fixes the issue you pointed (though still remains an issue with the bottom left menu, but that is also fixed in their master). The stable release should be out soon.
So I'm personally more incline to wait a few weeks and have things sorted magically and run the most recent versions of all.

[esnyder-rve]

I guess I miss-read some of the various version numbers being thrown around in these sources:

https://stackoverflow.com/questions/67542699/readthedocs-sphinx-not-rendering-bullet-list-from-rst-file

readthedocs/sphinx_rtd_theme#1115

It seems to be an issue with docutils>=0.17

[esnyder-rve]

@DelazJ Do we know what version of docutils the server is using?

[DelazJ]

@esnyder-rve As far I understand the docker image behind the docs build uses https://github.com/qgis/QGIS-Website/blob/master/REQUIREMENTS.txt

[esnyder-rve]

Ok, so docutils is not explicitly specified, and will be using the highest compatible version for the stated dependencies. I will check and see what actual version is being pulled.

[esnyder-rve]

@DelazJ The version that gets requested for the QGIS-Website REQUIREMENTS.txt is docutils<0.18;>=0.14 and version 0.16 is what gets installed. 0.16 is before the issue. So, we could either change the requirements file in this repo to match the QGIS-Website version (which will automagically pull a valid docutils, or we could explicitly set docutils to version 0.16.

[rduivenvoorde]

Hi, we recently updated the build images and uploaded them.
If you run pip freeze, you wil see the following versions:

$ docker run -exec -it qgis/sphinx_html_3  pip freeze
alabaster==0.7.13
attrs==18.2.0
Babel==2.11.0
certifi==2022.12.7
chardet==4.0.0
click==8.1.3
docutils==0.17.1
gitdb==4.0.10
GitPython==3.1.30
icalendar==5.0.4
idna==2.10
imagesize==1.4.1
importlib-metadata==6.0.0
Jinja2==3.1.2
MarkupSafe==2.1.2
packaging==23.0
pdflatex==0.1.3
Pygments==2.14.0
python-dateutil==2.8.2
python-slugify==4.0.1
pytz==2022.7.1
PyYAML==6.0
requests==2.25.1
rpl==1.8.0
six==1.16.0
smmap==5.0.0
snowballstemmer==2.2.0
Sphinx==4.5.0
sphinx-copybutton==0.5.1
sphinx-intl==2.0.1
sphinx-rtd-theme==1.1.1
sphinx-togglebutton==0.3.2
sphinxcontrib-applehelp==1.0.4
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==2.0.0
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.5
sphinxext-rediraffe==0.2.7
text-unidecode==1.3
transifex-client==0.14.4
urllib3==1.26.14
zipp==3.11.0

[rduivenvoorde]

Feel free to explicitly set a version in the requirements.txt, but as Harrissou tells: it is the requirements.txt of the Website master branch which is actually used for the building of the Docker images, NOT the one which is in the docs repo