Open ShaiAvr opened 7 months ago
Hey,
we have the same problem. Did u find a solution?
Sphinx 4 introduced a :canonical:
option to some of the directives (https://www.sphinx-doc.org/en/master/usage/domains/python.html#directive-option-py-class-canonical). We should make use of this in the templates.
I am running into the same issue.
I am new to
sphinx
andautoapi
so I may be missing something, but I searched the documentation and the internet and couldn't find a solution to my problem. I have afoo
package which has abar
module and in it there is aBar
class. TheBar
class is central to my library, so I decided to make an import shortcut for it. Inside the__init__.py
file of thefoo
package I have the code:So the end user can use
from foo import Bar
instead of the more verbosefrom foo.bar import Bar
. Since I declaredBar
in the__all__
variable, it gets picked up byautoapi
and documented in the generated page for thefoo
package. There is also a page for thefoo.bar
module which contains the full docstring of the class. The problem is that I can't get theBar
class in thefoo
page to link to the documentation ofBar
on thefoo.bar
page.If I have the "imported-members" option in
conf.py
, the docstring of theBar
class is displayed in both thefoo
andfoo.bar
pages with no link between them. This is an unnecessary duplication and it makes the user think that there are twoBar
symbols without explaining that one is just an alias for the other. If I disable the "imported-members" option, then the docstring only appears in thefoo.bar
page and on thefoo
page,Bar
is listed in the package's contents, but that's it. It doesn't link to anything. So the user knows thatfoo.Bar
is an alias, but he doesn't know to what. I'd like theBar
in thefoo
page to link to the full docstring in thefoo.bar
page, but I couldn't figure out how to accomplish that.Any ideas?