Align docutils version with sphinx_rtd_theme requirement

[stevepiercy]

With the upcoming release of sphinx_rtd_theme 3.0, docutils will get bumped to the following:

	docutils >0.18,<0.22

Should we remove the docutils pin in versions.cfg and allow sphinx_rtd_theme to handle its installation, or should we bump accordingly?

FTR, I ran into a version conflict when trying to install plone.restapi with buildout, and it took me a while to hunt down where it fell down:

Version and requirements information containing docutils:
  [versions] constraint on docutils: 0.18.1
  Base installation request: 'zest.releaser[recommended]', 'zest.pocompile', 'zestreleaser.towncrier', 'towncrier', 'readme', 'docutils', 'zpretty', 'i18ndude', 'coverage'
  Requirement of readme-renderer: docutils>=0.21.2
  Requirement of pyroma; extra == "recommended": docutils
  Requirement of readme-renderer[md]>=40: docutils>=0.21.2
While:
  Installing dependencies.
Error: The requirement ('docutils>=0.21.2') is not allowed by your [versions] constraint (0.18.1)

[davisagli]

@stevepiercy From what I see here, Zope's constraint for docutils (0.18.1) is compatible with the requirement from spinx_rtd_theme (docutils >0.18,<0.22).

The problem is that zest.releaser pulls in readme-renderer, and readme-renderer 0.44 requires docutils>=0.21.2

One way to resolve this would be to pin readme-renderer to an older version that still supports docutils 0.18.

Another way would be to add support for docutils 0.21.2 in sphinx_rtd_theme, and then update or remove the docutils pin here.

[stevepiercy]

Another way would be to add support for docutils 0.21.2 in sphinx_rtd_theme, and then update or remove the docutils pin here.

That's my preferred option, and I expect it will happen soon. See the linked PR in this issue description. I would prefer the removal of the pin from Zope, but maybe there is a valid reason to pin it similar to sphinx_rtd_theme v3.0.

[dataflake]

We pin all dependencies here, so a pin will stay. We can update it, sure.

[dataflake]

Just noticed that there is no newer sphinx_rtd_theme, so changing the pins will have to wait for that.

[stevepiercy]

I subscribed to notifications when that PR readthedocs/sphinx_rtd_theme#1576 is merged and when sphinx_rtd_theme releases v3.0. I'll follow up here when that happens.

[stevepiercy]

Alternatively to waiting for sphinx_rtd_theme to release v3, we could switch to a more modern theme and update the pins. Options include:

• https://github.com/plone/plone-sphinx-theme, which is based on:
• https://sphinx-book-theme.readthedocs.io/en/latest/, which is based on:
• https://pydata-sphinx-theme.readthedocs.io/en/stable/
• https://pradyunsg.me/furo/

Sphinx 8 was released last week: https://www.sphinx-doc.org/en/master/changes/8.0.html

[dataflake]

Alternatively to waiting for sphinx_rtd_theme to release v3, we could switch to a more modern theme and update the pins.

See #1221 for a suggestion using furo.

[dataflake]

I have merged #1221 and the result is visible at https://zope.readthedocs.io/en/latest/index.html. It's a nice clean look and the dependencies are cleaned up.

[icemac]

I really like, how it looks now. Thank you!

[loechel]

yes it looks nice now. But could we include the Zope Logo in the Docs.
Most Sphinx-Themes allow to set a custom Logo

@icemac would that also be a good theme for other Zope Projects like RestrictedPython?

[stevepiercy]

For the logo, see Adding a logo

[dataflake]

I have added the logo and also tweaked the blue link color to match the logo's blue color. That only looks well in the dark theme, so the light theme retains the default link color.

would that also be a good theme for other Zope Projects like RestrictedPython?

Yes of course.

[icemac]

@loechel wrote:

@icemac would that also be a good theme for other Zope Projects like RestrictedPython?

Why not, feel free to create a PR.