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

35 views
Skip to first unread message

Andrew Porter

unread,
Jun 9, 2021, 5:40:29 AMJun 9
to sphinx-users

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.


Many thanks,

Andy.

Mike Jarvis

unread,
Sep 16, 2021, 12:42:16 PMSep 16
to sphinx-users
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
Reply all
Reply to author
Forward
0 new messages