keyword paramtype warns "more than one target found for cross-reference 'list'"

[kristapratico]

Describe the bug

I have a class that uses keyword/paramtype to declare in the docstring that the type expected is a list[thing]: https://github.com/Azure/azure-sdk-for-python/blob/49c96611c69be2a769917dccd459692e72e945d3/sdk/advisor/azure-mgmt-advisor/azure/mgmt/advisor/models/_models_py3.py#L849

This library also contains a number of classes with methods called list(...).

Instead of resolving list as a python list, sphinx tries to make a cross-reference to the list methods found in the library and shows the following warning:

docstring of azure.mgmt.advisor.models._models_py3.SuppressionContractListResult:1: WARNING: more than one target found for cross-reference 'list': azure.mgmt.advisor.operations.Operations.list, azure.mgmt.advisor.operations.RecommendationMetadataOperations.list, azure.mgmt.advisor.operations.RecommendationsOperations.list, azure.mgmt.advisor.operations.SuppressionsOperations.list

Note that this doesn't occur when using param / type, it seems to specifically be something about using keyword/paramtype.

How to Reproduce

1. clone https://github.com/Azure/azure-sdk-for-python
2. pip install tox
3. cd sdk/advisor/azure-mgmt-advisor
4. tox run -e strict-sphinx -c ../../../eng/tox/tox.ini --root .

Note that the tox env uses sphinx==6.2.1, but this reproduces with the latest sphinx version as well.

Environment Information

Platform:              linux; (Linux-5.15.133.1-microsoft-standard-WSL2-x86_64-with-glibc2.35)
Python version:        3.11.7 (main, Dec 12 2023, 17:23:25) [GCC 11.4.0])
Python implementation: CPython
Sphinx version:        6.2.1
Docutils version:      0.18.1
Jinja2 version:        3.1.2
Pygments version:      2.17.2

Sphinx extensions

conf file is here: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/sphinx/conf.py

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.doctest',
              'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', 'sphinx.ext.napoleon',
              'myst_parser', 'sphinxcontrib.jquery']

Additional context

No response

[picnixz]

I can confirm the issue with a smaller MWE (even though the build does not indicate an issue with the reference, but the HTML links are indeed incorrect).

[kristapratico]

Thanks for the quick resolution @picnixz!

[picnixz]

@kristapratico I don't want to merge until I've added some tests, which I'll do this week-end, so you'll need to wait a bit before the fix is released.

[kristapratico]

@picnixz no problem. Also, I did verify that your patch does fix the warnings for me. Thanks for your work!

[kristapratico]

@picnixz any chance this bug fix will be in the next release? Thanks!

[picnixz]

Ah yes, I can push it but I don't have the permissions for pushing it on PyPI.