My take on this is to keep it simple for CPython: Require the newer version of Sphinx on all branches we backport docs changes to.

We, the CPython project, determine the exact version(s) of Sphinx a documentation build for a given version of CPython requires.  If Sphinx has unfortunately made a breaking change (as appears to be the case?), we should update our docs for all versions we backport doc changes to to use the most modern version (along with the docs themselves).

We should explicitly not care at all about people using external sphinx installs that are not fetched at the correct version via our Doc tree's Doc/requirements.txt.

That some distros want to use their own incompatible-version packaged version of sphinx to build our docs is on them to handle on their own.  Not on the CPython project.  That was never a guaranteed thing that would work.  Until now, they merely got lucky.  This is a docs build-time dependency with no impact on anything at runtime so we should be free to change versions as we see fit.

-gps


On Wed, Jan 13, 2021 at 8:25 AM Carol Willing <willingc@gmail.com> wrote:
Hi Julien,

I think that there are two items to consider:
- `needs_sphinx` in `conf.py`
- setting for Sphinx in `cpython/Doc/requirements.txt`

I believe that the `needs_sphinx` field identifies the minimal version of Sphinx that can be used to build the docs. The actual version that is used to build the docs is in the `requirements.txt` file.


On Wed, Jan 13, 2021 at 7:29 AM Serhiy Storchaka <storchaka@gmail.com> wrote:
12.01.21 22:38, Julien Palard via Python-Dev пише:
> During the development of cpython 3.10, Sphinx was bumped to 3.2.1.
>
> Problem is Sphinx 3 have some incompatibilities with Sphinx 2, some that
> we could work around, some are bit harder, so we may need to bump
> `needs_sphinx = '3.2'` (currently it is 1.8).

Sphinx version in the current Ubuntu LTS (20.04) is 1.8.5. Would not it
cause problems with builting documentation on Ubuntu?
_______________________________________________
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-leave@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/EJWTFPHZUX522RNCTIGAAOHWD23VD7NQ/
Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-leave@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/S53K4P272EE73EF2NLZWS5DVNR6VJG3R/
Code of Conduct: http://python.org/psf/codeofconduct/