Description

AA-Turner

opened on Jun 11, 2022

Issue body actions

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:

1. Is this change welcome?
2. How should I proceed with PRs? One per data type, per file, etc?
3. I would want to backport these changes to 3.10/3.11 (to allow future docs backports without conflicts), does anybody have objections?
4. Does anybody have other concerns?

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

• gh-93738: Documentation C syntax (:c:data:0 -> 0) #97771
• gh-93738: Documentation C syntax (:c:type:Py_UNICODE* -> :c:expr:Py_UNICODE*) #97784
• gh-93738: Documentation C syntax (:c:type:PyUnicodeObject* -> :c:expr:PyUnicodeObject*) #97783
• gh-93738: Documentation C syntax (:c:type:PyBytesObject* -> :c:expr:PyBytesObject*) #97782
• gh-93738: Documentation C syntax (:c:type:PyTupleObject* -> :c:expr:PyTupleObject*) #97780
• gh-93738: Documentation C syntax (:c:data:view->obj -> :c:expr:view->obj) #97773
• gh-93738: Documentation C syntax (:c:type:FILE -> :c:expr:FILE) #97769
• gh-93738: Documentation C syntax (:c:type:TYPE -> :c:expr:TYPE) #97770
• gh-93738: Documentation C syntax (:c:type:PyInterpreterState * -> :c:expr:PyInterpreterState *) #97777
• gh-93738: Documentation C syntax (:c:type:PyObject -> :c:expr:PyObject) #97776
• gh-93738: Documentation C syntax (:c:type: to :c:expr:, misc. cases) #97775
• gh-93738: Documentation C syntax (:c:type:PyTypeObject* -> :c:expr:PyTypeObject*) #97778
• gh-93738: Documentation C syntax (Use c:struct) #97772
• gh-93738: Documentation C syntax (Function glob patterns -> literal markup) #97774
• gh-93738: Documentation C syntax (:c:type:<C type> -> :c:expr:<C type>) #97768
• gh-93738: Disallow pre-v3 syntax in the C domain #97962

Reacted by Hugo van Kemenade, Ezio Melotti, Petr Viktorin and Senthil Kumaran

Activity

1. AA-Turner

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   3.11only security fixesonly security fixes

   3.10 (EOL)end of lifeend of life

   topic-C-API

   3.12only security fixesonly security fixes

   on Jun 11, 2022
2. AA-Turner

   self-assigned this

   on Jun 11, 2022
3. serhiy-storchaka commented on Jun 12, 2022

   

   serhiy-storchaka

   on Jun 12, 2022

   Member

   More actions

   What directives and roles can be used and what are gone?

   1. Is this change welcome?

   We do not have a choice, isn't?

   2. 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?

   3. 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 O
4. AA-Turner commented on Jun 12, 2022

   

   AA-Turner

   on Jun 12, 2022

   MemberAuthor

   More actions

   What 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
5. hugovk commented on Jun 12, 2022

   

   hugovk

   on Jun 12, 2022

   Member

   More actions

   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 Turner
6. vstinner commented on Jun 13, 2022

   

   vstinner

   on Jun 13, 2022

   Member

   More actions

   If 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 = False
   

   I 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 Turner
7. encukou commented on Jun 13, 2022

   

   encukou

   on Jun 13, 2022

   Member

   More actions

   I'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:const PyObject* will link to PyObject. If that's right, IMO the :c:type:PyObject* should be changed to expr, 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:PyArg_Parse\* functions link to the section (especially for PyArg_Parse where not all of them actually use the prefix); other cases could use wording like PyArg_Parse* functions (such as :c:func:PyArg_VaParse)

   Reacted by Adam Turner
8. AA-Turner commented on Jun 13, 2022

   

   AA-Turner

   on Jun 13, 2022

   MemberAuthor

   More actions

   Created at https://discuss.python.org/t/16500

   A
9. encukou commented on Sep 21, 2022

   

   encukou

   on Sep 21, 2022

   Member

   More actions

   @AA-Turner, do you still want to do this, or would it be better if someone else took over?
10. AA-Turner commented on Oct 3, 2022

    

    AA-Turner

    on Oct 3, 2022

    MemberAuthor

    More actions

    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
11. ezio-melotti

    added this to Sprinton Oct 4, 2022
12. 113 remaining items
13. pablogsal

    added 15 commits that reference this issue on Oct 22, 2022

    [3.11] gh-93738: Documentation C syntax (:c:type:<C type> -> :c:expr:…

    e48d6df

    [3.11] gh-93738: Documentation C syntax (Function glob patterns -> li…

    6ff98f7

    [3.11] gh-93738: Documentation C syntax (:c:type:`PyTypeObject*` -> :…

    2af31cf

    [3.11] gh-93738: Documentation C syntax (Use `c:struct`) (GH-97772) (#…

    33e4537

    [3.11] gh-93738: Documentation C syntax (:c:type: to :c:expr:, misc. …

    e2f7642

    [3.11] gh-93738: Documentation C syntax (:c:type:`PyObject` -> :c:exp…

    800c9c0

    [3.11] gh-93738: Documentation C syntax (:c:data:`view->obj` -> :c:ex…

    5137002

    [3.11] gh-93738: Documentation C syntax (:c:type:`PyInterpreterState …

    aa7893b

    [3.11] gh-93738: Documentation C syntax (:c:type:`TYPE` -> :c:expr:`T…

    56aaff4

    [3.11] gh-93738: Documentation C syntax (:c:type:`FILE` -> :c:expr:`F…

    9b73bd4

    [3.11] gh-93738: Documentation C syntax (:c:type:`PyTupleObject*` -> …

    ab665d9

    [3.11] gh-93738: Documentation C syntax (:c:type:`PyBytesObject*` -> …

    0679066

    [3.11] gh-93738: Documentation C syntax (:c:type:`PyUnicodeObject*` -…

    264b615

    [3.11] gh-93738: Documentation C syntax (:c:type:`Py_UNICODE*` -> :c:…

    232a402

    gh-93738: Documentation C syntax (:c:data:`0` -> ``0``) (GH-97771)

    d21bef5

Issue actions