Merge branch 'main' into typing

Author: tylerriccio33

.github/workflows/ci-docs.yaml

@@ -14,13 +14,17 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
       - name: Install dependencies
         run: |
           python -m pip install -e .
           python -m pip install ".[docs]"
           python -m pip install ibis-framework[duckdb]
           python -m pip install pins
+          python -m pip install pandera
+          python -m pip install patito
+          python -m pip install validoopsie
+          python -m pip install dataframely
       - name: Set up Quarto
         uses: quarto-dev/quarto-actions/setup@v2
       - name: Build docs

README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<a href="https://posit-dev.github.io/pointblank/"><img src="https://posit-dev.github.io/pointblank/assets/pointblank_logo.svg" width="75%"/></a>
+<a href="https://posit-dev.github.io/pointblank/"><img src="https://posit-dev.github.io/pointblank/assets/pointblank_logo.svg" width="85%"/></a>
 
 _Data validation made beautiful and powerful_
 
@@ -14,6 +14,7 @@ _Data validation made beautiful and powerful_
 [![Codecov branch](https://img.shields.io/codecov/c/github/posit-dev/pointblank/main.svg)](https://codecov.io/gh/posit-dev/pointblank)
 [![Repo Status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![Documentation](https://img.shields.io/badge/docs-project_website-blue.svg)](https://posit-dev.github.io/pointblank/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/posit-dev/pointblank)
 
 [![Contributors](https://img.shields.io/github/contributors/posit-dev/pointblank)](https://github.com/posit-dev/pointblank/graphs/contributors)
 [![Discord](https://img.shields.io/discord/1345877328982446110?color=%237289da&label=Discord)](https://discord.com/invite/YH7CybCNCQ)

docs/_extensions/machow/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
     }
 }

docs/_quarto.yml

@@ -1,5 +1,6 @@
 project:
   type: website
+  post-render: scripts/post-render.py
 
 format:
   html:
@@ -19,6 +20,9 @@ filters:
 
 interlinks:
   fast: true
+  autolink: true
+  aliases:
+    pointblank: [null, pb]
   sources:
     numpy:
       url: https://numpy.org/doc/stable/
@@ -83,6 +87,9 @@ website:
             - user-guide/preview.qmd
             - user-guide/col-summary-tbl.qmd
             - user-guide/missing-vals-tbl.qmd
+  page-footer:
+    left: 'Proudly supported by <a href="https://www.posit.co/" class="no-icon"><img src="/assets/posit-logo-black.svg" alt="Posit" width="80" style="padding-left: 3px;vertical-align:text-top;"></a>'
+    right: "&copy; 2024&ndash;2025 Posit Software, PBC."
 
 html-table-processing: none
 
@@ -203,6 +210,8 @@ quartodoc:
         - name: missing_vals_tbl
         - name: assistant
         - name: load_dataset
+        - name: get_data_path
+        - name: connect_to_table
     - title: Utility Functions
       desc: >
         The *Utility Functions* group contains functions that are useful accessing metadata about