Change Sphinx theme used for Zope documentation

[dataflake]

In a discussion about the never ending annoyance that the currently used sphinx_rtd_theme forbids the latest docutils (-> #1220) Steve Piercy suggested two other themes, the plone-sphinx-theme that is now used for Plone 6 documentation, and furo, another lightweight and modern theme.

This PR updates all compatible dependencies and switches the documentation theme to furo. You can test it all locally and look at the furo-themed documentation by running bin/tox -edocs and then opening the page at docs/_build/html/index.html.

This PR is a suggestion, not a "must". I do like the theme and as a maintainer I do like the fact that I have to stop worrying about dependency restrictions that make no sense.

I have taken a quick look at plone-sphinx-theme as well, but it explicitly only supports Python 3.9 and up with no fallback for Python 3.8. I respect the Plone team's decision to drop Python 3.8 support, but we're not there yet. Our documentation should build on all Python versions supported by Zope.

[stevepiercy]

I'm not sure about the conflicting versions of docutils and Sphinx in these changes. Should they be consistent or different?

[dataflake]

I'm not sure about the conflicting versions of docutils and Sphinx in these changes. Should they be consistent or different?

They are different for Python 3.8 because Sphinx 8 does not support Python 3.8. That means there must be a separate lower pin for Sphinx, which in turn requires a separate lower pin for docutils. The section with the lower pins only applies on Python 3.8.

[stevepiercy]

Thanks for the explanation. I overlooked the section header.

[icemac]

LGTM from reading through the diff. I did not take a look at the result.

[mauritsvanrees]

Thanks!

For those who want to compare:

• The Zope 4 docs use the old theme: https://zope.readthedocs.io/en/4.x/
• The Zope 5 docs use the new theme: https://zope.readthedocs.io/en/latest/

[dataflake]

If you compare https://zope.readthedocs.io/en/4.x/INSTALL.html and https://zope.readthedocs.io/en/latest/INSTALL.html you can also see how local tables of content are handled. They are stuck in their fixed location on the page with the RTD theme and thus scroll out of view while remaining in view on the right hand side with the furo theme.

[stevepiercy]

Dark mode and better typography in Furo eases my eye strain, too. The right-side navigation also has scroll-spy, highlighting the current location within the page.

[dataflake]

"scroll spy" - cool term. Never heard that before.

[stevepiercy]

I first saw it Twitter Bootstrap. https://getbootstrap.com/docs/3.4/javascript/#scrollspy