-
Notifications
You must be signed in to change notification settings - Fork 2.1k
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
automodule false positive WARNING: more than one target found for cross-reference #11883
Comments
Thanks for the report, Peter. Currently we've limited manpower for working on autodoc, to let you know. If you'd like to have a go yourself at a (partial) solution I'm happy to help where needed! Thanks, |
@peterjc Assuming you want a solution the easy way is trying |
The tilde prefix is some new syntax to me, https://www.sphinx-doc.org/en/master/usage/domains/python.html doesn't introduce it, it only gets a tiny aside at the very end:
I think that page needs a little more explanation about the use of tilde (~) in references. However, using |
This change surprisingly was blocking using a more recent version of Sphinx (our issue #4584), see: sphinx-doc/sphinx#11883 The *pair* of warnings about Chain being ambiguous had mislead me to think the trigger was the two Bio.PDB.Chain.Chain class references in the docstrings. TODO: Reinstate the type annotation for this method.
This change surprisingly was blocking using a more recent version of Sphinx (our issue #4584), see: sphinx-doc/sphinx#11883 The *pair* of warnings about Chain being ambiguous had mislead me to think the trigger was the two Bio.PDB.Chain.Chain class references in the docstrings. TODO: Reinstate the type annotation for this method.
This change surprisingly was blocking using a more recent version of Sphinx (our issue #4584), see: sphinx-doc/sphinx#11883 The *pair* of warnings about Chain being ambiguous had mislead me to think the trigger was the two Bio.PDB.Chain.Chain class references in the docstrings. TODO: Reinstate the type annotation for this method.
I found a workaround, dropping a possibly ambigous type annotation [something added to the project relatively recently, and after the early Sphinx API doc work was done]. If this was the root cause, then triggering two warnings apparently from the references in two docstrings mislead me: Might it be possible to get a single warning pinpointing the type annotation if Sphinx finds it ambiguous? |
Sure - it wasn't initially obvious that this was a duplicate of #4961, but in hindsight it does seem to be. |
@peterjc man, it's hard enough for the reader to link a huge repo with a broken build that uses Now, if you want to assign blame look no further, here's the root of all evils: I've seen Sphinx maintainers do a fantastic job for years, it's not their fault that Python as a language can't make up their mind on how things should be implemented. So it's not a problem in the Sphinx docs, it's not a problem in the warning message, it's not a problem with autodoc. I told everyone back in Python 3.7 the above linked announcement was going to happen :P |
@electric-coder I'm not looking to place blame. I knew Sphinx and autodoc were complicated - but hadn't really thought about what type annotations might add to the mix, nor even suspect their involvement initially. Thank you for the PEP563 links, this whole area is more complex than I realized having only recently starting using type annotations myself. I'm happy now I know the type annotation was triggering ambiguous reference warnings, we can use the current version of Sphinx, and will keep an eye on #4961. |
This change surprisingly was blocking using a more recent version of Sphinx (our issue biopython#4584), see: sphinx-doc/sphinx#11883 The *pair* of warnings about Chain being ambiguous had mislead me to think the trigger was the two Bio.PDB.Chain.Chain class references in the docstrings. TODO: Reinstate the type annotation for this method.
Describe the bug
This is somewhat related to #4961 and other closed issues.
How to Reproduce
Using Sphinx 7.2.6, macOS, and Biopython as of https://github.com/biopython/biopython/tree/e34c97bf12110d695d011f11daa4d617ceecebe3 downloaded and run as follows:
This works with Sphinx 4.3.2 (which is what we're currently running via pinned dependencies).
Environment Information
Sphinx extensions
Additional context
The two warnings (which cause the build to fail in strict mode) are a pair of false positives:
Despite the wording of the two warnings, there are no simple references to class
Chain
precisely because the package as a whole defines bothBio.Nexus.Nodes.Chain
andBio.PDB.Chain.Chain
. The API doc RST explicitly use the full unambiguous module nameBio.PDB.Chain.Chain
.Something seems to be breaking in parsing the RST docstrings?
The text was updated successfully, but these errors were encountered: