Repository navigation
Update C domain docs to Sphinx 3 syntax #93738
Description
Activity
What directives and roles can be used and what are gone?
- Is this change welcome?
We do not have a choice, isn't?
- How should I proceed with PRs? One per data type, per file, etc?
Could manual and automatic changes be separated, so intermediate results are still working? Say, first some preparing manual changes, then automatic changes, then final manual changes?
- I would want to backport these changes to 3.10/3.11 (to allow future docs backports without conflicts), does anybody have objections?
Do not have objections if systems with 3.10 support Sphinx 3.
Reacted by Jelle Zijlstra, Adam Turner, Hugo van Kemenade and Laurie OWhat directives and roles can be used and what are gone?
Gone in 3.0-3.2:
Relaxed parsing. In Sphinx 2, a definition like
:c:type:`const char*`was OK, but in Sphinx 3 this fails -- it should be a:c:expr:.:c:type:`PyObject*`is currently rendered in the docs with a link only to the "PyObject" part of the role text -- it should change to either having the*outside of the role (:c:type:`PyObject`\*) or being an expression (:c:expr:`PyObject*`). Places where there are references to groups of functions using the type role are invalid (and currently don't work), these should be replaced with literal syntax (e.g.:c:func:`PyErr_Set\*`).New in 3.0-3.2, taken from Sphinx's C domain docs:
Directives:
.. c:macro:: name(arg list)(Function style macro variant).. c:struct:: name.. c:union:: name.. c:enum:: name.. c:enumerator:: name
Cross-referencing roles:
:c:var:(alias of both:c:member:and:c:data:):c:struct::c:union::c:enum::c:enumerator:
Documentation support for anonymous entities (https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#anonymous-entities)
Support for re-printing declarations in a list, e.g. for overviews of interfaces (https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#aliasing-declarations)
Support for inline expresssions (https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#inline-expressions-and-types):
:c:expr::c:texpr:("text-expression")
Support for documentation-namespaces (https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#namespacing)
A
cc: @vstinner @serhiy-storchaka @encukou @erlend-aasland @JelleZijlstra @hugovk (Selection of C-API/documentation people, if I've missed anyone please mention them).
cc also @JulienPalard
Reacted by Adam TurnerIf I recall correctly, in 2020, I asked Sphinx to add an option to opt-in for the legacy C syntax. When it was discussed, the problem was that Sphinx supporting the new syntax was not widely available in Linux distributions. I guess that the situation changed and now it's perfectly fine to switch to the new syntax.
Doc/conf.py gives some context and links to bpo-40204:
# bpo-40204: Allow Sphinx 2 syntax in the C domain c_allow_pre_v3 = True # bpo-40204: Disable warnings on Sphinx 2 syntax of the C domain since the # documentation is built with -W (warnings treated as errors). c_warn_on_allowed_pre_v3 = FalseI would want to backport these changes to 3.10/3.11 (to allow future docs backports without conflicts)
I agree to backport for the reason that you give: make future backports simpler.
Reacted by Adam TurnerI've looked at the proposed branch. The commits there would make good individual PRs, IMO.
IMO we've now made it clear that documentation discussions live in the Discuss category. Perhaps mention there, and if no one objects, go ahead with PRs.Some specific points:
Please keep/turn as many of these as possible as/into links. Many times this would just mean checking that the links are generated (and are correct).
AFAIK, Sphinx will parse
:c:expr:expressions and linkify any types it finds, so:c:expr:will link toconst PyObject*PyObject. If that's right, IMO the :c:type:PyObject*should be changed toexpr, which is much easier to type than the ecaped star.
Or is there some disadvantage to:c:expr:?References to a family of functions (glob patterns) like
:c:func:link to the section (especially forPyArg_Parse\*functionsPyArg_Parsewhere not all of them actually use the prefix); other cases could use wording likePyArg_Parse*functions (such as :c:func:PyArg_VaParse)Reacted by Adam TurnerCreated at https://discuss.python.org/t/16500
A
@AA-Turner, do you still want to do this, or would it be better if someone else took over?
Thanks for the nudge Petr, 15 PRs later I've now covered all bases (I hope!) for the removal of the pre-v3 support. Some PRs are very trivial and can likely be merged instantly, some may need a few minutes to read through, but all are mechanical transformations.
A
113 remaining items
- added 15 commits that reference this issue
on Oct 22, 2022
Metadata
Metadata
Assignees
Projects
- Status
Sphinx would like to remove support for the pre-v3 C domain syntax. We have confirmed that the Linux kernel is no longer using it, so Python is the only project we are blocked on.
I have a branch where I've done the work, but it is a large number of files affected (~50) and the majority of the C-API documentation. The changes are almost all mechanical search-and-replace, but there are a few where I've had to use judgement.
Questions:
cc: @vstinner @serhiy-storchaka @encukou @erlend-aasland @JelleZijlstra @hugovk (Selection of C-API/documentation people, if I've missed anyone please mention them).
A
Tasks
0->0) #97771Py_UNICODE*-> :c:expr:Py_UNICODE*) #97784PyUnicodeObject*-> :c:expr:PyUnicodeObject*) #97783PyBytesObject*-> :c:expr:PyBytesObject*) #97782PyTupleObject*-> :c:expr:PyTupleObject*) #97780view->obj-> :c:expr:view->obj) #97773FILE-> :c:expr:FILE) #97769TYPE-> :c:expr:TYPE) #97770PyInterpreterState *-> :c:expr:PyInterpreterState *) #97777PyObject-> :c:expr:PyObject) #97776PyTypeObject*-> :c:expr:PyTypeObject*) #97778c:struct) #97772