add info on cross-referencing to the docs

[danieleades]

add support and documentation for creating cross references to vertices

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (6548b9d) to head (8420d37).

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #142   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           20        20           
  Lines          508       508           
=========================================
  Hits           508       508           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[danieleades]

@picnixz i was hoping to ask you another favour here.

cross-referencing as described in this PR doesn't actually work. Can you provide any advice on what it would take to make this work correctly?

i'm agnostic to the syntax at this stage. I have considered-

• :ref:'node-001'
• :ref:'vertex:node-001'
• :vertex:'node-001'

[danieleades]

@picnixz i did some more digging into this, and i'm a little confused.

• the custom directives create a target_node in the document when they are first processed
• given the reference target exists why can't i reference it using a standard :ref: directive?
• i've tried explicitly registering the target node with document.note_explicit_target but this doesn't make any difference. What is this for?

my fallback option is to create a custom vertexref role and manually resolve the references, but it seems strange I can't leverage the existing reference mechanism.