gh-101100: Fix Sphinx warning in gc.rst and refactor docs clean list

[hugovk]

Fix the single Sphinx warning in gc.rst, add the file to the clean list (so new warnings will fail the build), and refactor the clean list into a little Python script to keep the GitHub workflow from getting too big.

• Issue: Fix all Sphinx reference warnings in the documentation #101100

[CAM-Gerlach]

A couple comments, otherwise LGTM, thanks

[CAM-Gerlach]

One followup comment, otherwise LGTM — thanks @hugovk !

[CAM-Gerlach]

Sorry, a couple more followup fixes after @ezio-melotti 's suggested changes...

[hugovk]

Thanks! I've got a list of ~180 other files we can already add to clean-files.txt. Shall we do it in this PR?

[CAM-Gerlach]

My inclination would be to leave that for an immediate followup PR to keep them separate in the commit history and avoid lengthening this one further, but I don't feel strongly about it and would of course defer to you and @ezio-melotti if you do.

It would be good to do as an immediate follow-up, though, as it will help avoid regressions and also merge conflicts when adding more files (which are far more likely with a short file list). Thanks!

[CAM-Gerlach]

LGTM, thanks @hugovk !

[AlexWaygood]

(Doesn't need to be done in this PR.)

Maybe it would be better to keep a "dirty list" rather than a "clean list". I'd quite like to help out with getting the number of sphinx warnings down, and it would be handy to have a guaranteed-to-be-up-to-date list of all files that have yet to be worked on. Using a dirty list rather than a clean list would also mean that any new files added to the Doc/ directory would by default be tested with nitpicks enabled, whereas currently the default is for new files to be tested without nitpicks enabled.

The only downside I can see is that the dirty list would have to initially be pretty long. But I don't think that's actually a problem; it would be helpful to have an easy visualisation of the scale of the task still to be done.

[CAM-Gerlach]

Yeah, that sounds like a pretty compelling to me for the aforementioned followup. If we are going to take that approach, which certainly might make sense and matches the pattern of listing files to ignore rather than check (.gitignore, etc). In that event, we would probably want to specify directory-level exclude support, as well as an include list so we could, e.g, exclude all the files in Doc/whatsnew except for the current version's, without having to manually set and update that for every branch, to minimize ongoing maintenance (since that would be permanent).

[AlexWaygood]

In that event, we would probably want to specify directory-level exclude support, as well as an include list so we could, e.g, exclude all the files in Doc/whatsnew except for the current version's, without having to manually set and update that for every branch, to minimize ongoing maintenance (since that would be permanent).

You could add regex or glob support for the excludelist, but I'd personally vote against supporting an includelist and an excludelist simultaneously. That sounds like it would be overcomplicating things unnecessarily imho. Just add all files in Doc/whatsnew except 3.12.rst to the excludelist for now, and remove them one by one as we sort them out (or add a comment next to that section of the excludelist saying that it's not high priority to fix them).

We've done a very similar thing for a while for our stubtest check over at typeshed. Stubtest is a script that verifies that various things in the stub are consistent in various ways with the objects at runtime. It's a very useful tool, but it necessitates keeping a long allowlist -- some of these are inconsistencies that are still to be completed, but many have comments next to them or above them indicating that they can't be resolved for one reason or another. The system works very well for us. (Stubtest's allowlist has regex support, but not globbing support.)

https://github.com/python/typeshed/blob/main/tests/stubtest_allowlists/py3_common.txt

[hugovk]

I'd quite like to help out with getting the number of sphinx warnings down

Great!

The only downside I can see is that the dirty list would have to initially be pretty long. But I don't think that's actually a problem; it would be helpful to have an easy visualisation of the scale of the task still to be done.

Sure. There's ~490 total RST files, ~180 clean, so ~310 dirty. Not such a big difference.

Given a dirty list, we'd have to compute the clean list, so we can touch them to rebuild them.

I made the initial clean list by subtracting the list of files with warnings from a list of all files. I tested with all of those, but found that touching two clean files (includes/wasm-notavail.rst and whatsnew/changelog.rst) caused a cascade effect and resulted in a number of dirty files being rebuilt too, and so failing the build. So I've removed those. We'd need a mechanism to exclude them, and potentially others.

[hugovk]

My inclination would be to leave that for an immediate followup PR to keep them separate in the commit history and avoid lengthening this one further, but I don't feel strongly about it and would of course defer to you and @ezio-melotti if you do.

It would be good to do as an immediate follow-up, though, as it will help avoid regressions and also merge conflicts when adding more files (which are far more likely with a short file list). Thanks!

Sure, I'll merge this now and make a new PR right away!

[hugovk]

➡️ #103135

[hugovk]

(Doesn't need to be done in this PR.)

Maybe it would be better to keep a "dirty list" rather than a "clean list". I'd quite like to help out with getting the number of sphinx warnings down, and it would be handy to have a guaranteed-to-be-up-to-date list of all files that have yet to be worked on. Using a dirty list rather than a clean list would also mean that any new files added to the Doc/ directory would by default be tested with nitpicks enabled, whereas currently the default is for new files to be tested without nitpicks enabled.

The only downside I can see is that the dirty list would have to initially be pretty long. But I don't think that's actually a problem; it would be helpful to have an easy visualisation of the scale of the task still to be done.

Please see GH-103191.