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 #1322

[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 :+1:

[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 :+1:

[Paebbels]

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

[befeleme]

Hi, I did some visual testing of the theme with Sphinx 6.1.3 & docutils 0.19. I built two versions of the package docs, one with docutils 0.18 to compare. I noticed some output differences on my Fedora Linux 39, both on Chromium and Firefox. The screenshots come from the version built with docutils 0.19:

Edit: The screenshots come from version build with Sphinx 6.1.3 and docutils 0.19. The version build with Sphinx 5.0.3 and docutils 0.19 looked correctly. The culprit is probably Sphinx.

Giant tables and List tables jump out of the page border, the horizontal scrollbar doesn't appear

Long Sticky Nav: no [+] signs that indicate you can unfold the menu. On the screenshot there is 1.21 Example Sumbenu 1 actually clicked on - no change in the background that would indicate that, although the anchor was correctly loaded in the main page. The Submenus and Subsubmenus don't appear unfolded in the menu as they do with docutils 0.18.

[Paebbels]

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

[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: https://github.com/readthedocs/sphinx_rtd_theme/pull/1464

[humitos]

I double-checked the issues reported in https://github.com/readthedocs/sphinx_rtd_theme/issues/1323#issuecomment-1459938713 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 💯