Within a custom Sphinx domain, I'd like to create a reference to another node in a different domain. For example:
.. py:class:: foo.bar
Lorem ipsum.
.. example:directive:: baz -> foo.bar
Sit amet, sit.
My example:directive:: says that my "method" baz returns something of type foo.bar, which is a Python class. So I'd like to cross-reference that to the other py:class:: foo.bar description.
from sphinx.directives import ObjectDescription
class ExampleDescription(ObjectDescription):
def handle_signature(self, sig, signode):
# lots of parsing and node creation here
# parsed_annotation = "foo.bar"
signode += addnodes.desc_returns(parsed_annotation, parsed_annotation)
Within my custom domain I'm parsing my directives and building the elements and it's all fine, even cross-referencing within my example domain works just fine by subclassing the sphinx.domains.Domain:resolve_xref method. I'm just unsure how I would programmatically insert a node in my handle_signature method which is later resolved to a node in another domain. Would I somehow have to instantiate a sphinx.domains.python.PyXRefRole?
The expected result in HTML would be something like:
<dl>
<dt>
<code>baz</code>
→
<a href="example.html#py.class.foo.bar">
<code>foo.bar</code>
</a>
</dt>
</dl>