Skip to content
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.

Sign up for GitHub

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

Jump to bottom

gh-107298: Fix C API Buffer documentation #108011

Merged
merged 3 commits into from
Aug 16, 2023
Merged

gh-107298: Fix C API Buffer documentation #108011

merged 3 commits into from
Aug 16, 2023

Conversation

vstinner
Copy link
Member

@vstinner vstinner commented Aug 16, 2023 •
edited by github-actions bot
Loading

@bedevere-bot bedevere-bot mentioned this pull request Aug 16, 2023
Closed
@bedevere-bot bedevere-bot added docs Documentation in the Doc dir skip news labels Aug 16, 2023
@vstinner
Copy link
Member Author

Fix some of the Sphinx warnings reported in https://github.com/python/cpython/pull/108010/files PR (PR unrelated to documentation).

serhiy-storchaka
serhiy-storchaka reviewed Aug 16, 2023
View reviewed changes
Doc/c-api/buffer.rst
@@ -444,7 +448,7 @@ Buffer-related functions

Send a request to *exporter* to fill in *view* as specified by *flags*.
If the exporter cannot provide a buffer of the exact type, it MUST raise
:c:data:`PyExc_BufferError`, set ``view->obj`` to ``NULL`` and
:exc:`BufferError`, set ``view->obj`` to ``NULL`` and
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is yet one reference in typeobj.rst.

Doc/c-api/buffer.rst
@@ -163,13 +163,6 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
and :c:member:`~Py_buffer.suboffsets` MUST be ``NULL``.
The maximum number of dimensions is given by :c:macro:`PyBUF_MAX_NDIM`.

.. :c:macro:: PyBUF_MAX_NDIM
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can just add

   .. c:namespace:: NULL

here, and restore the namespace after the description to fix reference issues.

I already used it for some macros declared not at the top level.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#namespacing

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I saw your "namespace: NULL" trick of your other PRs, but here Py_buffer members are defined before and after this macro which is not part of Py_buffer structure. In terms of Sphinx, it's confusing. I prefer to document it somewhere else.

@vstinner vstinner merged commit c2941cb into python:main Aug 16, 2023
@vstinner vstinner deleted the fix_buffer_capi_doc branch August 16, 2023 16:24
@vstinner
Copy link
Member Author

Thanks for the review @serhiy-storchaka.

@serhiy-storchaka serhiy-storchaka added needs backport to 3.11 only security fixes needs backport to 3.12 bug and security fixes labels Aug 16, 2023
@miss-islington
Copy link
Contributor

Thanks @vstinner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

@miss-islington
Copy link
Contributor

Thanks @vstinner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

@miss-islington
Copy link
Contributor

Sorry, @vstinner, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker c2941cba7a986e6158eebb2a0bf33906dcd78616 3.12

@bedevere-bot
Copy link

GH-108041 is a backport of this pull request to the 3.11 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.11 only security fixes label Aug 16, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 16, 2023
@vstinner @miss-islington
pythongh-107298: Fix C API Buffer documentation (pythonGH-108011)
109aa80 
(cherry picked from commit c2941cb)

Co-authored-by: Victor Stinner <[email protected]>
@serhiy-storchaka serhiy-storchaka added needs backport to 3.12 bug and security fixes and removed needs backport to 3.12 bug and security fixes labels Aug 16, 2023
@miss-islington
Copy link
Contributor

Thanks @vstinner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

@miss-islington
Copy link
Contributor

Sorry @vstinner, I had trouble checking out the 3.12 backport branch.
Please retry by removing and re-adding the "needs backport to 3.12" label.
Alternatively, you can backport using cherry_picker on the command line.
cherry_picker c2941cba7a986e6158eebb2a0bf33906dcd78616 3.12

@serhiy-storchaka
Copy link
Member

Conflict in 3.12 but not in 3.11?

serhiy-storchaka pushed a commit to serhiy-storchaka/cpython that referenced this pull request Aug 16, 2023
@vstinner @serhiy-storchaka
[3.12] pythongh-107298: Fix C API Buffer documentation (pythonGH-108011…
bff84df 
…).

(cherry picked from commit c2941cb)

Co-authored-by: Victor Stinner <[email protected]>
@bedevere-bot
Copy link

GH-108048 is a backport of this pull request to the 3.12 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.12 bug and security fixes label Aug 16, 2023
vstinner added a commit that referenced this pull request Aug 16, 2023
@miss-islington @vstinner
[3.11] gh-107298: Fix C API Buffer documentation (GH-108011) (#108041)
4e5dac1 
gh-107298: Fix C API Buffer documentation (GH-108011)
(cherry picked from commit c2941cb)

Co-authored-by: Victor Stinner <[email protected]>
Yhg1s pushed a commit that referenced this pull request Aug 16, 2023
@serhiy-storchaka @vstinner
[3.12] gh-107298: Fix C API Buffer documentation (GH-108011). (#108048)
277bf80 
(cherry picked from commit c2941cb)

Co-authored-by: Victor Stinner <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@serhiy-storchaka serhiy-storchaka serhiy-storchaka approved these changes

Assignees
No one assigned
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@vstinner @miss-islington @bedevere-bot @serhiy-storchaka