Infra: Check Sphinx warnings on CI

[hugovk]

This is similar to what we have in the CPython repo, most recently: python/cpython#106460, and will help us gradually remove Sphinx warnings, and avoid new ones being introduces.

It checks three things:

1. If a file previously had no warnings (not listed in .nitignore), and new ones are introduced, it fails

   • -> To prevent regressions

2. If a file previously had warnings (it's lsited in .nitignore), but now has none, it fails and tells us to remove it from .nitignore

   • To help us incrementally improve over time

3. If a file previously had warnings (it's listed in .nitignore), and still has warnings, it doesn't fail, but it will annotate the PR to show the warning

   • To make them more visible, and give us the opportunity to fix them

I've intentionally kept the code and layout as close as possible to the CPython version (see https://github.com/python/cpython/tree/main/Doc/tools) for easier future maintenance.

---

📚 Documentation preview 📚: https://pep-previews--3213.org.readthedocs.build/

[hugovk]

It found one! #3189 was merged since I branched :)

[AA-Turner]

See #3214 to resolve several warnings.

[AA-Turner]

The only outstanding warnings are now unreferenced footnotes, of which we have 59 across 40 files:

Full list

pep-0232.txt:250: WARNING: Footnote [3] is not referenced.
pep-0262.txt:322: WARNING: Footnote [1] is not referenced.
pep-0277.txt:104: WARNING: Footnote [1] is not referenced.
pep-0292.txt:199: WARNING: Footnote [3] is not referenced.
pep-0292.txt:204: WARNING: Footnote [5] is not referenced.
pep-0299.txt:112: WARNING: Footnote [1] is not referenced.
pep-0323.txt:478: WARNING: Footnote [1] is not referenced.
pep-0323.txt:481: WARNING: Footnote [2] is not referenced.
pep-0326.txt:448: WARNING: Footnote [5] is not referenced.
pep-0326.txt:458: WARNING: Footnote [8] is not referenced.
pep-0326.txt:466: WARNING: Footnote [11] is not referenced.
pep-0329.txt:258: WARNING: Footnote [2] is not referenced.
pep-0336.txt:122: WARNING: Footnote [1] is not referenced.
pep-0340.txt:566: WARNING: Footnote [1] is not referenced.
pep-0343.txt:956: WARNING: Footnote [12] is not referenced.
pep-0355.txt:549: WARNING: Footnote [1] is not referenced.
pep-0361.txt:274: WARNING: Footnote [1] is not referenced.
pep-0370.txt:219: WARNING: Footnote [6] is not referenced.
pep-0371.txt:420: WARNING: Footnote [6] is not referenced.
pep-0371.txt:427: WARNING: Footnote [8] is not referenced.
pep-0419.txt:511: WARNING: Footnote [4] is not referenced.
pep-0419.txt:514: WARNING: Footnote [5] is not referenced.
pep-0425.txt:277: WARNING: Footnote [1] is not referenced.
pep-0425.txt:280: WARNING: Footnote [2] is not referenced.
pep-0448.txt:232: WARNING: Footnote [3] is not referenced.
pep-0480.txt:888: WARNING: Footnote [6] is not referenced.
pep-0480.txt:891: WARNING: Footnote [9] is not referenced.
pep-0480.txt:892: WARNING: Footnote [10] is not referenced.
pep-0488.txt:333: WARNING: Footnote [10] is not referenced.
pep-0491.txt:537: WARNING: Footnote [1] is not referenced.
pep-0492.txt:1404: WARNING: Footnote [1] is not referenced.
pep-0502.txt:688: WARNING: Footnote [10] is not referenced.
pep-0502.txt:692: WARNING: Footnote [11] is not referenced.
pep-0505.rst:858: WARNING: Footnote [5] is not referenced.
pep-0545.txt:573: WARNING: Footnote [2] is not referenced.
pep-0571.rst:361: WARNING: Footnote [18] is not referenced.
pep-0572.rst:1317: WARNING: Footnote [1] is not referenced.
pep-0617.rst:798: WARNING: Footnote [#] is not referenced.
pep-0622.rst:2198: WARNING: Footnote [1] is not referenced.
pep-0622.rst:2210: WARNING: Footnote [5] is not referenced.
pep-0644.rst:366: WARNING: Footnote [11] is not referenced.
pep-0645.rst:151: WARNING: Footnote [2] is not referenced.
pep-0645.rst:153: WARNING: Footnote [3] is not referenced.
pep-0654.rst:1495: WARNING: Footnote [13] is not referenced.
pep-3100.txt:346: WARNING: Footnote [26] is not referenced.
pep-3104.txt:485: WARNING: Footnote [15] is not referenced.
pep-3114.txt:208: WARNING: Footnote [6] is not referenced.
pep-3115.txt:300: WARNING: Footnote [1] is not referenced.
pep-3115.txt:303: WARNING: Footnote [2] is not referenced.
pep-3115.txt:306: WARNING: Footnote [3] is not referenced.
pep-3115.txt:309: WARNING: Footnote [4] is not referenced.
pep-3119.txt:847: WARNING: Footnote [2] is not referenced.
pep-3119.txt:850: WARNING: Footnote [3] is not referenced.
pep-3119.txt:869: WARNING: Footnote [9] is not referenced.
pep-3119.txt:872: WARNING: Footnote [10] is not referenced.
pep-3135.txt:216: WARNING: Footnote [1] is not referenced.
pep-3135.txt:219: WARNING: Footnote [2] is not referenced.
pep-3145.txt:137: WARNING: Footnote [8] is not referenced.
pep-3147.txt:607: WARNING: Footnote [21] is not referenced.

A

[AA-Turner]

I've opened a first batch of 10 PRs to resolve PEPs 232 through 340.