Docs: Add a custom extension to report unresolved cross-references

[AA-Turner]

This adds a custom Sphinx extension to report missing and unresolved cross-references, saving two files to the Sphinx build directory (refwarn.csv and refwarn_count.csv).

The first file reports every instance of missing references as reported by Sphinx, with the domain (e.g. py), role name (e.g. func), reference target (e.g. sum), and source file name, in a CSV format.

The second file aggregates the count of missing references in domain-role-target triples (ignoring the source file), giving a potential prioritisation order for missing references across the documentation.

This PR is presented as a sketch -- I think it is useful (I use it), but I can see arguments against merging it -- especially as I hope that it will someday be deleted!

A

---

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

[hugovk]

Sounds potentially useful, but it's not generating them at the moment due to an error:

Warning, treated as error:
the refwarn extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit
make: *** [build] Error 2

Please could you post some example files?

[AA-Turner]

refwarn.csv:

Domain,Type,Target,Source
c,identifier,wrapperbase,c-api\descriptor.rst
py,func,warnings.WarningMessage,c-api\exceptions.rst
py,attr,__module__,c-api\exceptions.rst
py,attr,__traceback__,c-api\exceptions.rst
py,attr,__context__,c-api\exceptions.rst
py,attr,__cause__,c-api\exceptions.rst
py,attr,__suppress_context__,c-api\exceptions.rst
c,macro,USE_STACKCHECK,c-api\exceptions.rst
c,data,PyExc_EnvironmentError,c-api\exceptions.rst
...

refwarn_count.csv:

Count,Domain,Type,Target
32,py,meth,__exit__
31,py,meth,__getitem__
26,py,meth,__enter__
22,py,class,Document
21,py,meth,__get__
21,py,meth,__init__
20,py,meth,__getattr__
20,py,meth,__iter__
20,py,meth,__new__
...

A

[hugovk]

Looks useful. Does it make sense to write out the CSV files (empty except headers) when not run in nitpicky mode? Maybe add some type hints?

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

[hugovk]

EPUB failure:

writing mimetype file...
writing META-INF/container.xml file...
writing content.opf file...
WARNING: unknown mimetype for refwarn.csv, ignoring [epub.unknown_project_files]

We don't want to add the CSV files to the EPUB, so should either add them to epub_exclude_files in conf.py, or write them somewhere else.