gh-156870: Add common Stable ABI notes for tables of definitions - #156871
gh-156870: Add common Stable ABI notes for tables of definitions#156871encukou wants to merge 9 commits into
Conversation
Documentation build overview
14 files changed ·
|
picnixz
changed the title
picnixz
changed the title
StanFromIreland
left a comment
StanFromIreland
left a comment
There was a problem hiding this comment.
This seems to be broken, we've lost all notes looking at the preview:
| # in a 'c_annotations' attribute. | ||
| ancestor = node | ||
| while ancestor: | ||
| if 'omit-stable-abi-note' not in ancestor.get( |
There was a problem hiding this comment.
Skip the note if any ancestor has 'omit-stable-abi-note'
Is this not inverted, it's skipped if it's absent?
| [], | ||
| ): | ||
| break | ||
| ancestor = node.parent |
There was a problem hiding this comment.
Shouldn't it be ancestor.parent?
| # no skip; add the annotation | ||
| annotation = _stable_abi_annotation(record) | ||
| node.insert(0, annotation) | ||
| node.setdefault("classes", []).append('ADDED-HERE') |
There was a problem hiding this comment.
Leftover from debugging I presume?
|
Yes, thanks to the catch. That was not the code I meant to send. |
|
|
||
| These pointers are part of the :ref:`Stable ABI <stable>` since the | ||
| version in the *S.ABI* column (or since 3.2 when *S.ABI* is empty). | ||
| Exceptions marked N/A are *not* part of Stable ABI. |
There was a problem hiding this comment.
| Exceptions marked N/A are *not* part of Stable ABI. | |
| Exceptions marked N/A are *not* part of the Stable ABI. |
| * :py:class:`zip` | ||
| .. stable-abi-note:: | ||
|
|
||
| These pointers are part of the :ref:`Stable ABI <stable>`. |
There was a problem hiding this comment.
| These pointers are part of the :ref:`Stable ABI <stable>`. | |
| These types are part of the :ref:`Stable ABI <stable>`. |
I think it's more suitable here?
There was a problem hiding this comment.
I wanted to be a bit more specific here: make it clear I'm not referring to the C types (PyObject/PyTypeObject).
| ancestor = ancestor.parent | ||
| else: | ||
| # no skip; add the annotation | ||
| annotation = _stable_abi_annotation(record) |
There was a problem hiding this comment.
This approach seems a bit fragile and wasteful, we already have the Stable ABI data, but we're duplicating it with hand-written tables. Can we at least assert it matches stable_abi_data?
There was a problem hiding this comment.
I haven't found a good way to do the assert.
I think this automation is a good tool -- it probably prevented a bunch of mistakes -- but where it has subpar results, we shouldn't be afraid to drop it and fall bask to writing things manually, like everywhere else in the docs.
If we start seeing many "S.ABI" columns, maybe we should automate that, but I don't think we're there yet.
| has_content = True | ||
|
|
||
| def run(self) -> list[nodes.Node]: | ||
| node = nodes.Element() # Anonymous container for parsing |
There was a problem hiding this comment.
Can we note use SphinxDirective.parse_content_to_nodes to simplify a little?
2 participants
Add two directives:
.. stable-abi-note::adds a note with similar formatting as the auto-generated notes (not exact; that can be fixed in CSS which is in a different repo).. omit-stable-abi-notes::a block in which autogenerated notes are omittedApply that to the tables of exceptions & iteration types.
(This PR has lots of indentation changes; hide them with
?w=1in GitHub or-won the Git command line.)