bpo-40204: Update documentation formatting for Sphinx 3.0 by jakobandersen · Pull Request #19397 · python/cpython · GitHub

In the recently released Sphinx v3.0 the C domain has been rewritten to improve parsing of declarations and cross-referencing capabilities. However, this means that the existing directives has gotten more strict on the type of entities they accept.
This PR updates the documentation to use the new directives and roles. Many of the changes are related to C constructs in running text where a type or expression is "referenced". These have been changed to use the new markup role c:expr which accepts arbitrary types or expressions. This is in opposition to the other roles, like c:type which is for cross-referencing a type declared with a directive.

A few issues I couldn't immediately resovle:

The refcount annotation in tools/extensions/c_annoations.py no longer works (though first broken in c domain: Generate node_id for objects in the right way sphinx-doc/sphinx#7269).
c-api/module.rst:194: the old m_reload is technically declared inside the scope of m_slots. This is now reflected in its ID/permalink.
c-api/call.rst: The two functions PyObject_CallFunctionObjArgs and PyObject_CallMethodObjArgs takes a variable amount of arguments, though the last one must be NULL, indicated explicitly in the declaration. This is not valid C. There could be a configuration option in Sphinx to allow this. Please open an issue for Sphinx if you find this is relevant.
howto/instrumentation.rst: The c:function directive is used for some markers, but without a return type. The type void was added. However, python.function.return contains return which is a C keyword, so a warning is generated. The elegant solution would perhaps be to code a custom domain for these things, as they are not really C declarations (as far as I understand).
c-api/unicode.rst: The function PyUnicode_Translate is documented twice.
c-api/init.rst: There are several instances mentioning "wchar_* string". Should this be :c:expr:`wchar_t*` string?

https://bugs.python.org/issue40204

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept this contribution by verifying everyone involved has signed the PSF contributor agreement (CLA).

Recognized GitHub username

We couldn't find a bugs.python.org (b.p.o) account corresponding to the following GitHub usernames:

@jakobandersen

This might be simply due to a missing "GitHub Name" entry in one's b.p.o account settings. This is necessary for legal reasons before we can look at this contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

You can check yourself to see if the CLA has been received.

Thanks again for the contribution, we look forward to reviewing it!

:c:func: not just changes the style and adds a link, but it also adds () after the function name. Please add explicit () in all sites where you changed :c:func: to :c:expr: or `` ``.

Suggested change

      
               :c:expr:`void*` argument that was passed to the ``PyArg_Parse*`` functions.
          
               :c:expr:`void*` argument that was passed to the ``PyArg_Parse*()`` functions.

Suggested change

      
            	  :c:expr:`void*`)as its argument and should return a "new" Python object, or
          
            	  :c:expr:`void*`) as its argument and should return a "new" Python object, or

Seems the tab character is used here. Please replace all tab characters with spaces and check that lines are correctly aligned.

I think it is enough to use

Suggested change

      
               *ierr* of :c:expr:`0`, the error code returned by a call to :c:func:`GetLastError`
          
               *ierr* of ``0``, the error code returned by a call to :c:func:`GetLastError`

as for all literals.

https://build.opensuse.org/request/show/812851 by user mcepl + dimstar_suse - add requires python3-base on libpython subpackage (bsc#1167008) - build against Sphinx 2.x until python is compatible with Sphinx 3.x (see gh#python/cpython#19397, bpo#40204) - Fix build with SQLite 3.32 (bpo#40783) add bpo40784-Fix-sqlite3-deterministic-test.patch

The problem of this PR is that :c:expr: is not supported by Sphinx 2, and so this PR drops Sphinx 2 support. Since Sphinx 3 is not widely adopted yet, I proposed a different approach which keeps Sphinx 2 support, but adds Sphinx 3 support, see: https://bugs.python.org/issue40204 Sphinx 2+3 support can be added to stable branches, it's not a backward incompatible change. But my changes require Sphinx 3.2 which adds a new option to opt-in for Sphinx 2 syntax for the C domain.

This PR contains a few relevant changes which are compatible with Sphinx 2. If you want, please try to extract them and write a new PR.

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

Thanks for your contribution! But your PR couldn't be merged. If you want, please try to extract your changes which are relevant and compatible with Sphinx 2.

jakobandersen added 2 commits March 15, 2020 19:43

Initial fixes for Sphinx 3

6c604b9

More doc fixes for Sphinx 3

965ca55

jakobandersen requested a review from tiran as a code owner April 6, 2020 17:41

the-knights-who-say-ni added the CLA not signed label Apr 6, 2020

bedevere-bot added docs Documentation in the Doc dir awaiting review labels Apr 6, 2020

jakobandersen mentioned this pull request Apr 6, 2020

TypeError in sphinx logging building CPython docs with Sphinx 3.0 sphinx-doc/sphinx#7423

Closed

serhiy-storchaka reviewed Apr 6, 2020

View reviewed changes

Comment thread Doc/c-api/arg.rst

m-aciek mentioned this pull request Apr 8, 2020

Make build-translation job work again python/python-docs-pl#8

Closed

serhiy-storchaka reviewed Apr 24, 2020

View reviewed changes

csabella removed the CLA not signed label May 22, 2020

the-knights-who-say-ni added the CLA signed label May 22, 2020

vstinner requested changes Aug 17, 2020

View reviewed changes

bedevere-bot added awaiting changes and removed awaiting review labels Aug 17, 2020

vstinner closed this Aug 17, 2020

-                    \*`) as its argument and should return a "new" Python object, or ``NULL`` if an
-                    error occurred.
+              	  function is called with *anything* (which should be compatible with
+              	  :c:expr:`void*`)as its argument and should return a "new" Python object, or

-                    error occurred.
+              	  function is called with *anything* (which should be compatible with
+              	  :c:expr:`void*`)as its argument and should return a "new" Python object, or
+              	  ``NULL`` if an error occurred.

bpo-40204: Update documentation formatting for Sphinx 3.0 by jakobandersen · Pull Request #19397 · python/cpython · GitHub

Uh oh!

Uh oh!

bpo-40204: Update documentation formatting for Sphinx 3.0 - #19397

bpo-40204: Update documentation formatting for Sphinx 3.0#19397
jakobandersen wants to merge 2 commits into
python:masterfrom
jakobandersen:doc_fixes

jakobandersen commented Apr 6, 2020 •
edited by bedevere-bot
Loading

Uh oh!

Uh oh!

the-knights-who-say-ni commented Apr 6, 2020

Uh oh!

Uh oh!

Uh oh!

serhiy-storchaka Apr 24, 2020

Uh oh!

serhiy-storchaka Apr 24, 2020

Uh oh!

serhiy-storchaka Apr 24, 2020

Uh oh!

serhiy-storchaka Apr 24, 2020

Uh oh!

vstinner left a comment

Uh oh!

bedevere-bot commented Aug 17, 2020

Uh oh!

vstinner commented Aug 17, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

                  where *object* is the Python object to be converted and *address* is the
-                 :c:type:`void\*` argument that was passed to the :c:func:`PyArg_Parse\*` function.
+                 :c:expr:`void*` argument that was passed to the ``PyArg_Parse*`` functions.

	:c:expr:`void` argument that was passed to the ``PyArg_Parse`` functions.
	:c:expr:`void` argument that was passed to the ``PyArg_Parse()`` functions.

	:c:expr:`void*`)as its argument and should return a "new" Python object, or
	:c:expr:`void*`) as its argument and should return a "new" Python object, or

                  This is a convenience function to raise :exc:`WindowsError`. If called with
-                 *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError`
+                 *ierr* of :c:expr:`0`, the error code returned by a call to :c:func:`GetLastError`

	ierr of :c:expr:`0`, the error code returned by a call to :c:func:`GetLastError`
	ierr of ``0``, the error code returned by a call to :c:func:`GetLastError`

bpo-40204: Update documentation formatting for Sphinx 3.0 by jakobandersen · Pull Request #19397 · python/cpython · GitHub

Uh oh!

Uh oh!

bpo-40204: Update documentation formatting for Sphinx 3.0 - #19397

bpo-40204: Update documentation formatting for Sphinx 3.0#19397jakobandersen wants to merge 2 commits intopython:masterpython/cpython:masterfrom jakobandersen:doc_fixesjakobandersen/cpython:doc_fixesCopy head branch name to clipboard

Conversation

jakobandersen commented Apr 6, 2020 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

the-knights-who-say-ni commented Apr 6, 2020

Recognized GitHub username

Uh oh!

Uh oh!

Uh oh!

serhiy-storchaka Apr 24, 2020

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Apr 24, 2020

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Apr 24, 2020

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Apr 24, 2020

Choose a reason for hiding this comment

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

bedevere-bot commented Aug 17, 2020

Uh oh!

vstinner commented Aug 17, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

bpo-40204: Update documentation formatting for Sphinx 3.0#19397
jakobandersen wants to merge 2 commits into
python:masterfrom
jakobandersen:doc_fixes

jakobandersen commented Apr 6, 2020 •
edited by bedevere-bot
Loading