gh-101100: Docs: Check Sphinx warnings and fail if improved

[hugovk]

Recently I improved some colour contrast for Pygments, and they have a file of current contrast ratios. If they're improved by a PR, the CI will fail to make sure the ratio constants are updated, to ensure continual improvement with no regressions.

This is a good idea!

Let's add it here, to check if any files in .nitignore (which may have Sphinx warnings) switch to having no warnings. Then we can remove them from .nitignore to make sure they remain free of warnings.

I was going to add another Sphinx build, a fourth, to touch the relevant files, so only those would be rebuilt. But four builds is far too many!

Instead, let's build only once and save the warnings to a file. Then we can process the file and do the three phases:

• Annotate PRs with Sphinx nitpicks (as before)
• Ensure some files always pass Sphinx nit-picky mode (as before)
• Check for improved files that can be removed from .nitignore (new!)

---

📚 Documentation preview 📚: https://cpython-previews--106460.org.readthedocs.build/

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

[hugovk]

Marked as draft to make some temporary commits to demonstrate errors.

First, the new check finds five files that no longer contain warnings!

Congratulations! You improved:
Doc/c-api/dict.rst
Doc/c-api/weakref.rst
Doc/library/cgi.rst
Doc/library/cmath.rst
Doc/library/curses.ascii.rst
Please remove from Doc/tools/.nitignore

https://github.com/python/cpython/actions/runs/5468129112/jobs/9955353278?pr=106460

Some of these files were deleted along with PEP 594's dead batteries. Others have been "accidentally" fixed since .nitignore was first compiled.

[hugovk]

Adding a (temporary) warning to 3.12.rst, which is not allowed warning, gives:

Error: must not contain warnings:
Doc/whatsnew/3.12.rst
9: WARNING: c:func reference target not found: PyFrame_BlockSetup

Plus the file is annotated.

https://github.com/python/cpython/actions/runs/5468217855/jobs/9955568557?pr=106460

(Edit: output updated per 3522e2c)

[hugovk]

Updating from main finds a new file that's been fixed! 🎉

Congratulations! You improved:
Doc/library/getopt.rst
Please remove from Doc/tools/.nitignore

[miss-islington]

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

[miss-islington]

Sorry @hugovk, I had trouble checking out the 3.12 backport branch.
Please retry by removing and re-adding the "needs backport to 3.12" label.
Alternatively, you can backport using cherry_picker on the command line.
cherry_picker 806d7c98a5da5c1fd2e52a5b666f36ca4f545092 3.12

[hugovk]

3.12 doesn't yet have the refactored .github/workflows/reusable-docs.yml workflow, so let's leave this backport for that 👍

[CAM-Gerlach]

Looks like that was landed and this is required to backport #108065 , so retrying the backport.

[miss-islington]

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

[miss-islington]

Sorry, @hugovk, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 806d7c98a5da5c1fd2e52a5b666f36ca4f545092 3.12

[bedevere-bot]

GH-108116 is a backport of this pull request to the 3.12 branch.

[CAM-Gerlach]

Had to manually backport it due to conflicts in .nitignore, and might need to resolve a few additional discrepancies there once it builds.