specify sphinx version

[acturner]

Problem: docutils==0.18 was recently pushed and breaks the same as docutils==0.17.
Solution: Use docutils<0.17 instead of docutils!=0.17.0

[jorisvandenbossche]

Normally sphinx already limits the version of docutils to < 0.18 (until they officially support it, sphinx-doc/sphinx#9777), in which case I would think we don't need to pin as well.

What version of sphinx are you using? And do you have an example of something that breaks? (there might also be specific things in our theme and not just sphinx that is impacted by the new docutils release)

[acturner]

@jorisvandenbossche When you pip install pydata-sphinx-theme I am currently seeing that it resolves to docutils==0.17.1. To your knowledge should this version work with pydata-sphinx-theme?

I will get back to you with a minimal example to reproduce the error. I was using poetry when I encountered it, which may have resolved to a different version of docutils (I was able to fix it by requiring docutils<0.18, hence the pull request).

[jorisvandenbossche]

It might be that you are (for some other reason) getting an older version of sphinx that does not include those stricter version requirements on sphinx (see also sphinx-doc/sphinx#9777 (comment))

[acturner]

@jorisvandenbossche I've confirmed this is a problem with poetry resolving to sphinx==3.5.3 which just specified docutils>=0.14. Obviously this is not inherently a problem in pydata-sphinx-theme, but I would say that if you are relying on sphinx specifying docutils<0.18, perhaps it would make sense to require sphinx>=4 (I will update this PR to do this in case you agree).

[jorisvandenbossche]

I've confirmed this is a problem with poetry resolving to sphinx==3.5.3 which just specified docutils>=0.14

It might be interesting to check where this pin for sphinx is coming from. Sphinx actually has a 3.5.4 release that specifically fixed this.

[choldgraf]

I'd be in favor of supporting the latest two major releases of Sphinx (and testing against them). I think it's too restrictive if this theme only works with the latest major release

[choldgraf]

Instead of pinning Sphinx, why don't we pin docutils to <0.17? Even if Sphinx supports a higher docutils version, it will likely break this theme until we update the CSS rules etc.

[acturner]

@choldgraf That was the original proposal; if you guys decide you want that I can revert the last commit.

[choldgraf]

I was going to update this one to pin at 3.5.4 as @jorisvandenbossche mentioned, but the branch seems to be deleted so I opened up #595

[damianavila]

Superseded by #595, so closing here.