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.

[webknjaz]

(personal style preference, optional)

Suggested change

	needs.build-context.outputs.run-tests == 'true'
	|| needs.build-context.outputs.run-docs == 'true'
	fromJSON(needs.build-context.outputs.run-tests)
	|| fromJSON(needs.build-context.outputs.run-docs)

[StanFromIreland]

I prefer to remain consistent, I'll leave it up to whoever merges, however.

[webknjaz]

Well, this is consistent with a bunch of places while differs from the others. I think GHA infra could use some linting and will probably look into that later. But again, this is probably something that would be improved in follow-ups.

[hugovk]

As a truthiness check, thing == 'true' is clearer to me than fromJSON(thing).

[StanFromIreland]

I agree with Hugo that is indeed more readable/logical.

[webknjaz]

Alright.. String comparison it is, then. It's just that the readability is poor when multiple conditionals are chained and having function calls makes it a little bit better.

[webknjaz]

Alright.. String comparison it is, then. It's just that the readability is poor when multiple conditionals are chained and having function calls makes it a little bit better.