docs(algolia): add custom attributes to backend and core methods (#9730)

Author: gforsyth

.github/workflows/algolia/configure-algolia.py

@@ -0,0 +1,35 @@
+from __future__ import annotations  # noqa: INP001
+
+import os
+
+from algoliasearch.search_client import SearchClient
+
+api_key = os.environ["ALGOLIA_WRITE_API_KEY"]
+app_id = os.environ["ALGOLIA_APP_ID"]
+index_name = os.environ["ALGOLIA_INDEX"]
+
+
+def main():
+    client = SearchClient.create(app_id, api_key)
+    index = client.init_index(index_name)
+
+    # Core is a custom attribute set to denote whether a record is part
+    # of the base expression API, we sort descending so those methods
+    # show up first in search instead of backend-specific methods
+    override_default_settings = {
+        "ranking": [
+            "typo",
+            "words",
+            "desc(core)",
+            "filters",
+            "proximity",
+            "attribute",
+            "exact",
+        ]
+    }
+
+    index.set_settings(override_default_settings)
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/upload-algolia-api.py renamed to .github/workflows/algolia/upload-algolia-api.py

@@ -62,13 +62,40 @@ def _create_api_record_from_method_line(base_url, method):
         "objectID": f"{base_url}{anchor}",
         "href": f"{base_url}{anchor}",
         "title": name,
-        "text": desc,
-        "crumbs": ["Expression API", "API", f"{section} expressions"],
+        "backend": "core",
+        "core": 1,
+        "crumbs": ["Expression API", "API", f"{section} expression"],
     }
+    if desc:
+        record["text"] = desc
 
     return record
 
 
+def adjust_backend_custom_attributes(backend_records):
+    """Adjusts attributes of the Algolia records.
+
+    Two custom attribute changes:
+        One is the name of the backend, which we can possibly use for grouping
+        or filtering results.
+
+        The other is a marker of whether the record is part of the core
+        expression API, which we can use to sort results so that generic table
+        expressions appear above backend-specific ones in the case of
+        name-collisions.
+
+    We also strip out the "text" attribute if it's empty
+    """
+    backend_name = backend_records[0]["title"].split(".", 1)[0]
+    for record in backend_records:
+        record["backend"] = backend_name
+        record["core"] = 0
+        if not record["text"]:
+            record.pop("text")
+
+    return backend_records
+
+
 def main():
     client = SearchClient.create(app_id, api_key)
     index = client.init_index(index_name)
@@ -106,8 +133,12 @@ def main():
     # Here, we load those records and upload them to the Algolia index
     records = []
     for record_json in glob.glob("docs/backends/*.json"):
+        print(f"Loading {record_json} methods...")  # noqa:T201
         with open(record_json) as f:
-            records.extend(json.load(f))
+            backend_records = json.load(f)
+            backend_records = adjust_backend_custom_attributes(backend_records)
+            records.extend(backend_records)
+    print(f"Uploading {len(records)} records to {index.name=}")  # noqa:T201
     index.save_objects(records)
 
 

.github/workflows/upload-algolia.py renamed to .github/workflows/algolia/upload-algolia.py

@@ -71,15 +71,23 @@ jobs:
 
       - name: Create and Upload Base Index
         run: |
-          python .github/workflows/upload-algolia.py
+          python .github/workflows/algolia/upload-algolia.py
         env:
           ALGOLIA_WRITE_API_KEY: ${{ secrets.ALGOLIA_WRITE_API_KEY }}
           ALGOLIA_APP_ID: TNU9HG3L41
           ALGOLIA_INDEX: prod_ibis
 
       - name: Create and Upload API Records to index
         run: |
-          python .github/workflows/upload-algolia-api.py
+          python .github/workflows/algolia/upload-algolia-api.py
+        env:
+          ALGOLIA_WRITE_API_KEY: ${{ secrets.ALGOLIA_WRITE_API_KEY }}
+          ALGOLIA_APP_ID: TNU9HG3L41
+          ALGOLIA_INDEX: prod_ibis
+
+      - name: Configure custom ranking on Algolia
+        run: |
+          python .github/workflows/algolia/configure-algolia-api.py
         env:
           ALGOLIA_WRITE_API_KEY: ${{ secrets.ALGOLIA_WRITE_API_KEY }}
           ALGOLIA_APP_ID: TNU9HG3L41

.github/workflows/ibis-docs-main.yml

@@ -36,7 +36,17 @@ def find_member_with_docstring(member):
         return member
 
     cls = member.parent
-    for base in cls.resolved_bases:
+    resolved_bases = cls.resolved_bases
+    # If we're a SQLBackend (likely) then also search through to `BaseBackend``
+    if resolved_bases and (sqlbackend := resolved_bases[0]).name == "SQLBackend":
+        for base in sqlbackend.resolved_bases:
+            if base not in resolved_bases:
+                resolved_bases.append(base)
+
+    # Remove `CanCreateSchema` and `CanListSchema` since they are deprecated
+    # and we don't want to document their existence.
+    filtered_bases = filter(lambda x: "schema" not in x.name.lower(), resolved_bases)
+    for base in filtered_bases:
         try:
             parent_member = get_callable(base, member.name)
         except KeyError: