Re: Supported Sphinx Versions (was: Re: [PATCH for-5.0? 0/3] Make docs build work with Sphinx 3)

[John Snow]

On 4/13/20 2:22 PM, Peter Maydell wrote:
> On Mon, 13 Apr 2020 at 19:08, John Snow <address@hidden> wrote:
>> I was curious about our actual version compatibility, so I did some testing.
> 
> Thanks for doing the testing.
> 
>> 1.6.1 through 2.2.2 all appear to work just fine, but produce a lot of
>> warnings about a coming incompatibility with Docutils > 0.16.
> 
> FWIW, I don't get this warning with the stock Ubuntu
> 1.6.7. The only time I did see it was when I'd managed
> to accidentally install half of Sphinx 3 to my ~/.local
> directory and I think it was the system Sphinx and an
> upgraded docutils or some other weird combo.
> 

Yeah, it depends on what versions you pull in. I am using `pip` to
install sphinx straight from PyPI, and the version dependency resolution
opts for "the latest that isn't prohibited by the repository", which
means that I am using (very likely) some cutting edge dependencies for
an older version of sphinx.

That's OK, it works just fine -- just a note, is all. It likely works
completely quietly if you scoot back down to Docutils 0.15.

(The requirements specify only Docutils >= 0.12. Eventually, older
sphinx installations may break when Docutils 0.17 comes out unless you
start pinning versions manually.)

>> Conclusion:
>>
>> Required: >= 1.6.1
>> Recommended: >= 2.3.0
> 
> I think that what we actually care about is the usual thing:
> do we build OK with the version of sphinx-build shipped by
> every distro on our support list?

Sure; if any distro ships a version that's outside of what I laid out
above it would be good to fix and check.

We can also tighten and document the versions so if we do fall outside
of that by accident, we'll catch it during RC testing phase.

I'm using this to make a quick assessment:
https://repology.org/project/python:sphinx/versions

Fedora:
    30: 1.8.4
    31: 2.1.2

OpenSUSE:
    15.1: 1.7.6

Ubuntu:
    19.10: 1.8.5
    20.04/LTS: 1.8.5

Debian:
    8/Jessie: We don't support this anymore AFAIUI.
    9/Stretch: 1.4.8 -- Broken at present!
    10/Buster: 1.8.3

Ubuntu LTS:
    16.04: Dropped
    18.04: 1.6.7
    20.04: 1.8.5

RHEL:
    EPEL7: 1.2.3 -- way, way too old!
    RHEL8: 1.7.6 [via CentOS8]



We *might* need to do some surgery to support Stretch, and EPEL7 fell
off the wagon entirely if repology is to believe -- it doesn't support
our stated minimum of simply having the "Alabaster" theme, which comes
in 1.3.

For RHEL7 we *could* start using a virtual environment, which would help
alleviate the wide version spread.

...are we opposed to this kind of thing? Has there been a discussion before?

Targeting the native repo versions is nice (and we should continue to
make a best effort there), but we *could* start offering a virtual
python environment for the builds that grabs very precise versions.

--js