Implement cross-referencing

[wenkokke]

Currently, every Talon object which is analysed by the Talon domain is given a unique name, but I've not had the opportunity to implement the ability to resolve cross-references yet.

This is especially important since it would enable us, for example, to populate the documentation for a tag with the contexts and Talon files that implement it (see #11).

For an example, see add_target_and_index and resolve_xref in Developing a “recipe” extension.

[Nova38]

On the example is stores all of the indexes, directives, and the domain all in the same file. The current setup of the repo has the directives in /src/talondoc/sphinx/directives and the domain in the parent folder. Would it be better to add a second child folder to the sphinx directory for the indexes or should they be collocated with their respective directives?

[wenkokke]

I'm happy for you to put them under directives.

[Nova38]

Two quick questions:

1. Where in the domain is the objects data stored?
   • In the example the function self.get_objects() that is used in the resolve_xref() returns the data stored in the self.data, and that data is populated in an add_recipe function. I don't see an equivalent set of functions defined in the domain class but i did see it has a registry variable that looks like the anylisis folder build the data from. Should I pull the objects from the regisry?
2. How do I compute the unique name for the objects in the directive's add_target_and_index function?
   • In the handle_signiture function for hte objectdescriptions it uses the self.talon.registry.lookup_default function to return an object called default and then runs the function desc_qualname and passes in its name attribute and a signode.

[wenkokke]

Where in the domain is the objects data stored?

In the example the function self.get_objects() that is used in the resolve_xref() returns the data stored in the self.data, and that data is populated in an add_recipe function. I don't see an equivalent set of functions defined in the domain class but i did see it has a registry variable that looks like the anylisis folder build the data from. Should I pull the objects from the regisry?

You should use the typed API to grab objects from the registry: https://github.com/wenkokke/talondoc/blob/71d88e22b83713ef417e03417085c1c29a32a180/src/talondoc/analysis/registry/__init__.py#L290-L315

This resolves a type and a name to an object or object group. You have to pass the type of the object as the first argument and the name as the second.

[wenkokke]

How do I compute the unique name for the objects in the directive's add_target_and_index function?

In the handle_signiture function for hte objectdescriptions it uses the self.talon.registry.lookup_default function to return an object called default and then runs the function desc_qualname and passes in its name attribute and a signode.

I'd suggest using a combination of the name and the object's class name, e.g., action:user.auto_insert. That's enough to reconstruct the class and name, which lets you use the lookup function.

Something like...

def xref(data: Data):
  return f"{data.__class__.__name__.lower()}:{data.name}"

Probably makes sense to add as an @property to the Data class.