docs: bring back backend API documentation

docs/backends/_templates/api.qmd

@@ -0,0 +1,21 @@
+```{python}
+#| echo: false
+#| output: asis
+
+from _utils import get_backend, render_methods
+
+# defined in the backend qmd, e.g., ../bigquery.qmd
+module = BACKEND.lower()
+backend = get_backend(module)
+
+print(f"## `{module}.Backend` {{ #{backend.canonical_path} }}")
+
+methods = sorted(
+    key for key, value in backend.members.items()
+    if value.is_function
+    if not value.name.startswith("_")
+    if value.name != "do_connect"
+)
+
+render_methods(backend, *methods, level=4)
+```

docs/backends/_utils.py

@@ -26,9 +26,39 @@ def get_callable(obj, name):
         return obj.functions[name]
 
 
+def find_member_with_docstring(member):
+    """Find the first inherited member with a docstring."""
+    if member.docstring is not None:
+        return member
+
+    cls = member.parent
+    for base in cls.resolved_bases:
+        try:
+            parent_member = get_callable(base, member.name)
+        except KeyError:
+            continue
+        else:
+            if parent_member.docstring is not None:
+                return parent_member
+    return member
+
+
 def render_method(*, member, renderer: MdRenderer) -> Iterator[str]:
-    yield f"{'#' * renderer.crnt_header_level} {member.name} {{ #{member.path} }}"
-    yield renderer.render(member)
+    header_level = renderer.crnt_header_level
+    header = "#" * header_level
+    name = member.name
+    try:
+        params = renderer.render(member.parameters)
+    except AttributeError:
+        params = None
+    yield "\n"
+    yield f"{header} {name} {{ #{member.path} }}"
+    yield "\n"
+    if params is not None:
+        yield f"`{name}({params})`"
+    yield "\n"
+
+    yield renderer.render(find_member_with_docstring(member))
 
 
 def render_methods(obj, *methods: str, level: int) -> None:

docs/backends/bigquery.qmd

@@ -126,3 +126,10 @@ gcloud auth login
 For any authentication problems, or information on other ways of authenticating,
 see the [`gcloud` CLI authorization
 guide](https://cloud.google.com/sdk/docs/authorizing).
+
+```{python}
+#| echo: false
+BACKEND = "BigQuery"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/clickhouse.qmd

@@ -123,3 +123,10 @@ or
 con = ibis.connect("clickhouse://play:clickhouse@play.clickhouse.com:443?secure=True")
 con.table("opensky")
 ```
+
+```{python}
+#| echo: false
+BACKEND = "ClickHouse"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/dask.qmd

@@ -65,3 +65,10 @@ con = ibis.dask.connect()  # <1>
 1. Adjust connection parameters as needed.
 
 :::
+
+```{python}
+#| echo: false
+BACKEND = "Dask"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/datafusion.qmd

@@ -105,3 +105,10 @@ from _utils import render_methods, get_backend
 backend = get_backend("datafusion")
 render_methods(backend, "read_csv", "read_parquet", "read_delta", level=4)
 ```
+
+```{python}
+#| echo: false
+BACKEND = "DataFusion"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/druid.qmd

@@ -102,3 +102,10 @@ passing a properly formatted Druid connection URL to `ibis.connect`
 ```python
 con = ibis.connect("druid://localhost:8082/druid/v2/sql")
 ```
+
+```{python}
+#| echo: false
+BACKEND = "Druid"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/duckdb.qmd

@@ -155,3 +155,10 @@ backend = get_backend("duckdb")
 methods = [f"read_{kind}" for kind in ("csv", "parquet", "delta", "json", "in_memory", "sqlite", "postgres")]
 render_methods(backend, *methods, level=4)
 ```
+
+```{python}
+#| echo: false
+BACKEND = "DuckDB"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/mssql.qmd

@@ -101,3 +101,10 @@ passing a properly formatted MSSQL connection URL to `ibis.connect`
 ```python
 con = ibis.connect(f"mssql://{user}:{password}@{host}:{port}")
 ```
+
+```{python}
+#| echo: false
+BACKEND = "MSSQL"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/mysql.qmd

@@ -102,3 +102,10 @@ passing a properly formatted MySQL connection URL to `ibis.connect`
 ```python
 con = ibis.connect(f"mysql://{user}:{password}@{host}:{port}/{database}")
 ```
+
+```{python}
+#| echo: false
+BACKEND = "MySQL"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/oracle.qmd

@@ -122,3 +122,10 @@ show parameter sec_case_sensitive_logon;
 If the returned value is `FALSE` then Ibis will _not_ connect.
 
 For more information, see this [issue](https://github.com/oracle/python-oracledb/issues/26).
+
+```{python}
+#| echo: false
+BACKEND = "Oracle"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/pandas.qmd

@@ -194,3 +194,10 @@ def add_two_with_none(x, y=None):
     y = 2.0
     return x + y
 ```
+
+```{python}
+#| echo: false
+BACKEND = "Pandas"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/polars.qmd

@@ -101,3 +101,10 @@ methods = ("read_csv", "read_parquet", "read_delta")
 backend = get_backend("polars")
 render_methods(backend, *methods, level=4)
 ```
+
+```{python}
+#| echo: false
+BACKEND = "Polars"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/postgresql.qmd

@@ -102,3 +102,10 @@ passing a properly formatted Postgres connection URL to `ibis.connect`
 ```python
 con = ibis.connect(f"postgres://{user}:{password}@{host}:{port}/{database}")
 ```
+
+```{python}
+#| echo: false
+BACKEND = "Postgres"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/pyspark.qmd

@@ -105,3 +105,10 @@ methods = ("read_csv", "read_parquet")
 backend = get_backend("pyspark")
 render_methods(backend, *methods, level=4)
 ```
+
+```{python}
+#| echo: false
+BACKEND = "PySpark"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/snowflake.qmd

@@ -174,3 +174,10 @@ methods = ("read_csv", "read_parquet", "read_json")
 backend = get_backend("snowflake")
 render_methods(backend, *methods, level=4)
 ```
+
+```{python}
+#| echo: false
+BACKEND = "Snowflake"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/sqlite.qmd

@@ -111,3 +111,10 @@ The URL can be `sqlite://` which will connect to an ephemeral in-memory database
 ```python
 con = ibis.connect("sqlite://")
 ```
+
+```{python}
+#| echo: false
+BACKEND = "SQLite"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/backends/trino.qmd

@@ -96,3 +96,10 @@ from _utils import render_do_connect
 
 render_do_connect("trino")
 ```
+
+```{python}
+#| echo: false
+BACKEND = "Trino"
+```
+
+{{< include ./_templates/api.qmd >}}

docs/styles.css

@@ -1,4 +1,9 @@
-section#connection-parameters {
+section#parameters {
+    /* scroll when child contents overflow the width */
+    overflow-x: auto;
+}
+
+section#parameters-1 {
     /* scroll when child contents overflow the width */
     overflow-x: auto;
 }