-
-
Notifications
You must be signed in to change notification settings - Fork 30.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update C domain docs to Sphinx 3 syntax #93738
Comments
What directives and roles can be used and what are gone?
We do not have a choice, isn't?
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?
Do not have objections if systems with 3.10 support Sphinx 3. |
Gone in 3.0-3.2:Relaxed parsing. In Sphinx 2, a definition like New in 3.0-3.2, taken from Sphinx's C domain docs:Directives:
Cross-referencing roles:
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):
Support for documentation-namespaces (https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#namespacing) A |
cc also @JulienPalard |
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:
I agree to backport for the reason that you give: make future backports simpler. |
I've looked at the proposed branch. The commits there would make good individual PRs, IMO. 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 References to a family of functions (glob patterns) like |
Created 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? |
…c:expr:`PyBytesObject*`) (python#97782) :c:type:`PyBytesObject*` -> :c:expr:`PyBytesObject*`
…c:expr:`PyTupleObject*`) (python#97780) :c:type:`PyTupleObject*` -> :c:expr:`PyTupleObject*`
…` -> :c:expr:`PyInterpreterState *`) (python#97777) :c:type:`PyInterpreterState *` -> :c:expr:`PyInterpreterState *`
…:`PyObject`) (python#97776) :c:type:`PyObject` -> :c:expr:`PyObject`
…r:`view->obj`) (python#97773) :c:data:`view->obj` -> :c:expr:`view->obj`
…PE`) (python#97770) :c:type:`TYPE` -> :c:expr:`TYPE`
…LE`) (python#97769) :c:type:`FILE` -> :c:expr:`FILE`
…ases) (python#97775) * :c:type: to :c:expr: * Update Doc/whatsnew/2.4.rst
…:expr:`PyTypeObject*`) (python#97778) Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
…C type>) (python#97768) :c:type:`<C type>` -> :c:expr:`<C type>` Co-authored-by: Łukasz Langa <lukasz@langa.pl>
Also, disable using invalid sphinx-lint 0.6.2.
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
) #97772The text was updated successfully, but these errors were encountered: