From 0d197e83aa8e6d27bb540a180ac7daf317d7dc30 Mon Sep 17 00:00:00 2001
From: Phillip Cloud <417981+cpcloud@users.noreply.github.com>
Date: Sat, 9 Sep 2023 05:36:17 -0400
Subject: [PATCH] docs: add `ibis.connect` to `top_level` API docs

---
 docs/_quarto.yml               |  2 ++
 ibis/backends/base/__init__.py | 32 +++++++++++++++++++++++++++-----
 2 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/docs/_quarto.yml b/docs/_quarto.yml
index 01a38c253bdc..7aaa1bd3f5af 100644
--- a/docs/_quarto.yml
+++ b/docs/_quarto.yml
@@ -202,6 +202,8 @@ quartodoc:
               dynamic: true
             - name: coalesce
               package: ibis.expr.api
+            - name: connect
+              package: ibis.backends.base
             - name: cumulative_window
               dynamic: true
             - name: date
diff --git a/ibis/backends/base/__init__.py b/ibis/backends/base/__init__.py
index 38ed28114b5a..459d78d64c4f 100644
--- a/ibis/backends/base/__init__.py
+++ b/ibis/backends/base/__init__.py
@@ -1167,6 +1167,21 @@ def _get_backend_names() -> frozenset[str]:
 def connect(resource: Path | str, **kwargs: Any) -> BaseBackend:
     """Connect to `resource`, inferring the backend automatically.
 
+    The general pattern for `ibis.connect` is
+
+    ```python
+    ibis.connect("backend://connection-parameters")
+    ```
+
+    With many backends that looks like
+
+    ```python
+    ibis.connect("backend://user:password@host:port/database")
+    ```
+
+    See the connection syntax for each backend for details about URL connection
+    requirements.
+
     Parameters
     ----------
     resource
@@ -1176,15 +1191,22 @@ def connect(resource: Path | str, **kwargs: Any) -> BaseBackend:
 
     Examples
     --------
-    Connect to an in-memory duckdb database:
+    Connect to an in-memory DuckDB database:
+
     >>> con = ibis.connect("duckdb://")
 
-    Connect to an on-disk sqlite database:
-    >>> con = ibis.connect("sqlite://relative/path/to/data.db")
+    Connect to an on-disk SQLite database:
+
+    >>> con = ibis.connect("sqlite://relative.db")
     >>> con = ibis.connect("sqlite:///absolute/path/to/data.db")
 
-    Connect to a postgres server:
-    >>> con = ibis.connect("postgres://user:password@hostname:5432")
+    Connect to a PostgreSQL server:
+
+    >>> con = ibis.connect("postgres://user:password@hostname:5432")  # quartodoc: +SKIP # doctest: +SKIP
+
+    Connect to BigQuery:
+
+    >>> con = ibis.connect("bigquery://my-project/my-dataset")  # quartodoc: +SKIP # doctest: +SKIP
     """
     url = resource = str(resource)