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-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/E64YE3DQGOHLFQOJAJHS7VW3PK5KLB4W/
Code of Conduct: http://python.org/psf/codeofconduct/
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-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/E64YE3DQGOHLFQOJAJHS7VW3PK5KLB4W/
Code of Conduct: http://python.org/psf/codeofconduct/