Repository: ibis-project/ibis

Issue:
docs(api): backend specific connection parameters in the docstring of the connect method
At the moment the docstring of the main public factory method for a given backend is not helpful because it does not document what are the backend-specific connection parameters:

```python
>>> help(ibis.duckdb.connect)
Help on method connect in module ibis.backends.base:
 
connect(*args, **kwargs) -> 'BaseBackend' method of ibis.backends.duckdb.Backend instance
    Connect to the database.
    
    Parameters
    ----------
    args
        Connection parameters
    kwargs
        Additional connection parameters
    
    Notes
    -----
    This returns a new backend instance with saved `args` and `kwargs`,
    calling `reconnect` is called before returning.
    
    Returns
    -------
    BaseBackend
        An instance of the backend
```

However the docstring of the concrete `do_connect` method is more helpful:

```python
>>> help(ibis.duckdb.do_connect)
Help on method do_connect in module ibis.backends.duckdb:
 
do_connect(database: 'str | Path' = ':memory:', path: 'str | Path' = None, read_only: 'bool' = False, **config: 'Any') -> 'None' method of ibis.backends.duckdb.Backend instance
    Create an Ibis client connected to a DuckDB database.
    
    Parameters
    ----------
    database
        Path to a duckdb database.
    read_only
        Whether the database is read-only.
    config
        DuckDB configuration parameters. See the [DuckDB configuration
        documentation](https://duckdb.org/docs/sql/configuration) for
        possible configuration values.
    
    Examples
    --------
    >>> import ibis
    >>> ibis.duckdb.connect("database.ddb", threads=4, memory_limit="1GB")
```

and the example actually documents the usage of the `connect` method instead of the `do_connect` method.

I think the `ibis.duckdb.connect.__doc__` attribute should be updated one way or another to either include the content of `ibis.duckdb.do_connect.__doc__` or at least refer to the `do_connect` method of the backend for more details.


Discussion:
Thanks for raising this @ogrisel -- I think this is a great idea.

Resolving patch:
diff --git a/ibis/backends/base/__init__.py b/ibis/backends/base/__init__.py
--- a/ibis/backends/base/__init__.py
+++ b/ibis/backends/base/__init__.py
@@ -379,14 +379,17 @@ def connect(self, *args, **kwargs) -> BaseBackend:
         Parameters
         ----------
         args
-            Connection parameters
+            Mandatory connection parameters, see the docstring of `do_connect`
+            for details.
         kwargs
-            Additional connection parameters
+            Extra connection parameters, see the docstring of `do_connect` for
+            details.
 
         Notes
         -----
-        This returns a new backend instance with saved `args` and `kwargs`,
-        calling `reconnect` is called before returning.
+        This creates a new backend instance with saved `args` and `kwargs`,
+        then calls `reconnect` and finally returns the newly created and
+        connected backend instance.
 
         Returns
         -------


Test patch: