Adds support for docutils 0.19

[benjaoming]

Fixes #1323

Blocked by #1304 (also contains this PR)

Release notes of docutils 0.19 look good: https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-19-2022-07-05

Noting "Drop support for Python 2.7, 3.5, and 3.6."

[benjaoming]

Some Sphinx versions do not put an upper bound on their docutils dependency. This PR requires a full understanding of which Sphinx versions without this upper bound that will also break.

[benjaoming]

From docutils release notes

Docutils 0.18.x is the last version supporting Python 2.7, 3.5, and 3.6.

On Read the Docs, this means the number of projects with old versions of Sphinx that will also have docutils 0.19 are limited to those that have chosen "CPython 3.x" which currently creates environments with Python 3.7. This comments about affect docutils 0.18 projects already how the set of affected projects is quite limited: #1304 (comment)

[benjaoming]

Some Sphinx versions do not put an upper bound on their docutils dependency. This PR requires a full understanding of which Sphinx versions without this upper bound that will also break.

We can probably find a lot of assertions in the CI test matrix, which should contain these combinations of Sphinx>=1.6...3.5.6+docutils 0.19 and assure that they work (needs verification).

Looking forwards to dropping some backwards compatibility in future versions of sphinx-rtd-theme 😇

[hardyoyo]

+1 from the community. We have a project that uses this theme for its docs, I've gotten the docs to work on a Python 3.8.16 install, by manually installing docutils 0.19, but now we have occasional warnings, like this one from pipdeptree:

sphinx-rtd-theme==1.2.0
  - docutils [required: <0.19, installed: 0.19]

Warnings can be ignored, of course, but, it doesn't feel great.

[humitos]

Just wanting to note that docutils 0.20 is already released (https://pypi.org/project/docutils/0.20/)

[benjaoming]

Just wanting to note that docutils 0.20 is already released

Oh 🙈 It'd be nice to have just docutils 0.19 introduced in one release, and then move to docutils 0.20 for the next one. Recalling the fallout of docutils 0.18 support, it's nice to limit the scope of Q&A'ing as well as subsequent troubleshooting.

[humitos]

I QAed all the current supported versions by running these commands:

Open all the pages built with Docutils 0.19 (this PR)

gh pr checkout 1336
tox run -r -x "tox.envlist=py310-sphinx{53,62,72}-qa"
# Open all the versions with firefox
firefox file:///home/humitos/rtfd/code/sphinx_rtd_theme/.tox/py310-sphinx72-qa/tmp/html/demo/demo.html file:///home/humitos/rtfd/code/sphinx_rtd_theme/.tox/py310-sphinx62-qa/tmp/html/demo/demo.html file:///home/humitos/rtfd/code/sphinx_rtd_theme/.tox/py310-sphinx53-qa/tmp/html/demo/demo.html

Then, open the same pages built with Docutils 0.18.1 (current master)

git checkout master
tox run -r -x "tox.envlist=py310-sphinx{53,62,72}"
# Open all the versions with firefox
firefox file:///home/humitos/rtfd/code/sphinx_rtd_theme/.tox/py310-sphinx72/tmp/html/demo/demo.html file:///home/humitos/rtfd/code/sphinx_rtd_theme/.tox/py310-sphinx62/tmp/html/demo/demo.html file:///home/humitos/rtfd/code/sphinx_rtd_theme/.tox/py310-sphinx53/tmp/html/demo/demo.html

I compared page by page, tab by tab, and I didn't find any visual difference. I'd say we are ready to move forward here. I think it would be good to publish a 2.1rc0 first and ask some users to see how it goes.