gh-141004: Add a CI job ensuring that new C APIs include documentation #142102
Conversation
ZeroIntensity
requested review from
AA-Turner,
emmatyping,
erlend-aasland,
ezio-melotti and
hugovk
as code owners
| IGNORED.pop(index) | ||
|
|
||
|
|
||
| def is_documented(name: str) -> bool: |
There was a problem hiding this comment.
I think is_documented is a little different from is present. Why not improve the check to include verifying it's a doc declaration, i.e. if it's in the text check it's on the same line as the c:func:: etc.?
There was a problem hiding this comment.
I thought about that, but I decided that it was a case of "practicality beats purity". Running Sphinx or using a regular expression will make this significantly slower, and probably won't save us much in practice.
There was a problem hiding this comment.
As a compromise, we could go ever simpler, just checking if :: and .. are in the same line as the API name.
Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
ZeroIntensity
added
needs backport to 3.13
|
I plan on backporting this to prevent conflicts when things are removed from |
|
No objection to backporting. |
There was a problem hiding this comment.
This currently picks up decelerations in comments, e.g. Py_OldFunction which is an example. This currently passes as the same example is used in the docs.
Edit: I wrote: ZeroIntensity#6
|
I assume that this is broken in strings too, for example: We can't really get this to work perfectly without using an actual C parser. If those comments aren't causing problems for us, why bother? |
|
To clarify: I agree with eventually adding better handling, I just don't think it should be done here. I'd like this script to be as close as possible to the script used to generate the list in #141004. We can expand on this in a later iteration. |
|
I'm going to merge this. For changes regarding the mock C parsing here, please open a new issue and/or PR. |
|
Thanks @ZeroIntensity for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14. |
|
Sorry, @ZeroIntensity, I could not cleanly backport this to |
|
Sorry, @ZeroIntensity, I could not cleanly backport this to |
|
GH-142247 is a backport of this pull request to the 3.14 branch. |
…ntation (pythonGH-142102) Co-authored-by: Hugo van Kemenade <[email protected]> (cherry picked from commit 1a7824a)
… documentation (pythonGH-142102) (cherry picked from commit 1a7824a) Co-authored-by: Peter Bierma <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]>
|
GH-142248 is a backport of this pull request to the 3.13 branch. |
…ntation (pythonGH-142102) Co-authored-by: Hugo van Kemenade <[email protected]> (cherry picked from commit 1a7824a)
… documentation (pythonGH-142102) (cherry picked from commit 1a7824a) Co-authored-by: Peter Bierma <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]>
…entation (GH-142102) (GH-142247) * gh-141004: Add a CI job ensuring that new C APIs include documentation (GH-142102) Co-authored-by: Hugo van Kemenade <[email protected]> (cherry picked from commit 1a7824a) --------- Co-authored-by: Hugo van Kemenade <[email protected]>
…ntation (pythonGH-142102) Co-authored-by: Hugo van Kemenade <[email protected]>
3 participants
This adds a simple job requiring that any new public C APIs come with documentation, which should prevent things from slipping through the cracks each release.