feat: interlinks autolink (#395)

* chore: prettify interlinks filter

* draft: autolinks

* test: add autolink test qmd

* feat: interlinks autolink and aliases

* feat: interlinks auto qd-no-link class

* docs: add autolinks to guide

* fix: filter handles pandoc inlines better

* feat(autolink): alias lists and shortening syntax

* docs: autolink shortening and aliases

* fix(autolink): remove shortening syntax from unmatched

* docs: unmatched autolink example

* feat: add ~~. autolink syntax

* dev: autolinks do not log debug messages

Author: machow

_extensions/interlinks/interlinks.lua

@@ -1,3 +1,13 @@
+local inventory = {} -- sphinx inventories
+local autolink       -- set in Meta
+local autolink_ignore_token = "qd-no-link"
+
+local function _debug_log(text, debug)
+    if debug then
+        quarto.log.warning(text)
+    end
+end
+
 local function read_inv_text(filename)
     -- read file
     local file = io.open(filename, "r")
@@ -11,16 +21,16 @@ local function read_inv_text(filename)
     local project = str:match("# Project: (%S+)")
     local version = str:match("# Version: (%S+)")
 
-    local data = {project = project, version = version, items = {}}
+    local data = { project = project, version = version, items = {} }
 
     local ptn_data =
         "^" ..
-        "(.-)%s+" ..        -- name
-        "([%S:]-):" ..      -- domain
-        "([%S]+)%s+" ..     -- role
-        "(%-?%d+)%s+" ..     -- priority
-        "(%S*)%s+" ..       -- uri
-        "(.-)\r?$"         -- dispname
+        "(.-)%s+" ..     -- name
+        "([%S:]-):" ..   -- domain
+        "([%S]+)%s+" ..  -- role
+        "(%-?%d+)%s+" .. -- priority
+        "(%S*)%s+" ..    -- uri
+        "(.-)\r?$"       -- dispname
 
 
     -- Iterate through each line in the file content
@@ -48,7 +58,6 @@ local function read_inv_text(filename)
 end
 
 local function read_json(filename)
-
     local file = io.open(filename, "r")
     if file == nil then
         return nil
@@ -66,18 +75,15 @@ local function read_inv_text_or_json(base_name)
         -- TODO: refactors so we don't just close the file immediately
         io.close(file)
         json = read_inv_text(base_name .. ".txt")
-
     else
         json = read_json(base_name .. ".json")
     end
 
     return json
 end
 
-local inventory = {}
-
-local function lookup(search_object)
-
+-- each inventory has entries: project, version, items
+local function lookup(search_object, debug)
     local results = {}
     for _, inv in ipairs(inventory) do
         for _, item in ipairs(inv.items) do
@@ -98,7 +104,7 @@ local function lookup(search_object)
                 goto continue
             else
                 if search_object.domain or item.domain == "py" then
-                  table.insert(results, item)
+                    table.insert(results, item)
                 end
 
                 goto continue
@@ -112,23 +118,24 @@ local function lookup(search_object)
         return results[1]
     end
     if #results > 1 then
-        quarto.log.warning("Found multiple matches for " .. search_object.name .. ", using the first match.")
+        _debug_log("Found multiple matches for " .. search_object.name .. ", using the first match.", debug)
         return results[1]
     end
     if #results == 0 then
-        quarto.log.warning("Found no matches for object:\n", search_object)
+        _debug_log("Found no matches for object:\n", debug)
+        _debug_log(search_object, debug)
     end
 
     return nil
 end
 
-local function mysplit (inputstr, sep)
+local function mysplit(inputstr, sep)
     if sep == nil then
-            sep = "%s"
+        sep = "%s"
     end
-    local t={}
-    for str in string.gmatch(inputstr, "([^"..sep.."]+)") do
-            table.insert(t, str)
+    local t = {}
+    for str in string.gmatch(inputstr, "([^" .. sep .. "]+)") do
+        table.insert(t, str)
     end
     return t
 end
@@ -140,7 +147,84 @@ local function normalize_role(role)
     return role
 end
 
-local function build_search_object(str)
+local function copy_replace(original, key, new_value)
+    -- First create a copy of the table
+    local copy = {}
+    for k, v in pairs(original) do
+        copy[k] = v
+    end
+
+    -- Then replace the specific value
+    copy[key] = new_value
+
+    return copy
+end
+
+local function contains(list, value)
+    -- check if list contains a value
+    for i, v in ipairs(list) do
+        if v == value then
+            return true
+        end
+    end
+    return false
+end
+
+local function flatten_alias_list(list)
+    -- flatten a list of lists into a single list,
+    -- where each entry has the form {key, subvalue}}
+    -- e.g.
+    --   input: {key1 = {subval1, subval2}, key2 = subval3}
+    --   output: {{key1, subval1}, {key1, subval2}, {key2, subval3}}
+    local flat = {}
+    for key, sublist in pairs(list) do
+        if type(sublist) == "table" then
+            for _, subvalue in ipairs(sublist) do
+                table.insert(flat, { key, subvalue })
+            end
+        else
+            table.insert(flat, { key, sublist })
+        end
+    end
+    return flat
+end
+
+local function prepend_aliases(flat_aliases)
+    -- if str up to first period starts with an alias, then
+    -- replace it with the full name.
+    -- For example, suppose we have the alias quartodoc -> qd
+    -- e.g. qd.Auto -> quartodoc.Auto
+    -- e.g. qda.Auto -> qda.Auto
+
+    local new_inv = {}
+    new_inv["project"] = "aliases"
+    new_inv["version"] = "0.0.9999" -- I have not begun to think about version...
+    new_inv["items"] = {}
+
+    for _, name_pair in pairs(flat_aliases) do
+        local full = name_pair[1]
+        local alias = name_pair[2]
+        for _, inv in ipairs(inventory) do
+            for _, item in ipairs(inv.items) do
+                if string.sub(item.name, 1, string.len(full) + 1) == (full .. ".") then
+                    -- replace full .. "." with alias .. "."
+                    local prefix
+                    if not alias or pandoc.utils.stringify(alias) == "" then
+                        prefix = ""
+                    else
+                        -- TODO: ensure alias doesn't end with period
+                        prefix = pandoc.utils.stringify(alias) .. "."
+                    end
+                    local new_name = prefix .. string.sub(item.name, string.len(full) + 2)
+                    table.insert(new_inv.items, copy_replace(item, "name", new_name))
+                end
+            end
+        end
+    end
+    table.insert(inventory, new_inv)
+end
+
+local function build_search_object(str, debug)
     local starts_with_colon = str:sub(1, 1) == ":"
     local search = {}
     if starts_with_colon then
