Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 6 commits into
base: main
Choose a base branch
from

Conversation

AA-Turner
Copy link
Member

@AA-Turner AA-Turner commented Oct 1, 2023

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/

@AA-Turner AA-Turner added type-feature A feature request or enhancement docs Documentation in the Doc dir skip issue skip news labels Oct 1, 2023
Doc/tools/extensions/refwarn.py Outdated Show resolved Hide resolved
Doc/tools/extensions/refwarn.py Outdated Show resolved Hide resolved
@hugovk
Copy link
Member

hugovk commented Oct 1, 2023

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?

Doc/tools/extensions/refwarn.py Outdated Show resolved Hide resolved
Doc/tools/extensions/refwarn.py Outdated Show resolved Hide resolved
Doc/tools/extensions/refwarn.py Outdated Show resolved Hide resolved
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
@AA-Turner
Copy link
Member Author

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
Copy link
Member

hugovk commented Oct 9, 2023

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
awaiting review docs Documentation in the Doc dir skip issue skip news type-feature A feature request or enhancement
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants