docs: add API docs for operations

ibis-project · May 22, 2024 · f20b789 · f20b789
1 parent 1ecb319
commit f20b789
Show file tree

Hide file tree

Showing 4 changed files with 88 additions and 55 deletions.
diff --git a/docs/_quarto.yml b/docs/_quarto.yml
@@ -125,6 +125,7 @@ website:
       contents:
         - auto: backends/*.qmd
         - support_matrix.qmd
+        - reference/operations.qmd
     - id: how-to
       title: "How-to"
       style: "docked"
@@ -506,6 +507,34 @@ quartodoc:
             - name: NumericValue.point
               package: ibis.expr.types.numeric
 
+        - kind: page
+          path: operations
+          package: ibis.expr.operations
+          summary:
+            name: Operations
+            desc: Low level operation classes. Subject to change in non-major releases.
+          contents:
+            - analytic
+            - arrays
+            - core
+            - generic
+            - geospatial
+            - histograms
+            - json
+            - logical
+            - maps
+            - numeric
+            - reductions
+            - relations
+            - sortkeys
+            - strings
+            - structs
+            - subqueries
+            - temporal
+            - temporal_windows
+            - udf
+            - vectorized
+            - window
         - kind: page
           summary:
             name: Column selectors

diff --git a/docs/support_matrix.py b/docs/support_matrix.py
diff --git a/docs/support_matrix.qmd b/docs/support_matrix.qmd
@@ -19,7 +19,10 @@ varies.
 ::: {.callout-tip}
 Backends with low coverage are good places to start contributing!
 
-Each backend implements operations differently, but this is usually very similar to other backends. If you want to start contributing to ibis, it's a good idea to start by adding missing operations to backends that have low operation coverage.
+Each backend implements operations differently, but this is usually very
+similar to other backends. If you want to start contributing to ibis, it's
+a good idea to start by adding missing operations to backends that have low
+operation coverage.
 :::
 
 :::
@@ -58,9 +61,62 @@ dict(value=sql_backends, color="green", icon="database")
 
 ## {height=70%}
 
+```{python}
+#| echo: false
+import pandas as pd
+
+import ibis
+import ibis.expr.operations as ops
+
+
+def make_support_matrix():
+    """Construct the backend operation support matrix data."""
+
+    from ibis.backends.sql.compiler import ALL_OPERATIONS
+
+    support_matrix_ignored_operations = (ops.ScalarParameter,)
+
+    public_ops = ALL_OPERATIONS.difference(support_matrix_ignored_operations)
+
+    assert public_ops
+
+    support = {"Operation": [f"{op.__module__}.{op.__name__}" for op in public_ops]}
+    support.update(
+        (backend, list(map(getattr(ibis, backend).has_operation, public_ops)))
+        for backend in sorted(ep.name for ep in ibis.util.backend_entry_points())
+    )
+
+    def make_link(parts):
+        module, op = parts[-2:]
+        return f'<a href="./reference/expression-operations.html#ibis.expr.operations.{module}.{op}">{op}</a>'
+
+    support_matrix = (
+        pd.DataFrame(support)
+        .assign(splits=lambda df: df.Operation.str.findall("[a-zA-Z_][a-zA-Z_0-9]*"))
+        .assign(
+            Category=lambda df: df.splits.str[-2],
+            Operation=lambda df: df.splits.map(make_link),
+        )
+        .drop(["splits"], axis=1)
+        .set_index(["Category", "Operation"])
+        .sort_index()
+    )
+    all_visible_ops_count = len(support_matrix)
+    assert all_visible_ops_count
+
+    coverage = pd.Index(
+        support_matrix.sum()
+        .map(lambda n: f"{n} ({round(100 * n / all_visible_ops_count)}%)")
+        .T
+    )
+    support_matrix.columns = pd.MultiIndex.from_tuples(
+        list(zip(support_matrix.columns, coverage)), names=("Backend", "API coverage")
+    )
+    return support_matrix
+```
+
 ```{python}
 from itables import show
-from support_matrix import make_support_matrix
 
 
 matrix = make_support_matrix()

diff --git a/ibis/expr/types/generic.py b/ibis/expr/types/generic.py
@@ -1356,7 +1356,7 @@ def preview(
         max_rows
             Maximum number of rows to display
         max_length
-           Maximum length for pretty-printed arrays and maps.
+            Maximum length for pretty-printed arrays and maps.
         max_string
             Maximum length for pretty-printed strings.
         max_depth