Link to plotly.graph_objects.Figure with intersphinx?

Question

I have set up plotly with intershinx in my conf.py like this:

intersphinx_mapping = {
    ...
    'plotly': ('https://plotly.com/python-api-reference/', None),
}

Now I try to have my typehints automatically parsed with sphinx autodoc and converted into proper documentation. Intersphinx loads the inventory and it also included the following line (checked with python -m sphinx.ext.intersphinx https://plotly.com/python-api-reference/objects.inv):

 plotly.graph_objects.Figure              generated/plotly.graph_objects.html#plotly.graph_objects.Figure

However, in my documentation, it only says "Figure" without creating the link to plotly.graph_objects.Figure in their docs. But why and how can I debug this?

For context - I have already successfully included the Python standard libs, numpy and matplotlib in my documentation with intersphinx. Moreover, there is no warning while running the code.

EDIT:

@steve-piercy: Here is the shortened version of the autodocumented method. I just use the Sphinx directive autoclass for its documentation. The docstrings are written in Google Doc style and translated by Napoleon. It has worked fine for all other instances.

import plotly.graph_objects

class A:
    def b(self) -> plotly.graph_objects.Figure:
        """
        Returns:
            The plotly figure.
        """
        ...
        fig = plotly.graph_objects.Figure(
            data=[
                plotly.graph_objects.Sankey(
                    arrangement='perpendicular',
                    node=dict(
                        ...
                    ),
                    link=dict(
                        ...
                    )
                )
            ]
        )

        return fig

By the way, I tried both plotly.graph_objects.Figure and plotly.graph_objs.Figure. One issue I have realized is that the actual type does not reside in that package. Instead, there are lots of relative imports from subpackages with leading underscores. This has slightly confused my IDE PyCharm. However, as I am using the full name, I was hoping that just the text is used.

In the past, I had a somehow similar issue with numpy.typing. I just imported numpy and everything worked fine except the Intersphinx linking. In that case, explicitely importing the subpackage numpy.typing solved it for me. In this case, however, I even use the Figure class to create the instance. So it cannot be an issue with a wrong import.

EDIT 2: This is by the way what I mean with an unclickable link. The return type is correctly displayed, it just leads to nowhere. Intersphinx could have issued a warning in that case, couldn't it?

Answer 1

Summarizing my solution to this, adapted from this discussion and the solution implemented by jeertmans in his conf.py file linked in that discussion:

I resolved this issue by adding the following to my conf.py file:

from docutils import nodes
from sphinx.addnodes import pending_xref
from sphinx.application import Sphinx
from sphinx.environment import BuildEnvironment
from sphinx.ext.intersphinx import missing_reference

intersphinx_mapping = {
    "plotly": ("https://plotly.com/python-api-reference/", None),
}


def fix_reference(
    app: Sphinx, env: BuildEnvironment, node: pending_xref, contnode: nodes.TextElement
) -> nodes.reference | None:
    """
    Fix some intersphinx references that are broken.
    """
    if node["refdomain"] == "py":
        # strange imports in plotly require a hardcoded redirect
        if node["reftarget"] == "plotly.graph_objs._figure.Figure":
            node["reftarget"] = "plotly.graph_objects.Figure"
        return missing_reference(app, env, node, contnode)

    return None


def setup(app: Sphinx) -> None:
    """
    Force sphinx to fix additional things on setup.
    """
    app.connect("missing-reference", fix_reference)

One other relevant tip I picked up from the discussion I linked above, if you build your docs with the -n flag (nitpicky mode), then if you build the docs before implementing the fix, you should see warnings for all the plotly figure references. After the fix, those warnings should disappear.