autoapi and 'more than one target for cross-reference' warnings

[Andrew Porter]

Hello,

We use Sphinx and AutoAPI to generate the API documentation for our Python project.

Our project consists of several sub-modules, each of which is defined with an `__init__.py` file containing an `__all__` list. In order to get AutoAPI to produce detailed documentation

for each individual class, we also have an `__all__` list at the end of each source file which

lists the classes to document.

Unfortunately, when generating the documentation for this project we get a lot of warnings such as:

Projects/PSyclone/src/psyclone/transformations.py:docstring of psyclone.transformations.KernelGlobalsToArguments.validate:: WARNING: more than one target found for cross-reference 'TransformationError': psyclone.psyir.transformations.TransformationError, psyclone.psyir.transformations.transformation_error.TransformationError

where the `TransformationError` class is implemented in psyclone/psyir/transformations/transformation_error.py but is made available as part of the `psyclone.psyir.transformations` module.

I would have thought this was a fairly common use case. Are we doing something unexpected or is there some way of getting AutoAPI to do the 'right thing'?

I'm using Sphinx 4.0.2 and autoapi 2.0.1 under Ubuntu 20.04 and python 3.8.5.

BTW, you can see the config file at: https://github.com/stfc/PSyclone/blob/master/doc/reference_guide/source/conf.py

Many thanks,

Andy.

[Mike Jarvis]

Did anyone have a solution to this problem?  I have exactly the same scenario, where I import classes into a top level namespace, and Sphinx v4 cannot disambiguate between the top-level version and the lower-level module version.  E.g.

```

WARNING: more than one target found for 'any' cross-reference 'Catalog': could be :py:class:`treecorr.Catalog` or :py:class:`treecorr.catalog.Catalog`

```

My current workaround it to downgrade to Sphinx 3.5.4, which works as I expect.  Is this an intended "feature" of Sphinx 4.x?  Can I add something to the config file to get back to the old resolution behavior?

Thanks,
Mike