How to correct 3rd party sphinx ambiguous cross-reference warnings?
15:28 12 Sep 2025

I'm trying to document a variety of classes that use scikit-learn bases BaseEstimator and TransformerMixin. Sphinx builds with a warning that,

/home/jake/github/proj/pkg/__init__.py:docstring of 
sklearn.utils._set_output._SetOutputMixin.set_output:6: WARNING: more than one target 
found for 'any' cross-reference 'transform': could be
:py:meth:`pkg.Class1.transform` or 
:py:meth:`pkg.Class2.transform` or 
:py:meth:`pkg.mod.Class3.transform` or 
...

Here, all classes subclass sklearn.base.BaseEstimator and sklearn.base.TransformerMixin, which subclasses sklearn.utils._set_output._SetOutputMixin, whose set_output docstring includes the line

Configure output of `transform` and `fit_transform`

It appears that, because _SetOutputMixin is a mixin and has no transform method to link, this would be ambiguous. Yet Class1.set_output has a reference to Class1.transform`, etc, so its making the correct choice.

This is sphinx 8.1.3, not sphinx 8.2.3. I've noticed that the warning goes away in 8.2.3, but not all extensions we use are compatible with 8.2. It appears from this pr that there is no way of suppressing the warning prior to 8.2 (and I've tried with suppress_warnings and show_warning_types).

Since I can't change the 3rd party docstring (not sure I'd even know what to do in this case), is there a way to correct my package's docstring/inheritance to get rid of this error?

python scikit-learn python-sphinx