Description
Describe the bug
When a subclass is added, implicit docstring inheritance by its methods can create ambiguous cross-reference targets in the docstrings of the methods of the parent class.
To Reproduce
Start with a minimal project:
$ sphinx-quickstart --sep --dot _ -pfoo -afoo -r0 -len --suffix .rst --master index --ext-autodoc -m
Edit index.rst to include
.. automodule:: themodule
:members:
and write the following themodule.py:
class A:
"""The A."""
def dothis(self):
"""Call :obj:`.dothat`."""
def dothat(self):
"""Really do it."""
class Unrelated:
"""Nothing related."""
def dothat(self):
"""Has the same name as :obj:`A.dothat`, but otherwise unrelated."""
Build the docs with themodule.py in the PYTHONPATH (PYTHONPATH=. make html) -- things work fine; in particular the doc of A.dothis correctly links to A.dothat.
Now let's say someone adds (in the same module) a subclass of A that overrides dothis, but doesn't bother with a docstring:
class B(A):
def dothis(self): pass
Trying to build the docs now results in a warning:
/tmp/testdocs/themodule.py:docstring of themodule.B.dothis:1: WARNING: more than one target found for cross-reference 'dothat': themodule.A.dothat, themodule.Unrelated.dothat
i.e. B.dothis inherited A.dothis's docstring, but doesn't know what ":obj:`.dothat`" is supposed to refer to. I believe it should actually resolve it to mean B.dothat (which happens to be equal to A.dothat). (emphasis as this is the actual issue at hand) Indeed, if B also defines dothat:
class B(A):
def dothis(self): pass
def dothat(self): pass
then the docstring of B.dothis does link to B.dothat.
Expected behavior
In B.dothis's docstring, ":obj:`.dothat`" should link to A.dothat (if B.dothat does not exist).
Your project
n/a
Screenshots
n/a
Environment info
- OS: linux
- Python version: 3.7.2
- Sphinx version: 1.8.5
- Sphinx extensions: sphinx.ext.autodoc
- Extra tools: n/a
Additional context
Add any other context about the problem here.
- [e.g. URL or Ticket]