Improve discoverability of Connection(..., connect_kwargs={})

Support request made me realize, uh...this was NOT visible AT ALL
and it's kind of a core concept for most users.

fabric/connection.py

@@ -42,6 +42,14 @@ class Connection(Context):
     level operations with that `~paramiko.client.SSHClient` and
     `~paramiko.channel.Channel` instances generated from it.
 
+    .. _connect_kwargs:
+
+    .. note::
+        Many SSH specific options -- such as specifying private keys and
+        passphrases, timeouts, disabling SSH agents, etc -- are handled
+        directly by Paramiko and should be specified via the
+        :ref:`connect_kwargs argument <connect_kwargs-arg>` of the constructor.
+
     **Lifecycle**
 
     `.Connection` has a basic "`create <__init__>`, `connect/open <open>`, `do
@@ -206,15 +214,26 @@ def __init__(
 
             Default: ``config.timeouts.connect``.
 
+        .. _connect_kwargs-arg:
+
         :param dict connect_kwargs:
             Keyword arguments handed verbatim to
             `SSHClient.connect <paramiko.client.SSHClient.connect>` (when
             `.open` is called).
 
             `.Connection` tries not to grow additional settings/kwargs of its
             own unless it is adding value of some kind; thus,
-            ``connect_kwargs`` is currently the right place to hand in
-            parameters such as ``pkey`` or ``key_filename``.
+            ``connect_kwargs`` is currently the right place to hand in paramiko
+            connection parameters such as ``pkey`` or ``key_filename``. For
+            example::
+
+                c = Connection(
+                    host="hostname",
+                    user="admin",
+                    connect_kwargs={
+                        "key_filename": "/home/myuser/.ssh/private.key",
+                    },
+                )
 
             Default: ``config.connect_kwargs``.
 

sites/docs/getting-started.rst

@@ -100,6 +100,11 @@ instances of `invoke.runners.Result` (or subclasses thereof) exposing the sorts
 of details seen above: what was requested, what happened while the remote
 action occurred, and what the final result was.
 
+.. note::
+    Many lower-level SSH connection arguments (such as private keys and
+    timeouts) can be given directly to the SSH backend by using the
+    :ref:`connect_kwargs argument <connect_kwargs-arg>`.
+
 Superuser privileges via auto-response
 ======================================