@@ -163,15 +247,15 @@ local function build_search_object(str)
             search.role = normalize_role(t[3])
             search.name = t[4]:match("%%60(.*)%%60")
         else
-            quarto.log.warning("couldn't parse this link: " .. str)
+            _debug_log("couldn't parse this link: " .. str, debug)
             return {}
         end
     else
         search.name = str:match("%%60(.*)%%60")
     end
 
     if search.name == nil then
-        quarto.log.warning("couldn't parse this link: " .. str)
+        _debug_log("couldn't parse this link: " .. str, debug)
         return {}
     end
 
@@ -220,7 +304,60 @@ function Link(link)
     return link
 end
 
-local function fixup_json(json, prefix)
+function Code(code)
+    if (not autolink) or contains(code.classes, autolink_ignore_token) then
+        return code
+    end
+
+    -- allow text for lookup to be simple function call
+    -- and also support shortened syntax (~~ prefix)
+    -- e.g. my_func() -> my_func
+    -- e.g. a.b.call() -> a.b.call
+    -- e.g. ~~my_func() -> my_func
+    local text
+
+    -- detect and remove shortening syntax (~~ prefix)
+    local is_shortened = code.text:sub(1, 2) == "~~"
+    local is_short_dot = code.text:sub(1, 3) == "~~."
+    local unprefixed = code.text:gsub("^~~%.?", "")
+    if unprefixed:match("%(%s*%)") then
+        text = unprefixed:gsub("%(%s*%)", "")
+    else
+        text = unprefixed
+    end
+
+
+    -- return code.attr
+    local search = build_search_object("%60" .. text .. "%60")
+    local item = lookup(search)
+
+    -- determine replacement, used if no link text specified ----
+    if item == nil then
+        code.text = unprefixed
+        return code
+    end
+
+    -- shorten text if shortening syntax used
+    if is_shortened then
+        -- keep text after last period (.)
+        local split = mysplit(unprefixed, ".")
+        if #split > 0 then
+            local new_name = split[#split]
+            if is_short_dot then
+                -- if shortened with dot, keep the dot
+                new_name = "." .. new_name
+            end
+            code.text = new_name
+        else
+            code.text = unprefixed
+        end
+    end
+
+
+    return pandoc.Link(code, item.uri:gsub("%$$", search.name))
+end
+
+local function fixup_json(json, prefix, attach)
     for _, item in ipairs(json.items) do
         item.uri = prefix .. item.uri
     end
@@ -232,6 +369,23 @@ return {
         Meta = function(meta)
             local json
             local prefix
+            local aliases
+
+            -- set globals from config
+            if meta.interlinks and meta.interlinks.autolink then
+                autolink = true
+            else
+                autolink = false
+            end
+
+            local aliases
+            if meta.interlinks and meta.interlinks.aliases then
+                aliases = meta.interlinks.aliases
+            else
+                aliases = {}
+            end
+
+            -- process sources
             if meta.interlinks and meta.interlinks.sources then
                 for k, v in pairs(meta.interlinks.sources) do
                     local base_name = quarto.project.offset .. "/_inv/" .. k .. "_objects"
@@ -246,9 +400,12 @@ return {
             if json ~= nil then
                 fixup_json(json, "/")
             end
+
+            prepend_aliases(flatten_alias_list(aliases))
         end
     },
     {
-        Link = Link
+        Link = Link,
+        Code = Code
     }
 }

_extensions/interlinks/objects.txt

@@ -0,0 +1,7 @@
+# Sphinx inventory version 2
+# Project: quartodoc
+# Version: 0.0.9999
+# The remainder of this file is compressed using zlib.
+some_func py:function 1 api/some_func.html -
+a.b.c py:function 1 api/a.b.c.html -
+quartodoc.Auto py:class 1 api/Auto.html -

_extensions/interlinks/test.qmd

@@ -0,0 +1,22 @@
+---
+filters:
+  - interlinks.lua
+interlinks:
+  autolink: true
+  aliases:
+    quartodoc: null
+  #sources:
+  #  test:
+  #    url: https://example.com
+---
+
+* `some_func`
+* `some_func()`
+* `some_func(a=1)`
+* `some_func()`{.qd-no-link}
+* `some_func + some_func`
+* `a.b.c`
+* `~a.b.c`
+* `a.b.c()`
+* `quartodoc.Auto()`
+* `Auto()`

docs/_quarto.yml

@@ -16,6 +16,9 @@ filters:
 
 interlinks:
   fast: true
+  autolink: true
+  aliases:
+    quartodoc: [null, qd]
   sources:
     python:
       url: https://docs.python.org/3/
@@ -56,10 +59,14 @@ website:
             - get-started/basic-content.qmd
             - get-started/basic-building.qmd
             - get-started/crossrefs.qmd
-            - get-started/interlinks.qmd
             - get-started/sidebar.qmd
             - get-started/extending.qmd
 
+        - section: Interlinking
+          contents:
+            - get-started/interlinks.qmd
+            - get-started/interlinks-autolink.qmd
+
         - section: "Docstrings"
           contents:
             - get-started/docstring-style.qmd