diff --git a/doc/src/connection.rst b/doc/src/connection.rst
index d656fa1b..2910f301 100644
--- a/doc/src/connection.rst
+++ b/doc/src/connection.rst
@@ -676,33 +676,6 @@ The ``connection`` class
             .. __: http://www.postgresql.org/docs/current/static/libpq-status.html#LIBPQ-PQTRANSACTIONSTATUS
 
 
-    .. method:: encrypt_password(password, user, [algorithm])
-
-        Returns the encrypted form of a PostgreSQL password based on the
-        current password encryption algorithm.
-
-        Raises `~psycopg2.NotSupportedError` if the ``psycopg2`` module was
-        compiled with a ``libpq`` version lesser than 10 (which can be detected
-        by the `~psycopg2.__libpq_version__` constant), when encryption
-        algorithm other than 'md5' is specified for the server version greater
-        than, or equal to 10.
-
-        Ignores the encrytion algorithm for servers version less than 10, and
-        always uses 'md5' as encryption algorithm.
-
-        .. seealso:: libpq docs for `PQencryptPasswordConn()`__ for details.
-
-            .. __: https://www.postgresql.org/docs/devel/static/libpq-misc.html#libpq-pqencryptpasswordconn
-
-        .. seealso:: libpq docs for `PQencryptPassword()`__ for details.
-
-            .. __: https://www.postgresql.org/docs/devel/static/libpq-misc.html#libpq-pqencryptpassword
-
-        .. seealso:: libpq docs for `password_encryption`__ for details.
-
-            .. __: https://www.postgresql.org/docs/devel/static/runtime-config-connection.html#guc-password-encryption
-
-
     .. index::
         pair: Protocol; Version
 
diff --git a/doc/src/extensions.rst b/doc/src/extensions.rst
index 8545fcfa..34d53a7e 100644
--- a/doc/src/extensions.rst
+++ b/doc/src/extensions.rst
@@ -555,6 +555,38 @@ Other functions
         .. __: http://www.postgresql.org/docs/current/static/libpq-exec.html#LIBPQ-PQESCAPEIDENTIFIER
 
 
+.. method:: encrypt_password(password, user, scope=None, algorithm=None)
+
+    Return the encrypted form of a PostgreSQL password.
+
+    :param password: the cleartext password to encrypt
+    :param user: the name of the user to use the password for
+    :param scope: the scope to encrypt the password into; if *algorithm* is
+        ``md5`` it can be `!None`
+    :type scope: `connection` or `cursor`
+    :param algorithm: the password encryption algorithm to use
+
+    The *algorithm* ``md5`` is always supported. Other algorithms are only
+    supported if the client libpq version is at least 10 and may require a
+    compatible server version: check the `PostgreSQL encryption
+    documentation`__ to know the algorithms supported by your server.
+
+    .. __: https://www.postgresql.org/docs/current/static/encryption-options.html
+
+    Using `!None` as *algorithm* will result in querying the server to know the
+    current server password encryption setting, which is a blocking operation:
+    query the server separately and specify a value for *algorithm* if you
+    want to maintain a non-blocking behaviour.
+
+    .. versionadded:: 2.8
+
+    .. seealso:: PostgreSQL docs for the `password_encryption`__ setting, libpq `PQencryptPasswordConn()`__, `PQencryptPassword()`__ functions.
+
+        .. __: https://www.postgresql.org/docs/current/static/runtime-config-connection.html#GUC-PASSWORD-ENCRYPTION
+        .. __: https://www.postgresql.org/docs/current/static/libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN
+        .. __: https://www.postgresql.org/docs/current/static/libpq-misc.html#LIBPQ-PQENCRYPTPASSWORD
+
+
 
 .. index::
     pair: Isolation level; Constants