Intersphinx Mapping link not working with Plotly objects in signature about sphinx

[electric-coder]

The example you're showing is convoluted to say the least, i.e:

    Keyword Args:
        figure (:py:class:`Figure<plotly.graph_objects.Figure>`):
            The figure that draws contents of the scene.

Here, unless I'm mistaken, you're not "declaring" but inserting an explicit cross-reference in the type field. So Figure is your shortened alias for the link to plotly.graph_objects.Figure. (Needless to say for this to work properly you'll need intersphinx correctly setup for plotly).

The usual way of writing these links would be using the shortened ~ syntax, so you'd write ~plotly.graph_objects.Figure or just .Figure - note that on occasion Sphinx won't be able to resolve all links depending on the context and if the referenced class is affected by one of the bugs listed in #11991

The surest way to get this working, currently, is to explicitly write the return type into the docstring (notice that the one field/link you're complaining about is the one you're not writing out explicitly but instead expect Sphinx to extract&link automatically from the signature, so instead of:

    Return:
        The canvas or figure that is reused for this context.

try writing the type explicitly:

    Returns:
        Figure: Description of return value

or with the path as specified in the docs in the link until you find what works:

    Returns:
        ~.plotly.graph_objects.Figure: Description of return value

[jeertmans]

The example you're showing is convoluted to say the least, i.e:

    Keyword Args:
        figure (:py:class:`Figure<plotly.graph_objects.Figure>`):
            The figure that draws contents of the scene.

Here, unless I'm mistaken, you're not "declaring" but inserting an explicit cross-reference in the type field. So Figure is your shortened alias for the link to plotly.graph_objects.Figure. (Needless to say for this to work properly you'll need intersphinx correctly setup for plotly).

The usual way of writing these links would be using the shortened ~ syntax, so you'd write ~plotly.graph_objects.Figure or just .Figure - note that on occasion Sphinx won't be able to resolve all links depending on the context and if the referenced class is affected by one of the bugs listed in #11991

The surest way to get this working, currently, is to explicitly write the return type into the docstring (notice that the one field/link you're complaining about is the one you're not writing out explicitly but instead expect Sphinx to extract&link automatically from the signature, so instead of:

    Return:
        The canvas or figure that is reused for this context.

try writing the type explicitly:

    Returns:
        Figure: Description of return value

or with the path as specified in the docs in the link until you find what works:

    Returns:
        ~.plotly.graph_objects.Figure: Description of return value

I think you misunderstood my problem.

This example you cite works properly (i.e., where I put figure (:py:class:Figure<plotly.graph_objects.Figure>)), because the link is actually clickable.

The issue comes from the return type, that is obtained from the type signature (using "sphinx_autodoc_typehints" extension).

For all return values, I get a clickable link, except from Figure objects from Plotly (in the code, from plotly.graph_objects import Figure.).

[electric-coder]

The issue comes from ... (using "sphinx_autodoc_typehints" extension).

Exactly! You should post this issue at their repository since it's their extension that proposes to extract the type from the signature.

I think you misunderstood my problem.

I understood it perfectly fine!

[jeertmans]

Ok, will do that then :-)