feat: interlinks in own module, testing spec

Author: machow

quartodoc/interlinks.py

@@ -4,6 +4,7 @@
 import itertools
 import json
 import warnings
+import yaml
 
 from pydantic import BaseModel, Field
 from dataclasses import dataclass
@@ -29,10 +30,10 @@ class InvLookupError(Exception):
 
 def get_path_to_root():
     # In lua filters you can use quarto.project.offset
-    return os.environ[ENV_PROJECT_ROOT]
+    return Path(os.environ[ENV_PROJECT_ROOT])
 
 
-def parse_rst_style_ref(full_text):
+def parse_rst_style_ref(full_text: str):
     """
     Returns
     -------
@@ -52,6 +53,19 @@ def parse_rst_style_ref(full_text):
     return ref, text
 
 
+def parse_md_style_link(full_text: str):
+    import re
+
+    m = re.match(r"\[(?P<text>.*?)\]\((?P<ref>.*?)\)", full_text)
+
+    if m is None:
+        raise Exception()
+
+    text, ref = m.groups()
+
+    return ref, text
+
+
 # Dataclasses representing pandoc elements ------------------------------------
 # These classes are used to help indicate what elements the Interlinks class
 # would return in a pandoc filter.
@@ -60,15 +74,15 @@ def parse_rst_style_ref(full_text):
 class Link(BaseModel):
     """Indicates a pandoc Link element."""
 
-    kind: Literal["link"] = "link"
+    kind: Literal["Link"] = "Link"
     content: str
     url: str
 
 
 class Code(BaseModel):
     """Indicates a pandoc Code element."""
 
-    kind: Literal["code"] = "code"
+    kind: Literal["Code"] = "Code"
     content: str
 
 
@@ -79,11 +93,12 @@ class Unchanged(BaseModel):
     return the original content element.
     """
 
-    kind: Literal["unchanged"] = "unchanged"
+    kind: Literal["Unchanged"] = "Unchanged"
     content: str
 
 
 class TestSpecEntry(BaseModel):
