STINNER Victor <vstin...@python.org> added the comment:
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. ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue40204> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
