How can I get the target URI of a standalone ref:foo reference?

[lelit]

I'm writing a Sphinx extension that implements a directive able to render a d2 diagram and insert the resulting PNG or SVG into a document, very similar to what ext/graphviz.py does.

It is already good enough for my needs, but I'd like to exploit the link feature of a d2 node so that I can use :ref: to set the target to an arbitrary Sphinx reference.

In other words, instead of writing this:

.. d2::
   Organization: {
     shape: class
     link: /uri/pointing/to/the/python/Organization/class.html
     name: str
   }

I would prefer being able to say:

.. d2::
   Organization: {
     shape: class
     link: :py:class:`Organization`
     name: str
   }

Given that the actual rendering of the diagram (that is, the execution of d2 to generate the SVG) is already happening when the whole documentation has been built, I think it should be a matter of manually pre-processing the diagram's code searching for those link: XXX options and, when XXX is a reST role, process it in the current context to compute the final URI and replace XXX with that.

I spent a few hours searching and trying, but I could not figure out a way to do that at render time.

Can you shed some light on how I could do that?

Thanks in advance for any hint!

[AA-Turner]

You will need to do this in the reading phase (in your directive). Once you've extracted the reST to process, call self.parse_inline and use the URI of the result node.

A

[lelit]

Thanks, I tried that, but doing it in the reading phase, I failed to see how I can resolve that to the final target URI, because at that time the location of the Python class could be not known yet... what am I missing?

[AA-Turner]

Oh, if you're getting a pending_xref then I would store that somewhere (perhaps as a child of your custom node) and then let the ReferencesResolver handle them.

A

[lelit]

Yay, I think I got it!

Basically

• in the reading phase, I collect those links, parse them and add resulting nodes to the d2node produced by the directive.
• later, when rendering the diagram, I first replace all those links with subnodes refuri/refid

Thanks a lot!

[lelit]

This commit implements the desired facility, but I need to study further to understand how to treat a local reference (that is, when the reference has just a refid) here.

The case is this one, where the reference is within the very same document containing the diagram: when I am about replacing the original ":ref:d2", the resolved reference contains a refid set to d2. I need to substitute the original with something like /index.html#d2, not just #d2 because the latter one will be relative to the embedded SVG object, and obviously wrong. I failed to find a way to determine that index.html, that is the base URI of the containing document page. Can you point me in the right direction?

Thanks again!

[lelit]

Later I will try to see whether the fix_svg_relative_paths() function does right that...

[lelit]

For the record, no, that is unrelated, but it gave me an hint about using env.path2doc(self.document["source"]).
All is good (for now): https://pypi.org/project/metapensiero.sphinx.d2/

[AA-Turner]

Fab, do let me know if there are improvements we can make here in Sphinx.

A

[AA-Turner]

Entirely off topic, but out of interest are you the same Lele that contributed Italian translations etc to Docutils (e.g. at r2533)? We're (slowly) working on a migration to Git, so matching people up is useful!

Best,
Adam

[lelit]

Yes I am!