+    input: str
     output_text: Optional[str] = None
     output_link: Optional[str] = None
     output_element: Optional[
@@ -93,6 +108,10 @@ class TestSpecEntry(BaseModel):
     warning: Optional[str] = None
 
 
+class TestSpec(BaseModel):
+    __root__: list[TestSpecEntry]
+
+
 # Reference syntax ------------------------------------------------------------
 # note that the classes above were made pydantic models so we could serialize
 # them from json. We could make these ones pydantic too, but there is not a
@@ -280,16 +299,16 @@ def ref_to_anchor(self, ref: str | Ref, text: "str | None"):
         is_shortened = ref.target.startswith("~")
 
         entry = self.lookup_reference(ref)
-        dst_url = entry["full_uri"]
+        dst_url = entry.full_uri
 
         if not text:
-            name = entry["name"] if entry["dispname"] == "-" else entry["dispname"]
+            name = entry.name if entry.dispname == "-" else entry.dispname
             if is_shortened:
                 # shorten names from module.sub_module.func_name -> func_name
                 name = name.split(".")[-1]
-            return Link(name, url=dst_url)
+            return Link(content=name, url=dst_url)
 
-        return Link(text, url=dst_url)
+        return Link(content=text, url=dst_url)
 
     def pandoc_ref_to_anchor(self, ref: str, text: str) -> Link | Code | Unchanged:
         """Convert a ref to a Link, with special handling for pandoc filters.
@@ -299,27 +318,33 @@ def pandoc_ref_to_anchor(self, ref: str, text: str) -> Link | Code | Unchanged:
         non-ref urls unchanged.
         """
 
-        if (ref.startswith("%60") or ref.startswith(":")) and ref.endswith("%60"):
+        # detect what *might* be an interlink. note that we don't validate
+        # that it has a closing `, to allow a RefSyntaxError to bubble up.
+        if ref.startswith("%60") or ref.startswith(":"):
             # Get URL ----
             try:
                 return self.ref_to_anchor(ref.replace("%60", "`"), text)
             except InvLookupError as e:
-                warnings.warn(warnings.warn(str(e)))
+                warnings.warn(f"{e.__class__.__name__}: {e}")
                 if text:
                     # Assuming content is a ListContainer(Str(...))
                     body = text
                 else:
-                    body = ref.replace("%60", "")
-                return Code(body)
+                    body = ref.replace("%60", "`")
+                return Code(content=body)
 
-        return Unchanged(ref)
+        return Unchanged(content=ref)
 
     @staticmethod
     def _filter_by_field(items, field_name: str, value: "str | None" = None):
         if value is None:
             return items
 
-        return (item for item in items if item[field_name] == value)
+        # TODO: Ref uses invname, while EnhancedItem uses inv_name
+        if field_name == "invname":
+            field_name = "inv_name"
+
+        return (item for item in items if getattr(item, field_name) == value)
 
     @classmethod
     def from_items(cls, items: "list[EnhancedItem]"):
@@ -331,9 +356,16 @@ def from_items(cls, items: "list[EnhancedItem]"):
         return invs
 
     @classmethod
-    def from_quarto_config(cls, cfg: dict):
+    def from_quarto_config(cls, cfg: str | dict, root_dir: str | None = None):
+
+        if isinstance(cfg, str):
+            if root_dir is None:
+                root_dir = Path(cfg).parent
+
+            cfg = yaml.safe_load(open(cfg))
+
         invs = cls()
-        p_root = get_path_to_root()
+        p_root = get_path_to_root() if root_dir is None else Path(root_dir)
 
         interlinks = cfg["interlinks"]
         sources = interlinks["sources"]
@@ -354,3 +386,5 @@ def from_quarto_config(cls, cfg: dict):
             json_data = json.load(open(inv_path))
 
             invs.load_inventory(json_data, url=cfg["url"], invname=doc_name)
+
+        return invs

quartodoc/tests/example_interlinks/_quarto.yml

@@ -8,7 +8,8 @@ filters:
 
 interlinks:
   sources:
-    numpy:
-      url: https://numpy.org/doc/stable/
-    python:
-      url: https://docs.python.org/3/
+    other:
+      # note that url is usually the http address it is
+      # fetched from, but we generate the inventory for
+      # this source manually.
+      url: "other+"

quartodoc/tests/example_interlinks/spec.yml

@@ -10,7 +10,7 @@
   output_text: quartodoc.MdRenderer
 
 # can look up function
-- input: "[](`quartodoc.Mdrenderer.render`)"
+- input: "[](`quartodoc.MdRenderer.render`)"
   output_link: /api/MdRenderer.html#quartodoc.MdRenderer.render
   output_text: quartodoc.MdRenderer.render
 

quartodoc/tests/test_interlinks.py

@@ -1,11 +1,37 @@
+import contextlib
 import pytest
+import yaml
 
-from quartodoc.inventory import Ref
+from quartodoc import interlinks
+from quartodoc.interlinks import (
+    Inventories,
+    Ref,
+    TestSpec,
+    TestSpecEntry,
+    parse_md_style_link,
+    Link,
+)
+from importlib_resources import files
+
+# load test spec at import time, so that we can feed each spec entry
+# as an individual test case using parametrize
+_raw = yaml.safe_load(open("quartodoc/tests/example_interlinks/spec.yml"))
+spec = TestSpec(__root__=_raw).__root__
 
 
 @pytest.fixture
-def spec():
-    pass
+def invs():
+    invs = Inventories.from_quarto_config(
+        str(files("quartodoc") / "tests/example_interlinks/_quarto.yml")
+    )
+
+    return invs
+
+
+# def test_inventories_from_config():
+#     invs = Inventories.from_quarto_config(
+#         str(files("quartodoc") / "tests/example_interlinks/_quarto.yml")
+#     )
 
 
 @pytest.mark.parametrize(
@@ -25,3 +51,43 @@ def test_ref_from_string(raw, dst):
     src = Ref.from_string(raw)
 
     assert src == dst
+
+
+@pytest.mark.parametrize("entry", spec)
+def test_spec_entry(invs: Inventories, entry: TestSpecEntry):
+
+    ref_str, text = parse_md_style_link(entry.input)
+    ref_str = ref_str.replace("`", "%60")  # weird, but matches pandoc
+
+    # set up error and warning contexts ----
+    # pytest uses context managers to check warnings and errors
+    # so we either create the relevant cm or uses a no-op cm
+    if entry.error:
+        ctx_err = pytest.raises(getattr(interlinks, entry.error))
+    else:
+        ctx_err = contextlib.nullcontext()
+
+    if entry.warning:
+        ctx_warn = pytest.warns(UserWarning, match=entry.warning)
+    else:
+        ctx_warn = contextlib.nullcontext()
+
+    # fetch link ----
+    with ctx_warn as rec_warn, ctx_err as rec_err:  # noqa
+        el = invs.pandoc_ref_to_anchor(ref_str, text)
+
+    if entry.error:
+        # return on errors, since no result produced
+        return
+
+    # output assertions ----
+    if entry.output_link is not None or entry.output_text is not None:
+        assert isinstance(el, Link)
+
+        if entry.output_link:
+            assert entry.output_link == el.url
+
+        if entry.output_text:
+            assert entry.output_text == el.content
+    elif entry.output_element:
+        assert el == entry.output_element