Support for docutils 0.19.x

[benjaoming]

docutils 0.19 has been released.

1. We should add support for and test docutils 0.19.x
2. report any issues, beyond the issues with docutils 0.18 reported in docutils 0.18 support issues #1322
3. remove brackets around footnote reference links Support for docutils 0.19.x #1323 (comment)

[gabicca]

Hello, I wanted to note that there is a requirement incompatibility issue with the latest m2r2 package what was released on 11 Aug:

  docutils>=0.19 from m2r2==0.3.3
  docutils<0.18 from sphinx_rtd_theme==1.0.0

As you can see, they don't support docutils below 0.19 anymore, so if sphinx_rtd_theme could start supporting 0.19, that would be great.

Thanks!

[benjaoming]

Thanks for this input! We'll be getting something out the door soon. First step is docutils 0.18, and after a few fixes for this support, we can see if it's feasible to add docutils 0.19.

If you are able to do testing with docutils 0.19, that'd be great. It's helpful to know your impressions. The type of testing that's needed is mostly around visual regression testing - it's a bit manual and tedious since it involves looking at the "correct"/old version and then compare to the proposed new version.

[gabicca]

Thanks for this input! We'll be getting something out the door soon. First step is docutils 0.18, and after a few fixes for this support, we can see if it's feasible to add docutils 0.19.

If you are able to do testing with docutils 0.19, that'd be great. It's helpful to know your impressions. The type of testing that's needed is mostly around visual regression testing - it's a bit manual and tedious since it involves looking at the "correct"/old version and then compare to the proposed new version.

Thanks @benjaoming for the quick reply and taking actions. Sorry for not getting back to you sooner. This week and next week will be busy for me and won't be able to do any testing. After that, unless the PR is already merged and the issue resoled, what I can do is use your branch to install sphinx_rtd_theme and see if our docs build properly. I could do minor comparisons testing as well, but won't be able to spend more than a few hours on it.

[benjaoming]

There is a PR build available where visual regression testing can be done.

https://sphinx-rtd-theme--1336.org.readthedocs.build/en/1336/

I verified from the build that docutils 0.19 is also used here.

[Paebbels]

Any progress on supporting latest docutils?

---

/cc @umarcor

[benjaoming]

@Paebbels @umarcor

Any progress on supporting latest docutils?

The upgrade is blocked. We'll be shipping 1.1 without the support. 1.2 will follow with docutils 0.18 and perhaps docutils 0.19 support, too.

[ssbarnea]

@benjaoming Sorry to ask but I do not see any other version than 1.0.0 and docutils 0.19 was released more than an year ago, and we cannot blame sphinx for not supporting it.

The conflict is caused by:
    sphinx 5.1.1 depends on docutils<0.20 and >=0.14
    sphinx-rtd-theme 1.0.0 depends on docutils<0.18
    The user requested (constraint) docutils==0.19

[benjaoming]

Hi @ssbarnea! We have a 1.1.0b3 out. If there's no incoming blockers, we'll release 1.1.0 next week and hurry to release 1.2.0 soon after (that will be the release with the docutils update).

We do realize the importance, but there are many documentation projects that do not pin the theme, so we try to be cautious about the pace 👍

[befeleme]

I looked at the rendered build and found these differences, comparing to the current "live" documentation of the project (on https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html). There is one issue I spotted on my Firefox 105. It doesn't look much different from the docs created with docutils 0.18

Before: references had just numbers, now: the numbers are encapsulated with []:

[benjaoming]

thanks so much @befeleme for evaluating this - it takes a long time to visually identify these changes and it's easy to miss something, so really appreciate it!

Even if it's a smaller ting, we'll make sure to fix it so we can aim for a "zero changes" experience. If anyone wants brackets here (it might be easier to see, looks like Wikipedia etc), it's absolutely okay to open an issue to add them 👍

[Paebbels]

With the update of Sphinx 6.0, now a newer docutils version is required. Any progress on this?

[eeintech]

I can confirm, that navigation is broken with docutils 0.19 and Sphinx 6.x in Chrome on Windows 11.

After messing up with the toctree directive, conf.py and other hacks, simply rolling back to 5.3.0 did it for me... too bad this theme still does not support Sphinx 6.0!

[kloczek]

BTW .. what about support sphinxcontrib-jquery 3.0.0? 🤔

[stefaneidelloth]

The conflict is caused by:
sphinx 6.2.1 depends on docutils<0.20 and >=0.18.1
myst-parser 2.0.0 depends on docutils<0.21 and >=0.16
sphinx-rtd-theme 1.0.0 depends on docutils<0.18

[kloczek]

sphinx-rtd-theme 1.0.0 depends on docutils<0.18

In mean time I've tested current sphinx-rtd-theme with

[tkloczko@pers-jacek SPECS]$ grep "BuildRequires:.*python3dist(sphinx-rtd-theme)" * -l |wc -l
107

other python modules (mostly on generate documentation) it works fine with latest docutils and so far I was not able to find anything wrong.
IMO pinning to lover version of the docutils is not necessary.

[benjaoming]

@stefaneidelloth if you can run sphinx-rtd-theme in version 1.2.x, you shouldn't have that version conflict as it supports docutils 0.18.x.

[stefaneidelloth]

@stefaneidelloth if you can run sphinx-rtd-theme in version 1.2.x, you shouldn't have that version conflict as it supports docutils 0.18.x.

Thank you for the hint.
Following seems to be the combination with the highest version numbers still working:

sphinx==6.2.1
myst-parser==2.0.0
sphinx-rtd-theme==1.2.2

Related:
#1464

[humitos]

I double-checked the issues reported in #1323 (comment) and I wasn't able to notice any difference with Sphinx==6.2.x and docutils==0.19. So far, I haven't find any issue on any page from the current theme documentation 💯