Since documentation changes are backported to 3.8 and 3.9 stable branches, if we increase the minimum required Sphinx version in master, I would prefer to also increase it in 3.8 and 3.9 branches.
I would prefer to not have to check manually if a doc backport PR is still compatible with Sphinx 2 or not. If we skip some doc backports, conflicts will become more likely with following doc backports. -- I looked at Sphinx and Python versions of Debian, Ubuntu and Fedora: https://bugs.python.org/issue42843#msg384963 In my list, there is only Debian Buster (stable) which doesn't have Sphinx 3 yet. It uses Python 3.7 and so would not be affected by Python 3.8 changes. -- The alternative is to keep Sphinx 2 support, use strip_signature_backslash and don't use :no-trim-doctest-flags: ? Victor On Tue, Jan 12, 2021 at 9:44 PM Julien Palard via Python-Dev <python-dev@python.org> wrote: > > 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). > > I found two incompatibilities: > > - We're using :no-trim-doctest-flags:, introduced in Sphinx 3.2.0, if we > build with Sphinx < 3.2.0 the blocks using it are dropped by Sphinx (we > use it in library/doctest). > > - double backslashes in domain directives are no longer replaced by > single backslashes. But a configuration value > (strip_signature_backslash) can be used to have the same behavior on > Sphinx 2 and 3. > > So yes, it's still possible to build the docs with Sphinx 1.8 using > `make html SPHINXERRORHANDLING=`, it "works" but: > > - Doctests code blocks using no-trim-doctest-flags dissapear. > - Some functions declarations are lacking a backslash, like > print(*objects, sep=' ', end='n', ... > > Which is bad. > > For the first one we could still workaround with an ugly `sed -i > /no-trim-doctest-flags/d`, or simply stop using it (and reopen bpo-36675). > For the 2nd one we could use `strip_signature_backslash` in cpython 3.10 > to have the same behavior. > > So the question is: Should we bump minimum version of Sphinx from 1.8 to > 3.2.1 along with Python 3.10? For the moment this is where we go, but if > you're having to maintain a release of Python along with Sphinx < 3, > please make speak. > > Conversation has already started here [1] and here [2]. > > [1]: https://bugs.python.org/issue42843 > [2]: https://github.com/python/cpython/pull/24142 > > -- > [Julien Palard](https://mdk.fr) > _______________________________________________ > Python-Dev mailing list -- python-dev@python.org > To unsubscribe send an email to python-dev-le...@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/E64YE3DQGOHLFQOJAJHS7VW3PK5KLB4W/ > Code of Conduct: http://python.org/psf/codeofconduct/ -- Night gathers, and now my watch begins. It shall not end until my death. _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@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/VABPDAAMCNMHLSG4N2FXK6S7NHYTPBRM/ Code of Conduct: http://python.org/psf/codeofconduct/
