API docs: be more explicit about driver factory parameters (#883)

* API docs: be more explicit about driver factory parameters

* API docs: cannot combine +s/+ssc schemes with some settings

* Minor tweak: add ref to URI when talking about schemes

Author: robsdedude

docs/source/api.rst

@@ -16,7 +16,7 @@ The :class:`neo4j.Driver` construction is done via a ``classmethod`` on the :cla
 .. autoclass:: neo4j.GraphDatabase
    :members: bookmark_manager
 
-    .. method:: driver
+    .. automethod:: driver
 
         Driver creation example:
 
@@ -212,6 +212,8 @@ connection can be used to perform database related work.
 -------------
 Specify whether to use an encrypted connection between the driver and server.
 
+This setting is only available for URI schemes ``bolt://`` and ``neo4j://`` (:ref:`uri-ref`).
+
 This setting does not have any effect if a custom ``ssl_context`` is configured.
 
 :Type: ``bool``
@@ -312,6 +314,8 @@ For example:
 ---------
 Specify how to determine the authenticity of encryption certificates provided by the Neo4j instance on connection.
 
+This setting is only available for URI schemes ``bolt://`` and ``neo4j://`` (:ref:`uri-ref`).
+
 This setting does not have any effect if ``encrypted`` is set to ``False``.
 
 :Type: ``neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES``, ``neo4j.TRUST_ALL_CERTIFICATES``
@@ -342,6 +346,8 @@ This setting does not have any effect if ``encrypted`` is set to ``False``.
 ---------------
 Specify a custom SSL context to use for wrapping connections.
 
+This setting is only available for URI schemes ``bolt://`` and ``neo4j://`` (:ref:`uri-ref`).
+
 If given, ``encrypted`` and ``trusted_certificates`` have no effect.
 
 .. warning::
@@ -361,6 +367,8 @@ If given, ``encrypted`` and ``trusted_certificates`` have no effect.
 ------------------------
 Specify how to determine the authenticity of encryption certificates provided by the Neo4j instance on connection.
 
+This setting is only available for URI schemes ``bolt://`` and ``neo4j://`` (:ref:`uri-ref`).
+
 This setting does not have any effect if ``encrypted`` is set to ``False`` or a
 custom ``ssl_context`` is configured.
 

src/neo4j/_async/driver.py

@@ -122,12 +122,20 @@ def driver(
     else:
 
         @classmethod
-        def driver(cls, uri, *, auth=None, **config) -> AsyncDriver:
+        def driver(
+            cls, uri: str, *,
+            auth: t.Union[t.Tuple[t.Any, t.Any], Auth, None] = None,
+            **config
+        ) -> AsyncDriver:
             """Create a driver.
 
-            :param uri: the connection URI for the driver, see :ref:`async-uri-ref` for available URIs.
-            :param auth: the authentication details, see :ref:`auth-ref` for available authentication details.
-            :param config: driver configuration key-word arguments, see :ref:`async-driver-configuration-ref` for available key-word arguments.
+            :param uri: the connection URI for the driver,
+                see :ref:`async-uri-ref` for available URIs.
+            :param auth: the authentication details,
+                see :ref:`auth-ref` for available authentication details.
+            :param config: driver configuration key-word arguments,
+                see :ref:`async-driver-configuration-ref` for available
+                key-word arguments.
             """
 
             driver_type, security_type, parsed = parse_neo4j_uri(uri)

src/neo4j/_sync/driver.py

@@ -119,12 +119,20 @@ def driver(
     else:
 
         @classmethod
-        def driver(cls, uri, *, auth=None, **config) -> Driver:
+        def driver(
+            cls, uri: str, *,
+            auth: t.Union[t.Tuple[t.Any, t.Any], Auth, None] = None,
+            **config
+        ) -> Driver:
             """Create a driver.
 
-            :param uri: the connection URI for the driver, see :ref:`uri-ref` for available URIs.
-            :param auth: the authentication details, see :ref:`auth-ref` for available authentication details.
-            :param config: driver configuration key-word arguments, see :ref:`driver-configuration-ref` for available key-word arguments.
+            :param uri: the connection URI for the driver,
+                see :ref:`uri-ref` for available URIs.
+            :param auth: the authentication details,
+                see :ref:`auth-ref` for available authentication details.
+            :param config: driver configuration key-word arguments,
+                see :ref:`driver-configuration-ref` for available
+                key-word arguments.
             """
 
             driver_type, security_type, parsed = parse_neo4j_uri(uri)