From e6500326133b8ecbdc94b1b1c8a30c19e9039825 Mon Sep 17 00:00:00 2001
From: Nick Crews <nicholas.b.crews@gmail.com>
Date: Tue, 3 Dec 2024 13:07:31 +0900
Subject: [PATCH] docs: add callout notes for some APIs changes and additions

fixes https://github.com/ibis-project/ibis/issues/10535
---
 ibis/backends/duckdb/__init__.py |  9 +++++++++
 ibis/expr/api.py                 |  3 +++
 ibis/expr/types/generic.py       | 10 ++++++++++
 ibis/expr/types/relations.py     |  4 ++++
 4 files changed, 26 insertions(+)

diff --git a/ibis/backends/duckdb/__init__.py b/ibis/backends/duckdb/__init__.py
index 03c463907443..da1cfdd3f557 100644
--- a/ibis/backends/duckdb/__init__.py
+++ b/ibis/backends/duckdb/__init__.py
@@ -384,6 +384,15 @@ def do_connect(
         >>> import ibis
         >>> ibis.duckdb.connect(threads=4, memory_limit="1GB")  # doctest: +ELLIPSIS
         <ibis.backends.duckdb.Backend object at 0x...>
+
+        ::: {.callout-note title="Changed in version 10.0.0"}
+        Before, we had special handling if the user passed the `temp_directory`
+        parameter, setting a custom default, and creating intermediate
+        directories if necessary. Now, we do nothing, and just pass the value
+        directly to DuckDB. You may need to add
+        `Path(your_temp_dir).mkdir(exists_ok=True, parents=True)`
+        to your code to maintain the old behavior.
+        :::
         """
         if not isinstance(database, Path) and not database.startswith(
             ("md:", "motherduck:", ":memory:")
diff --git a/ibis/expr/api.py b/ibis/expr/api.py
index 8ba4d27db7a7..442fb6fd9e28 100644
--- a/ibis/expr/api.py
+++ b/ibis/expr/api.py
@@ -1243,6 +1243,9 @@ def cases(
     │ divisible by 2 │
     │ divisible by 2 │
     └────────────────┘
+
+    ::: {.callout-note title="Added in version 10.0.0"}
+    :::
     """
     cases, results = zip(branch, *branches)
     return ops.SearchedCase(cases=cases, results=results, default=else_).to_expr()
diff --git a/ibis/expr/types/generic.py b/ibis/expr/types/generic.py
index ff54fa18d992..e3934a946bd6 100644
--- a/ibis/expr/types/generic.py
+++ b/ibis/expr/types/generic.py
@@ -2122,6 +2122,10 @@ def topk(
         │ J      │      5.01 │
         │ H      │      4.13 │
         └────────┴───────────┘
+
+        ::: {.callout-note title="Changed in version 9.5.0"}
+        Added `name` parameter.
+        :::
         """
         from ibis.expr.types.relations import bind
 
@@ -2279,6 +2283,9 @@ def value_counts(self, *, name: str | None = None) -> ir.Table:
         │ c      │     3 │
         │ d      │     4 │
         └────────┴───────┘
+
+        ::: {.callout-note title="Added in version 9.5.0"}
+        :::
         """
         colname = self.get_name()
         if name is None:
@@ -2785,6 +2792,9 @@ def to_list(self, **kwargs) -> list:
         >>> t = ibis.examples.penguins.fetch()
         >>> t.bill_length_mm.to_list(limit=5)
         [39.1, 39.5, 40.3, None, 36.7]
+
+        ::: {.callout-note title="Added in version 10.0.0"}
+        :::
         """
         return self.to_pyarrow(**kwargs).to_pylist()
 
diff --git a/ibis/expr/types/relations.py b/ibis/expr/types/relations.py
index 1ad5feae3ff4..31f515779abf 100644
--- a/ibis/expr/types/relations.py
+++ b/ibis/expr/types/relations.py
@@ -4720,6 +4720,10 @@ def value_counts(self, *, name: str | None = None) -> ir.Table:
         │  2009 │ Dream     │                44 │
         │  2009 │ Torgersen │                16 │
         └───────┴───────────┴───────────────────┘
+
+        ::: {.callout-note title="Changed in version 10.0.0"}
+        Added `name` parameter.
+        :::
         """
         columns = self.columns
         if name is None: