GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-107298: Fix C API Buffer documentation by vstinner · Pull Request #108011 · python/cpython

Conversation

@vstinner

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

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member
  • Issue: Fix Sphinx warnings in the C API documentation #107298

📚 Documentation preview 📚: https://cpython-previews--108011.org.readthedocs.build/

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@vstinner
pythongh-107298: Fix C API Buffer documentation
d00b3d8
@bedevere-bot bedevere-bot added the awaiting core review label Aug 16, 2023
@bedevere-bot bedevere-bot mentioned this pull request Aug 16, 2023
Fix Sphinx warnings in the C API documentation #107298
Closed
@bedevere-bot bedevere-bot added docs Documentation in the Doc dir skip news labels Aug 16, 2023
@vstinner

vstinner commented Aug 16, 2023

Copy link
Copy Markdown
Member Author

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
serhiy-storchaka
serhiy-storchaka reviewed Aug 16, 2023
View reviewed changes
Comment thread Doc/c-api/buffer.rst
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

@serhiy-storchaka serhiy-storchaka Aug 16, 2023

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/buffer.rst
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

@serhiy-storchaka serhiy-storchaka Aug 16, 2023

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
AA-Turner reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

@vstinner vstinner Aug 16, 2023

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
vstinner added 2 commits August 16, 2023 16:58
@vstinner
Fix typo; update PyExc_BufferError
5217fa5
@vstinner
Update Doc/tools/.nitignore
a7de64f
serhiy-storchaka
serhiy-storchaka approved these changes Aug 16, 2023
View reviewed changes
@bedevere-bot bedevere-bot added awaiting merge and removed awaiting core review labels Aug 16, 2023
@vstinner
vstinner merged commit c2941cb into python:main Aug 16, 2023
@bedevere-bot bedevere-bot removed the awaiting merge label Aug 16, 2023
@vstinner
vstinner deleted the fix_buffer_capi_doc branch August 16, 2023 16:24
@vstinner

vstinner commented Aug 16, 2023

Copy link
Copy Markdown
Member Author

Thanks for the review @serhiy-storchaka.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@serhiy-storchaka serhiy-storchaka added needs backport to 3.11 only security fixes needs backport to 3.12 only security fixes labels Aug 16, 2023
@miss-islington

miss-islington commented Aug 16, 2023

Copy link
Copy Markdown
Contributor

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@miss-islington

miss-islington commented Aug 16, 2023

Copy link
Copy Markdown
Contributor

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@miss-islington

miss-islington commented Aug 16, 2023

Copy link
Copy Markdown
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
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@miss-islington miss-islington assigned vstinner Aug 16, 2023
@bedevere-bot

bedevere-bot commented Aug 16, 2023

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@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 only security fixes and removed needs backport to 3.12 only security fixes labels Aug 16, 2023
@miss-islington

miss-islington commented Aug 16, 2023

Copy link
Copy Markdown
Contributor

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@miss-islington

miss-islington commented Aug 16, 2023

Copy link
Copy Markdown
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
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@serhiy-storchaka

serhiy-storchaka commented Aug 16, 2023

Copy link
Copy Markdown
Member

Conflict in 3.12 but not in 3.11?
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
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

bedevere-bot commented Aug 16, 2023

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-bot bedevere-bot removed the needs backport to 3.12 only security fixes label Aug 16, 2023
@serhiy-storchaka serhiy-storchaka unassigned vstinner 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

Uh oh!

There was an error while loading. Please reload this page.

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.

Uh oh!

There was an error while loading. Please reload this page.

4 participants

@vstinner @miss-islington @bedevere-bot @serhiy-storchaka
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.