◐ Shell
reader mode source ↗
Skip to content

bpo-43795: PEP 652 user documentation#25668

Merged
miss-islington merged 14 commits into
python:mainfrom
encukou:pep652-document
May 11, 2021
Merged

bpo-43795: PEP 652 user documentation#25668
miss-islington merged 14 commits into
python:mainfrom
encukou:pep652-document

Conversation

@encukou

@encukou encukou commented Apr 27, 2021 •
edited by miss-islington
Loading

Copy link
Copy Markdown
Member
  • Reformat the C API and ABI Versioning page (and extend/clarify a bit)
  • Rewrite the stable ABI docs into a general text on C API Compatibility
  • Add a list of Limited API contents, and notes for the individual items.
  • Replace Include/README.rst with a link to a devguide page with the same info

https://bugs.python.org/issue43795

Automerge-Triggered-By: GH:encukou

encukou added 2 commits April 27, 2021 21:16
@encukou
Doc: Reformat the C API and ABI Versioning page …
28e34ab 
Mark up all the version macros, adding them to the index and allowing
links to them.

Clarify that these are resolved at build time.

Add an example for Python 3.10. Some people might assume this is 0x10,
not 0xA, based on how well PY_VERSION_HEX "reads" in hex.

Link to the (upcoming) page on API and ABI stability.
@encukou
Add Stable ABI (PEP 652) documentation
61cf858
@encukou encukou added docs Documentation in the Doc dir skip news DO-NOT-MERGE labels Apr 27, 2021
@encukou encukou mentioned this pull request Apr 29, 2021
Merged
encukou and others added 5 commits April 29, 2021 17:06
@encukou
Mark up Py_LIMITED_API as a macro
b9dc6d2
@encukou
Replace Include/README.rst with a link to the devguide …
15cc273 
Devguide PR: python/devguide#682
@encukou
Merge in the main branch
f37ec96
@encukou
Add a list of the stable ABI to the docs
d3c3107
@encukou @WillAyd
Add "Part of the Stable ABI" annotations to the documentation …
179c132 
This replaces the existing :stableabi:, which wasn't really used.

Doc/data/stable_abi.dat is expanded to include all relevant
info (kind of the symbol and version it was added in), and the
c_annotations Sphinx extension reads this file and adds
notes similar to ones added by :stableabi: (which wasn't really
used).

Relevant prior work: python#23185
Co-authored-by: Will Ayd <william.ayd@icloud.com>
@encukou

encukou commented Apr 29, 2021

Copy link
Copy Markdown
Member Author

As per the PEP, I added a list of everything in the limited API, as well as notes in individual doc entries. A screenshot of the notes:

image

@encukou encukou marked this pull request as ready for review April 29, 2021 16:03
@encukou encukou mentioned this pull request Apr 29, 2021
Closed
@encukou

encukou commented May 6, 2021

Copy link
Copy Markdown
Member Author

The docs notes will now show platform restrictions, based on #ifdef, like the “on Windows" here:

image

orsenthil
orsenthil reviewed May 7, 2021
View reviewed changes

@orsenthil orsenthil left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Hide comment

This looks good to me. I had few nits to clarify.

willingc
willingc approved these changes May 7, 2021
View reviewed changes

@willingc willingc left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Hide comment

Thank you @encukou. Nice work improving clarity here. I've made a few suggestions for consideration. Thanks again ☀️

@encukou

encukou commented May 7, 2021

Copy link
Copy Markdown
Member Author

Thank you for the thoughtful comments!

@miss-islington miss-islington merged commit b05955d into python:main May 11, 2021
@miss-islington

miss-islington commented May 11, 2021

Copy link
Copy Markdown
Contributor

Sorry, I can't merge this PR. Reason: Base branch was modified. Review and try the merge again..

@miss-islington

miss-islington commented May 11, 2021

Copy link
Copy Markdown
Contributor

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

@bedevere-bot

bedevere-bot commented May 11, 2021

Copy link
Copy Markdown

GH-26034 is a backport of this pull request to the 3.10 branch.

@encukou encukou deleted the pep652-document branch May 11, 2021 14:04
@encukou

encukou commented May 11, 2021

Copy link
Copy Markdown
Member Author

This can be confusing; more and more often and I need a page to link to. So I merged this.
However, I'd be happy for more suggestions/improvements :)

willingc pushed a commit that referenced this pull request May 14, 2021
@miss-islington @encukou
bpo-43795: PEP 652 user documentation (GH-25668) (GH-26034) …
3739371 
- Reformat the C API and ABI Versioning page (and extend/clarify a bit)
- Rewrite the stable ABI docs into a general text on C API Compatibility
- Add a list of Limited API contents, and notes for the individual items.
- Replace `Include/README.rst` with a link to a devguide page with the same info
(cherry picked from commit b05955d)

Co-authored-by: Petr Viktorin <encukou@gmail.com>

Co-authored-by: Petr Viktorin <encukou@gmail.com>
@pablogsal pablogsal mentioned this pull request Jul 18, 2021
Closed
@encukou encukou mentioned this pull request Jun 7, 2022
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@orsenthil orsenthil orsenthil left review comments

@willingc willingc willingc 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.

6 participants

@encukou @miss-islington @bedevere-bot @orsenthil @willingc @the-knights-who-say-ni