docutils 0.20 cannot be used with Sphinx 7.0.0

[rikardn]

Describe the bug

When trying to use the latest version of docutils together with Sphinx 7.0.0 I get the following error:

 The conflict is caused by:
    The user requested docutils==0.20
    sphinx 7.0.0 depends on docutils<0.20 and >=0.18.1

How to Reproduce

In requirements.txt:

docutils==0.20
sphinx==7.0.0

Environment Information

Not needed

Sphinx extensions

No response

Additional context

No response

[AA-Turner]

Please would you explain your requirements here? Sphinx specifies the versions of Docutils that it works with to avoid breakage on a new Docutils version. Why do you want to explicitly install Docutils 0.20?

A

[rikardn]

Good question.

I guess there isn't any current problem I am trying to solve, but rather trying to avoid potential future problems that typically arise when packages cap newer versions of dependencies. I can see two potential problems:

1. My package could have two dependencies that both depend on docutils. One might in a future version set a lowest version of 0.20 which would then create an unresolvable conflict downstream. To be honest this isn't the case for me when it comes to docutils, but it has happened many times before for other packages.

2. One of the users of my package might need another package that depends on docutils 0.20 that would cause the same conflict.

As the author of a downstream package I would like my dependencies to never set caps of versions of dependencies upstream because I cannot do anything about it. Lets say there wasn't an upper cap, and it turns out that Sphinx doesn't work with the new version of docutils, then I could block it for my users in requirements.txt for example. The opposite requires the upstream package to lift the cap, which is kind of what I am trying to do with this issue before anyone further downstream gets hit.

Are you sure that docutils 0.20 doesn't work with Sphinx 7.0.0? Perhaps this is something I could test?

[mgeier]

This question wasn't directed to me, but I'd still like to answer it:

Why do you want to explicitly install Docutils 0.20?

docutils 0.18 and 0.19 have a bug that's affecting bibliographies: mcmtroffaes/sphinxcontrib-bibtex#309.
A fix for this has already been brought forward last August, and it has finally been released with docutils 0.20.

Are you sure that docutils 0.20 doesn't work with Sphinx 7.0.0?

Apparently it would work fine if there wasn't an upper version bound: #11411.

About 2 years ago there was a fad in the Python community to add upper version bounds everywhere. Most project have stopped doing that by now, maybe Sphinx should also stop that?

Anyway, it looks like we'll be able to use docutils 0.20 after next Sphinx release.

[AA-Turner]

I've released Sphinx 7.0.1 which declares support in the project metadata for Docutils 0.20 (as @mgeier pointed out, there is no technical restriction on using Sphinx 7.0.0 with Docutils 0.20).

A

[rikardn]

Thanks for the fix and the extra release!