Author vstinner
Recipients Maciej Olko, benjamin.peterson, docs@python, eric.araujo, ezio.melotti, georg.brandl, mdk, miss-islington, ned.deily, python-dev, rhettinger, serhiy.storchaka, skrah, terry.reedy, vstinner, willingc, xtreak
Date 2020-06-30.16:00:51
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1593532852.26.0.283168802633.issue40204@roundup.psfhosted.org>
In-reply-to
Content
Making the Python documentation compatible with Sphinx 3.0 is causing multiple blocker issues.


(*) The first major problem is that new C domain markup like :c:struct: and :expr: are not recognized by Sphinx 2.4.4, but Sphinx 3.0 requires them. For example, a ".. c:struct:" section is completely hidden: treated as a comment.

I don't think that we can afford to drop Sphinx < 3 support since no Linux distribution uses Sphinx 3 yet. I see two options:

* Stay at Sphinx forever
* Backport the ":c:struct:" and ":c:expr:" markups somehow in Sphinx 2 using our CPython Sphinx extensions
* Update Sphinx 3 to tolerate our "incorrect" documentation using :c:type: and :c:type:`PyObject\*` (invalid C syntax), maybe as an opt-in option
* Update Sphinx 2 to support Sphinx 3 new syntax: something like Python 2.7 which backported a few Python 3 features like b"bytes string" syntax


(*) The second major question is: should we backport these changes to Python 3.8 and 3.9 branches? I consider that "supporting Sphinx 3" is a fix in the Python build system, and usually we do backport such changes, even if they can be seen as "new features". For me, it falls into the same category than supporting a newer version of C compiler.

PR 19397 makes tons of small changes. If we don't backport it, it will be very likely very painful to backport documentation changes. Julien Palard (who works on the documentation) suggests to backport the change. Usually, documentation changes are applied to all branches, not only master.

Again, right now, if we backport these changes, we would drop Sphinx 2 support.
History
Date User Action Args
2020-06-30 16:00:52vstinnersetrecipients: + vstinner, georg.brandl, rhettinger, terry.reedy, benjamin.peterson, ned.deily, ezio.melotti, eric.araujo, skrah, docs@python, python-dev, serhiy.storchaka, willingc, mdk, miss-islington, xtreak, Maciej Olko
2020-06-30 16:00:52vstinnersetmessageid: <1593532852.26.0.283168802633.issue40204@roundup.psfhosted.org>
2020-06-30 16:00:52vstinnerlinkissue40204 messages
2020-06-30 16:00:51vstinnercreate