sphinx-autoapi
sphinx-autoapi copied to clipboard
readthedocs
Make imported memebrs link to their documentation.
I am new to sphinx and autoapi 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 a foo package which has a bar module and in it there is a Bar class. The Bar class is central to my library, so I decided to make an import shortcut for it. Inside the __init__.py file of the foo package I have the code:
from foo.bar import Bar
__all__ = ["Bar"]
So the end user can use from foo import Bar instead of the more verbose from foo.bar import Bar. Since I declared Bar in the __all__ variable, it gets picked up by autoapi and documented in the generated page for the foo package. There is also a page for the foo.bar module which contains the full docstring of the class. The problem is that I can't get the Bar class in the foo page to link to the documentation of Bar on the foo.bar page.
If I have the "imported-members" option in conf.py, the docstring of the Bar class is displayed in both the foo and foo.bar pages with no link between them. This is an unnecessary duplication and it makes the user think that there are two Bar 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 the foo.bar page and on the foo page, Bar is listed in the package's contents, but that's it. It doesn't link to anything. So the user knows that foo.Bar is an alias, but he doesn't know to what. I'd like the Bar in the foo page to link to the full docstring in the foo.bar page, but I couldn't figure out how to accomplish that.
Any ideas?
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.
