Warn on all missing references in PEPs

[AA-Turner]

The final PR in this series -- once all the "Resolve unreferenced footnotes" PRs are merged, we can enable Sphinx's nit-picky mode.

A

This also closes #3213.

---

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

[AA-Turner]

Thanks for your help reviewing the references PRs (& fixing far more references yourself) @hugovk!

A

[hugovk]

And thank you very much for finishing them all off!

Good we won't need #3213 :)

What do you think about annotating new warnings in PRs? That's number 3 from #3213.

[AA-Turner]

I was instead going to just set -W by default (#3272) -- we could potentially only set -W in CI, and annotate warnings etc in PRs, but I wonder about author experience if PEPs that 'work' locally suddenly fail when making a PR.

A

[hugovk]

Yes, I think setting -W ("turn warnings into errors") by default makes sense, doing the same both locally and for CI.

And for the CI, also SPHINXOPTS="-w sphinx-warnings.txt" to write them out to a file so they can be annotated in the PR? Will make it more visible where the error is coming from, without having to dig through logs and look up line numbers.

[CAM-Gerlach]

Shouldn't -n be added too, to avoid introducing new broken ref warnings, since we're clean on those?

Also, FYI, this line setting the docutils warning level should be removed, as it is redundant with -W and interferes with e.g. --keep-going.

[AA-Turner]

See #3272 (comment)

[CAM-Gerlach]

Nice, thanks—forgot you could do that.