Docs: Intersphinx references require fully qualified name for 2.0 documentation

[janssenhenning]

Describe the current issue

Starting with version 2.0 it is no longer possible to use interpshinx references like :py:class:`aiida.orm.Dict` in external documentations. aiida-fleur has intersphinx set up like this

intersphinx_mapping = {
    'aiida': ('https://aiida-core.readthedocs.io/en/latest/', None),
}

Which prior to 2.0 generated a link like this https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.orm.html#aiida.orm.Dict for the above reference (To see that it still works replace latest with v1.6.8 like here). With 2.0 the reference can no longer be resolved leading to errors like in this CI job

Describe the solution you'd like

Of course these references can be replaced with the fully qualified name :py:class:`aiida.orm.nodes.data.dict.Dict` , but this seems quite fragile since aiida-core relies on the exporting in __init__.py files a lot. Replacing the intersphinx link with the v1.6.8 documentation is a fix but this would only be a temporary solution

[ltalirz]

Thanks for reporting @janssenhenning, I noticed this in the AiiDA plugin cutter as well.

Do we know what changed here? @sphuber

[chrisjsewell]

Yep I changed it in 58a5d80, because it was (silently) broken before.
Basically, you can have autodoc for __all__ imports or for absolute imports, but you can't have both.

[chrisjsewell]

We can switch over to only documenting via __all__, which I'd prefer, but it will likely take a bit of work

[ltalirz]

From the commit message

Then, to overcome the fact that we would still like to refer to the top-level module paths
(e.g. aiida.orm.Computer rather than aiida.orm.computers.Computer),
some code has been added in conf.py, to specify these aliases.

I just think that this is an important feature for plugin authors as well.

I guess a temporary fix can be to specify those aliases in the plugin's conf.py as well (we could also do this in the plugin cutter) but this is not a long term solution as they will inevitably go out of sync.

Edit: If we make the aliases importable from the plugin side, that's already better.

[ltalirz]

I've run into this issue again.

I will open a PR to move the AutodocAliases class inside aiida-core such that plugins can import them as well in their documentation.