Feature Request: Ability to silence more than one target found for cross-reference warning

[Blendify]

Subject: Feature request to extend the suppress_warnings function

Problem

A project that I work with currently has 1000+ warning from duplicate cross references.
WARNING: more than one target found for cross-reference 'float' while e may be able to fix this later, it would be great if we can silence them in the mean time.

Procedure to reproduce the problem

Create duplicate cross references.

Error logs / results

`WARNING: more than one target found for cross-reference 'float'` 

Expected results

The error should not appear.

Reproducible project / your project

https://developer.blender.org/diffusion/B/browse/master/doc/python_api/sphinx_doc_gen.py

Environment info

• OS: Windows 10
• Python version: 3.5.x
• Sphinx version: 1.6.1

[tk0miya]

+1. I will add new filter to suppress_warnings.
It would be nice if you provide small reproducible example for us (I'd failed to reproduce the warning...)

[Blendify]

I think this actually is a bigger issue... I think the issue is the auto-linking for int, string, and, float types in Info field lists. I tried to scale this down to one case which can be seen below:

In one rst file:

.. module:: bge.constraints

.. function:: createConstraint(pivot_y=0.0)

   Creates a constraint.

   :arg pivot_y: Pivot Y position. (optional)
   :type pivot_y: float

   :return: A constraint wrapper.
   :rtype: :class:`~bge.types.KX_ConstraintWrapper`

In another rst file:

.. module:: bmesh.types

.. class:: BMLayerAccessVert

   .. attribute:: float

      Generic float custom-data layer.
      
      type: :class:`BMLayerCollection`

.. class:: BMLayerAccessLoop

   .. attribute:: float

      Generic float custom-data layer.
      
      type: :class:`BMLayerCollection`

[tk0miya]

Thank you for quick response. reproduced!
And I send #3869. It will resolve this problem.
Thanks,

[Blendify]

I think what would really help is the ability to just not make these links. For us it does not make sense and the links are not relevent. E.g. a link will link to a class in a different class in a different module that does not relate to the orginal link in anyway. We just need it to tell the data type instead.

[tliron]

Here's a quick workaround to put in conf.py:

class PatchedPythonDomain(PythonDomain):
    def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
        if 'refspecific' in node:
            del node['refspecific']
        return super(PatchedPythonDomain, self).resolve_xref(
            env, fromdocname, builder, typ, target, node, contnode)
    
def setup(sphinx):
    sphinx.override_domain(PatchedPythonDomain)

[Blendify]

@tliron thanks and sorry for the wait but while testing it out I get the error NameError: name 'PythonDomain' is not defined might I have done something wrong?

[tliron]

You will also need this:

from sphinx.domains.python import PythonDomain

[Blendify]

Ah thanks.

[tliron]

I understand that the feature requested was specifically to silence the warning, but I think some of us would like to turn off the feature entirely. To be honest, it's hard for me to imagine the use case for this feature.

For those who want to turn off the feature, my patch would work. But it seems like this should be part of Sphinx.

[pitrou]

Hi, I tried the workaround mentioned in #3866 (comment), but now I get another error:

Warning, treated as error:
/home/travis/build/tornadoweb/tornado/tornado/platform/asyncio.py:docstring of tornado.platform.asyncio.AsyncIOMainLoop:1:py:obj reference target not found: IOLoop

See https://travis-ci.org/tornadoweb/tornado/jobs/291144347#L1444

Any guidance on this?

[tk0miya]

@pitrou Is that related with this issue? And did you mean that is a bug of Sphinx?
This is isseus list of Sphinx, not forum. Please move to forum if it is question.

Thanks,

[pitrou]

@tk0miya, yes this is related, since I tried the workaround mentioned here after I got bitten by this issue.

[ashafer01]

I came across this issue because I deliberately had created a "canonical path" for user import in my project, which obviously created the 'more than one target found' warning. I ended up adapting @tliron's response to override find_obj instead so that it would always resolve the desired path if it was found there:

class MyPythonDomain(PythonDomain):
    def find_obj(self, env, modname, classname, name, type, searchmode=0):
        """Ensures an object always resolves to the desired module if defined there."""
        orig_matches = PythonDomain.find_obj(self, env, modname, classname, name, type, searchmode)
        matches = []
        for match in orig_matches:
            match_name = match[0]
            desired_name = _desired_base_module + '.' + name.strip('.')
            if match_name == desired_name:
                matches.append(match)
                break
        if matches:
            return matches
        else:
            return orig_matches


def setup(sphinx):
    """Use MyPythonDomain in place of PythonDomain"""
    sphinx.override_domain(MyPythonDomain)

[pablosjv]

The @tliron patch needs a slight modification to work for Sphinx 3.4.3. In case someone finds this issue in google recently (like me), here it is:

from sphinx.domains.python import PythonDomain

class PatchedPythonDomain(PythonDomain):
    def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
        if 'refspecific' in node:
            del node['refspecific']
        return super(PatchedPythonDomain, self).resolve_xref(
            env, fromdocname, builder, typ, target, node, contnode)

def setup(sphinx):
    sphinx.add_domain(PatchedPythonDomain, override=True)

[Blendify]

Thank you!