Sphinx: more than one target found for cross reference should prefer current file's method over other libraries methods

[dvorapa]

Subject: more than one target found for cross reference should prefer current file's method over other libraries methods

Problem

• When building HTML of our project, Sphinx outputs cca 200 warnings like this. But half of them should be never thrown, because Sphinx is not sure, whether to use current file's one or imported library's one. For example, see:

/src/pywikibot/interwiki_graph.py:docstring of pywikibot.interwiki_graph.GraphDrawer.__init__:: WARNING: more than one target found for cross-reference 'Subject': scripts.interwiki.Subject, pywikibot.interwiki_graph.Subject

The expected one is clear: The one from current file interwiki_graph should be preferred over the imported, but Sphinx still throwns a warning.

Procedure to reproduce the problem

Build HTML of Pywikibot (last build by us: https://integration.wikimedia.org/ci/job/pywikibot-core-tox-publish/424/console) or try to simulate the situation

Error logs / results

/src/pywikibot/interwiki_graph.py:docstring of pywikibot.interwiki_graph.GraphDrawer.__init__:: WARNING: more than one target found for cross-reference 'Subject': scripts.interwiki.Subject, pywikibot.interwiki_graph.Subject

• https://integration.wikimedia.org/ci/job/pywikibot-core-tox-publish/424/console

Expected results

It should prefer the current file over the imported one

Reproducible project / your project

• https://www.mediawiki.org/wiki/Manual:Pywikibot

Environment info

• OS: Debian Jessie
• Python version: 3.4
• Sphinx version: 1.7.4
• Napoleon, Epytext

[tk0miya]

Where can I see the content ofinterwiki_graph? I'd like to see your source and try to reproduce this.
I can't understand how to do it. Please let me know the way to reproduce (or investigate).

Reproducible project / your project
https://www.mediawiki.org/wiki/Manual:Pywikibot

[dvorapa]

Reproducible project / your project
https://www.mediawiki.org/wiki/Manual:Pywikibot

As you could find out in that link, the source code can be found for example here: https://phabricator.wikimedia.org/diffusion/PWBC/. Also you could look to https://pypi.org/project/pywikibot/.

Sphinx config is in the docs/ folder. Dependencies for Sphinx are written in docs/conf.py and tox.ini's [testenv:doc] (or I could collect them into one list and send them to you, if there will be any problem). The Sphinx build live can be found here: https://doc.wikimedia.org/pywikibot/

The file in the description is stored in pywikibot/ folder. But if you search through build log, you could see there is also a bunch of other similar ones. Today, I wanted to clean "more than one target found for cross reference" warnings, but I found out many of them have this issue.

If there will be any problem, I'll write more detailed step-by-step quide to build our docs.

[tk0miya]

Confirmed with this Dockerfile:

FROM tk0miya/sphinx-html

RUN apt update; apt install -y libmysqlclient-dev
RUN git clone https://gerrit.wikimedia.org/r/pywikibot/core.git
WORKDIR /docs/core
RUN git submodule update --init
RUN pip3 install tox
RUN sed -i -e 's/python3.4/python3.5/' tox.ini
RUN tox -e doc

I understand the issue.

But half of them should be never thrown, because Sphinx is not sure, whether to use current file's one or imported library's one.

At present, there are no way to tell the objects in the file to Sphinx. The autodoc extension only generates reST file. And Sphinx-core only converts it to output format.

I feel your proposal is reasonable. So it would be nice if we can implement it in future!