gh-141004: Add a CI job ensuring that new C APIs include documentation

[ZeroIntensity]

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.

• Issue: Document the entire C API #141004

[StanFromIreland]

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.?

[ZeroIntensity]

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.

[StanFromIreland]

As a compromise, we could go ever simpler, just checking if :: and .. are in the same line as the API name.

[ZeroIntensity]

Hm, that may work, but the list in #141004 was created using a full-text search, not a search for :: or .., so there are probably some APIs that still need work. Let's finish the list in #141004 first, and then we can look into finding more edge cases.

[ZeroIntensity]

I plan on backporting this to prevent conflicts when things are removed from ignored_c_api.txt. Any objections?

[hugovk]

No objection to backporting.

[StanFromIreland]

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

[ZeroIntensity]

I assume that this is broken in strings too, for example: puts("PyAPI_FUNC(int) PySomething(void);"). There are plenty of ways to break the regular expressions.

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?

[ZeroIntensity]

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.