gh-141004: GHA: Run check-c-api-docs check on docs-only PRs

[StanFromIreland]

As mentioned in #143564 (review) by @ZeroIntensity:

One extra thing I would like to do is run the script on docs PRs, since a name being documented while also being in ignored_c_api.txt will cause it to fail. So, if someone merges new documentation without updating ignored_c_api.txt, we'll see blocking failures on all C code PRs until we fix it. I haven't looked too closely at the GHA for change detection, but if you see an easy way to do that, would you mind doing it in this PR?

We could keep it in the check-generated-files job, but that would make it quite messy as all the other checks would have to be excluded in the case when only run-docs is true. And, to avoid having to configure, I run the script directly (since it uses PYTHON_FOR_REGEN anyway, there shouldn't be a difference).

On this PR, the new job ran in 13 seconds.

• Issue: Document the entire C API #141004

[ZeroIntensity]

This makes sense to me, but I'd like one of the GHA experts to have a look.

[encukou]

@webknjaz, does this look interesting?

[webknjaz]

Personally, I've been leaning towards having a single workflow tool target invocation per job. In this case it's one make command (I've implemented my reusable-tox.yml thing around the same approach and a it turned out to be a pretty powerful strategy).

So yes, it's a good idea — it can run a check that would otherwise be skipped, sometimes. But I also foresee better responsiveness even in full runs. This could be taken farther at some point (follow-ups) but it's well-scoped as it is.

One thing I'd ask, though would be moving the new job into a reusable-*.yml module so this doesn't contribute to cluttering the huge YAML file more than it is already. No other comments otherwise.

---

On this PR, the new job ran in 13 seconds.

In that case, I'd maybe reduce the job timeout to 5 minutes or less. This tends to improve responsiveness too, plus catch problems with sudden slowdowns w/o wasting too much CPU.

[StanFromIreland]

One thing I'd ask, though would be moving the new job into a reusable-*.yml module
...
reduce the job timeout to 5 minutes

Done :-)

[webknjaz]

I think this is ready, I left a style note, though. But that's inconsistent across the CI definitions anyway, so not important.

[encukou]

As I replied to the comment mentioned in the OP:

If we do [this], we should take the names from the newly-built Intersphinx inventory, rather than parse the .rst.

Here's the code to parse Intersphinx inventory: main...encukou:cpython:doccheck-intersphinx

Would it be possible to hook up GHA so that the Doc/build/html/objects.inv file generated in the “Doc build” step is accessible? And perhaps use a slightly older one if docs weren't rebuilt?
(Not necessarily in this PR of course.)

[StanFromIreland]

Would it be possible to hook up GHA so that the Doc/build/html/objects.inv file generated in the “Doc build” step is accessible?

Yes we could, we can upload the artifact in the docs build and run the c-api check when it is available.

Edit: Funnily enough, here is an example of just that: #143742

Since it is not necessary yet, I suggest it is done in a future PR.

[StanFromIreland]

I can open a PR on your fork against your branch with the changes when this is merged.

[encukou]

Thank you!

Feel free to send PRs to my branch. Or merge to your branch and send the CPython PR from that.

[webknjaz]

Here's the code to parse Intersphinx inventory: main...encukou:cpython:doccheck-intersphinx

Or from sphinx.ext.intersphinx import fetch_inventory if Sphinx is available in that env. I'm using it in a hacky static website that shows tables with linckable objects on the web: https://webknjaz.github.io/intersphinx-untangled/.

[encukou]

fetch_inventory is undocumented; it needs a Sphinx app and returns an Inventory which are both also undocumented. I don't think it's much of a win over zlib…

(Are you sure your site works with the latest Sphinx?)

[webknjaz]

Are you sure your site works with the latest Sphinx?

Yeah, I was lazy and didn't pin versions. So it always pulls whatever's latest on PyPI (every three four hours): https://github.com/webknjaz/intersphinx-untangled/blob/dbb400751a169988d486495b160137fc2a594438/.github/workflows/build-gh-pages.yml#L26C48-L26C54. On that note, I just realized I'm passing a fake object in there (see a dozen lines below). YOLO!