[autodoc] undefined reference for aliased type annotation in the class constructor

[danieleades]

Describe the bug

i'm seeing a build error because rx.PyDiGraph cannot be found

How to Reproduce

see https://github.com/danieleades/sphinx-graph/actions/runs/8684807082/job/23813057033?pr=143

Environment Information

python 3.12, sphinx 7.2.6

Sphinx extensions

No response

Additional context

No response

[picnixz]

FWICT, it's because we don't have a reference to rx.PyDiGraph present in the signature of your state's constructor.

[danieleades]

FWICT, it's because we don't have a reference to rx.PyDiGraph present in the signature of your state's constructor.

i'm not sure i understand what you mean.

Here's the constructor:

class State:
    """State object for Sphinx Graph vertices."""

    def __init__(
        self,
        vertices: dict[str, tuple[int, Info]],
        graph: rx.PyDiGraph[str, str | None],
    ) -> None:
        """Create a new state object."""
        self._vertices = vertices
        self._graph = graph

rx.PyDiGraph is in the function signature, no?

[picnixz]

Yes, but that's the issue with the "target not found" of :py:class: I think.

The reason why it says "docstring of State" is because we generate the "docstring" from the init method + its signature but its signature contains some rx.PyDiGraph so it's as if you had an RST with :type graph: rx.PyDiGraph which then uses a py:class for a reference.

[danieleades]

Yes, but that's the issue with the "target not found" of :py:class: I think.

The reason why it says "docstring of State" is because we generate the "docstring" from the init method + its signature but its signature contains some rx.PyDiGraph so it's as if you had an RST with :type graph: rx.PyDiGraph which then uses a py:class for a reference.

sorry, i still don't understand. Can you explain like i'm 5? ;)
or better yet- how can i resolve this warning?

[danieleades]

ultimately this is in service to this PR (that i could also use your help on @picnixz!) - danieleades/sphinx-graph#142

[picnixz]

sorry, i still don't understand. Can you explain like i'm 5? ;)

I assume you are using autodoc. So the documenter generates an (temporary) RST document that would look like:

.. py:class:: State
  
   Blablabla

   :type graph: rx.PyDiGraph[str, str | None]

Then, we want to "highlight" rx.PyDiGraph so that you can click on it on the rendered docs (hence the py:class:). Now, I'm not entirely sure that the issue is really at that stage or not.

or better yet- how can i resolve this warning?

Go in verbose mode and check the autodoc output (the log starts with "[autodoc] output"). Check what is really being changed so that I can tell you the real issue.

Also, could you tell me if I could have perhaps introduced an error in #12256 ? (i.e., could you bissect the bad commit if possible?)

ultimately this is in service to this PR

Sorry I don't have much time for that for the next weeks.

[danieleades]

here is the verbose output from the logs:

[autodoc] => <class 'sphinx_graph.vertex.state.State'>
[app] emitting event: 'autodoc-before-process-signature'(<function State.__init__ at 0x7f4bdfc45e40>, True)
[app] emitting event: 'autodoc-process-signature'('class', 'sphinx_graph.vertex.State', <class 'sphinx_graph.vertex.state.State'>, {'members': []}, '
[app] emitting event: 'autodoc-process-docstring'('class', 'sphinx_graph.vertex.State', <class 'sphinx_graph.vertex.state.State'>, {'members': []}, [
[app] emitting event: 'autodoc-process-docstring'('class', 'sphinx_graph.vertex.State', <class 'sphinx_graph.vertex.state.State'>, {'members': []}, [
[autodoc] output:

.. py:class:: State(vertices: dict[str, tuple[int, Info]], graph: rx.PyDiGraph[str, str | None])
   :module: sphinx_graph.vertex
   :canonical: sphinx_graph.vertex.state.State

   State object for Sphinx Graph vertices.

   Create a new state object.

[app] emitting event: 'object-description-transform'('py', 'class', <desc_content: <paragraph...><paragraph...>>)
[app] emitting event: 'doctree-read'(<document: <section "sphinx_graph.vertex.state"...>>,)
[app] emitting event: 'viewcode-follow-imported'('sphinx_graph.vertex', 'State')
[app] emitting event: 'viewcode-find-source'('sphinx_graph.vertex.state',)

[picnixz]

Ah! actually, I just remembered but... did you include the intersphinx mappings for your rx package? It might be the reason why we cannot find the reference if it's not part of your project.

[danieleades]

Ah! actually, I just remembered but... did you include the intersphinx mappings for your rx package? It might be the reason why we cannot find the reference if it's not part of your project.

the rustworkx package is installed in the build environment, and imported like so-

import rustworkx as rx

what additional config is needed to make this discoverable?

[picnixz]

Err, either intersphinx or autodoc_type_aliases maybe (honestly, it's one of the annoying things in autodoc: you don't know why something is missing a reference or not).

There are various reasons I can think of why it fails:

• It's imported as rx.
• There is some from __future__ import annotations.
• There is no intersphinx mapping for 'rx'.
• I made a mistake in Improve sphinx.util.inspect [part 1] #12256 (unless you are not using HEAD)

And you can fix it by:

• Adding a nitpick_ignore entry (fastest way to do it).
• Perhaps changing the import to from rustworkx import PyDiGraph
• Perhaps adding autodoc_type_aliases.

Sorry, but I won't have more time today :(

[danieleades]

Perhaps changing the import to from rustworkx import PyDiGraph

this doesn't help, unfortunately

There is some from future import annotations

yes, i am using this statement