Sphinx autodoc fails to reference objects through intersphinx

[Dreamsorcerer]

As we don't seem to use autodoc anywhere, it seems we've missed this issue.

When using autodoc in a project, it will inspect the fully resolved name of an object, for example aiohttp.client.ClientSession. As the submodules are implementation details and we don't want to expose them to users, we only have aiohttp.ClientSession etc. in our docs.

To fix this, we should be able to use the :canonical: directive to create aliases that intersphinx can use for references. The end result should still not display the submodules to users reading the docs, but will allow intersphinx linking via the submodules.
https://www.sphinx-doc.org/en/master/usage/domains/python.html#directive-option-py-method-canonical

This probably needs to be done for almost all object in the reference docs.

[MohsenHNSJ]

I have encountered this issue, and i found that autoapi does work with the current status of documentation.

The exact error from autodoc is the following:

WARNING: py:class reference target not found: aiohttp.client.ClientSession [ref.class]

[webknjaz]

@MohsenHNSJ technically, the error isn't from autodoc. Autodoc just generates RST files. It uses reference names it sees in runtime. But then you invoke sphinx-build which attempts to look up objects with those names and can't find any because our Sphinx docs only documents the aliased refs without their canonical addresses.

[MohsenHNSJ]

@webknjaz Thanks for the clarification. I have switched to autoapi after that and since then, no similar issue has happened.