feat(interlinks): support rst syntax

Author: machow

interlinks/_extension.yml renamed to _extension.yml

@@ -4,4 +4,4 @@ version: 1.0.0
 quarto-required: ">=1.2.0"
 contributes:
   filters:
-    - interlinks.lua
+    - interlinks/interlinks.py

interlinks/example.qmd

@@ -18,13 +18,12 @@ interlinks:
 
 ## Testing
 
-Tilde means don't display module:
 
-* :ref:`vetiver.SKLearnHandler`
-* :ref:`~vetiver.SKLearnHandler`
-* :ref:`siuba.dply.verbs.mutate`
-  - TODO: should be able to use `domain:...` to use a specific inventory file.
-* :refzzz:`some explanation <mutate>`
-  - TODO: this syntax let's you change the text of the link.
-* [some explanation](`vetiver.SKLearnHandler`)
-* [](`vetiver.SKLearnHandler`)
+| style | syntax | output |
+| ----- | ------ | ------ |
+| md custom text  | `[some explanation](`vetiver.SKLearnHandler`)` | [some explanation](`vetiver.SKLearnHandler`) |
+| md blank text   | `[](`vetiver.SKLearnHandler`)` | [](`vetiver.SKLearnHandler`) |
+| md blank text (~shortened)| `[](`~vetiver.SKLearnHandler`)` | [](`~vetiver.SKLearnHandler`) |
+| rst custom text | `` :ref:`some explanation <vetiver.SKLearnHandler>` `` | :ref:`some explanation <vetiver.SKLearnHandler>` |
+| rst blank text  | `` :ref:`vetiver.SKLearnHandler` `` | :ref:`vetiver.SKLearnHandler` |
+| rst blank text (~shortened) | `` :ref:`~vetiver.SKLearnHandler` `` | :ref:`~vetiver.SKLearnHandler` |

interlinks/interlinks.py

@@ -7,7 +7,32 @@
 inventory = {}
 
 
-def ref_to_anchor(ref, text):
+def load_mock_inventory(items: "dict[str, str]"):
+    for k, v in items.items():
+        inventory[k] = v
+
+
+def ref_to_anchor(ref: str, text: "str | pf.ListContainer | None"):
+    """Return a Link element based on ref in interlink format
+
+    Parameters
+    ----------
+    ref:
+        The interlink reference (e.g. "my_module.my_function").
+    text:
+        The text to be displayed for the link.
+
+    Examples
+    --------
+
+    >>> url = "https://example.org/functools.partial.html"
+    >>> load_mock_inventory({"functools.partial": {"full_uri": url, "name": "functools.partial"}})
+    >>> ref_to_anchor("functools.partial")
+    Link(Str(functools.partial); url='https://example.org/functools.partial.html')
+
+    >>> ref_to_anchor("~functools.partial")
+    Link(Str(partial); url='https://example.org/functools.partial.html')
+    """
     # TODO: for now we just mutate el
     is_shortened = ref.startswith("~")
 
@@ -28,11 +53,41 @@ def ref_to_anchor(ref, text):
     else:
         # when the element is an Link, content is a ListContainer, but it has to be
         # *splatted back into Link?
-        return pf.Link(*text, url=dst_url)
+        if isinstance(text, pf.ListContainer):
+            return pf.Link(*text, url=dst_url)
+        elif isinstance(text, str):
+            return pf.Link(pf.Str(text), url=dst_url)
+        else:
+            raise TypeError(f"Unsupported type: {type(text)}")
 
     return pf.Link(name, url=dst_url)
 
 
+def parse_rst_style_ref(full_text):
+    """
+    Returns
+    -------
+    tuple
+        The parsed title (None if no title specified), and corresponding reference.
+    """
+
+    import re
+
+    pf.debug(full_text)
+
+    m = re.match(r"(?P<text>.+?)\<(?P<ref>[a-zA-Z\.\-: ]+)\>", full_text)
+    if m is None:
+        # TODO: print a warning or something
+        return full_text, None
+
+    text, ref = m.groups()
+
+    return ref, text
+
+
+# Visitor ================================================================================
+
+
 @dispatch
 def visit(el, doc):
     return el
@@ -63,12 +118,14 @@ def visit(el: pf.Doc, doc):
 
 
 @dispatch
-def visit(el: pf.Code, doc):
-    # TODO: also need to remove ref. Should handle in parent?
-    left_el = el.prev
+def visit(el: pf.Plain, doc):
+    cont = el.content
+    if len(cont) == 2 and cont[0] == pf.Str(":ref:") and isinstance(cont[1], pf.Code):
+        _, code = el.content
+
+        ref, title = parse_rst_style_ref(code.text)
 
-    if left_el == pf.Str(":ref:"):
-        return ref_to_anchor(el.text, None)
+        return pf.Plain(ref_to_anchor(ref, title))
 
     return el