Relax docutils pin to allow build to support sphinx>=6 and python>=3.11

[valeriupredoi]

Hey guys, the pin on docutils in your meta file makes this package not able to support the latest sphinx and python >=3.11. See example minimal en that fails to solve:

---
name: sphinx-py311
channels:
  - conda-forge
  - nodefaults

dependencies:
  - sphinx ==6.1.3
  - python ==3.11
  - sphinx_rtd_theme

This results in:

Could not solve for environment specs
Encountered problems while solving:
  - package sphinx-6.1.3-pyhd8ed1ab_0 requires docutils >=0.18,<0.20, but none of the providers can be installed

If you don't mind me, I'll try a PR freeing up the pin on docutils now 👍

[chohner]

The recipe here is simply following whatever the upstream package is defining:

install_requires = 
	sphinx >=1.6,<7
	docutils <0.19
	sphinxcontrib-jquery >=2.0.0,!=3.0.0 ; python_version > '3'

Looking at your error message - do you know where the restriction against docutils ==0.18 comes from?

[valeriupredoi]

hi @chohner - the problem is with the pin on docutils in the sphinx_rtd_theme package - if one needs the latest sphinx with python=3.11, that pin blocks the env to solve, there has to be some dependency of sphinx>=6.1.3 that needs docutils to be >0.19 - I don't know which one though, would you want me to look into that?

[chohner]

Sphinx itself only requires docutils >=0.18,<0.20, I'm surprised a sub-dependency has tighter requirements.

Could you try to figure out which exact package it could be? Maybe running the resolver with some additional verbosity?

[chohner]

After poking around myself: docutils 0.18.x isn't tagged to support python 3.11, which is the bottleneck here. I tried running the docutils tests to check whether we could relax the python3.10 pin in retrospect but the tests don't even run on Python 3.11.

imo the cleanest way forward would be for sphinx_rtd_theme to support docutils 0.19.x, which currently seems blocked: readthedocs/sphinx_rtd_theme#1323

Update:
after modifying the test runner and one test to their 0.19 versions, it seems like docutils 0.18.1 does pass on python 3.11:

Ran 1469 tests in 2.529s

OK (skipped=4)
Elapsed time: 2.712 seconds

[valeriupredoi]

hi @chohner my apologies for replying rather late - Easter break and all. Cheers muchly for your investigations! OK cool - let me try pin docutils==1.18.1 in our env and see where things go from there 😁

[valeriupredoi]

sadly no go with docutils>=1.18.1 either - we're just gonna let sphinx and sphinx_rtd_theme unpinned, therefore have sphinx=5 until readthedocs/sphinx_rtd_theme#1323 gets sorted out 🍺

[AndrewAnnex]

@valeriupredoi think I am running into an issue with this theme and found this issue, readthedocs/sphinx_rtd_theme#1323 was resolved yesterday it appears but any chance this would be quick to fix now?

[chohner]

the easiest would be to wait for an release of version 2.0 of sphinx_rtd_theme, as it will support sphinx >=5 and docutils <0.21, see https://github.com/readthedocs/sphinx_rtd_theme/blob/master/docs/changelog.rst

[AndrewAnnex]

@chohner hmm think that was what I was thinking of in the end. looks like that may be happening soon

[chohner]

should've been fixed with f62635c