automodule false positive WARNING: more than one target found for cross-reference

[peterjc]

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:

$ curl -o biopython-e34c97b.zip https://codeload.github.com/biopython/biopython/zip/e34c97bf12110d695d011f11daa4d617ceecebe3
$ unzip biopython-e34c97b.zip
$ cd biopython-e34c97bf12110d695d011f11daa4d617ceecebe3/Doc/
$ make html
...
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] index
/home/pcock/repositories/biopython/Bio/PDB/internal_coords.py:docstring of Bio.PDB.internal_coords.IC_Chain:1: WARNING: more than one target found for cross-reference 'Chain': Bio.Nexus.Nodes.Chain, Bio.PDB.Chain.Chain
/home/pcock/repositories/biopython/Bio/PDB/internal_coords.py:docstring of Bio.PDB.internal_coords.IC_Chain.__init__:1: WARNING: more than one target found for cross-reference 'Chain': Bio.Nexus.Nodes.Chain, Bio.PDB.Chain.Chain
generating indices... genindex py-modindex done
writing additional pages... search done
copying images... [100%] images/phylo-draw-example.png
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 2 warnings.
make: *** [Makefile:20: html] Error 1

This works with Sphinx 4.3.2 (which is what we're currently running via pinned dependencies).

Environment Information

Platform:              linux; (Linux-5.15.133.1-microsoft-standard-WSL2-x86_64-with-glibc2.35)
Python version:        3.10.12 | packaged by conda-forge | (main, Jun 23 2023, 22:40:32) [GCC 12.3.0])
Python implementation: CPython
Sphinx version:        7.2.6
Docutils version:      0.19
Jinja2 version:        3.1.2
Pygments version:      2.16.1

Sphinx extensions

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.todo",
    "sphinx.ext.autosummary",
    "numpydoc",
]

Additional context

The two warnings (which cause the build to fail in strict mode) are a pair of false positives:

$ grep "Chain\`" Bio/*/*/*.py Bio/*/*.py Bio/*.py
Bio/PDB/internal_coords.py::class:`IC_Chain`: Extends Biopython Chain on .internal_coord attribute.
Bio/PDB/internal_coords.py:        The Biopython :class:`Bio.PDB.Chain.Chain` object this extends
Bio/PDB/internal_coords.py:        in parent :class:`Bio.PDB.Chain.Chain`; populate ordered_aa_ic_list with
Bio/PDB/internal_coords.py:        """Build :class:`IC_Chain` numpy coordinate array from biopython atoms.
Bio/PDB/internal_coords.py:        Fill :class:`IC_Chain` arrays hedraL12, L23, L13 and dihedraL14
Bio/PDB/internal_coords.py:        according to AtomKey mappings in :class:`IC_Chain` .hedraNdx and .dihedraNdx
Bio/PDB/internal_coords.py:        parent chain :class:`IC_Chain` object
Bio/PDB/internal_coords.py:        which works at the :class:`IC_Chain` level.

Despite the wording of the two warnings, there are no simple references to class Chain precisely because the package as a whole defines both Bio.Nexus.Nodes.Chain and Bio.PDB.Chain.Chain. The API doc RST explicitly use the full unambiguous module name Bio.PDB.Chain.Chain.

$ more api/Bio.PDB.Chain.rst
:github_url: https://github.com/biopython/biopython/blob/master/Bio/PDB/Chain.py

Bio.PDB.Chain module
====================

.. automodule:: Bio.PDB.Chain
   :members:
   :undoc-members:
   :show-inheritance:

Something seems to be breaking in parsing the RST docstrings?

[AA-Turner]

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,
Adam

[electric-coder]

@peterjc Assuming you want a solution the easy way is trying :ref:`.Chain` with the leading dot, or using the fully qualified name, like :ref:`~Bio.Nexus.Nodes.Chain` or :ref:`~Bio.PDB.Chain.Chain` where the cross-reference is causing the error.

[peterjc]

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:

Note that you can combine the ~ and . prefixes: :py:meth:~.TarFile.close will reference the tarfile.TarFile.close() method, but the visible link caption will only be close().

I think that page needs a little more explanation about the use of tilde (~) in references.

However, using :ref:`~Bio.Nexus.Nodes.Chain` rather than :ref:`Bio.Nexus.Nodes.Chain` doesn't seem to help. I think the root cause is slightly different (testing something now).

[peterjc]

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:

biopython/biopython@5d08d26

Might it be possible to get a single warning pinpointing the type annotation if Sphinx finds it ambiguous?

[electric-coder]

Might it be possible

Might it be possible for you to close the thread since it's a duplicate of #4961 and you failed to include a proper MRE?

[peterjc]

Sure - it wasn't initially obvious that this was a duplicate of #4961, but in hindsight it does seem to be.

[electric-coder]

@peterjc man, it's hard enough for the reader to link a huge repo with a broken build that uses autosummary. But that much I can understand and that's ok.

Now, if you want to assign blame look no further, here's the root of all evils:

PEP 563 may not be the future

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

[peterjc]

@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.