Move module level docstring into Sphinx docs

1 files changed, 22 insertions, 0 deletions

diff --git a/sites/docs/index.rst b/sites/docs/index.rst
index 98f4069a..87a0f994 100644
--- a/sites/docs/index.rst
+++ b/sites/docs/index.rst
@@ -10,6 +10,28 @@ please see `the main website <http://paramiko.org>`_.
 API documentation
 =================
 
+The high-level client API starts with creation of an `.SSHClient` object. For
+more direct control, pass a socket (or socket-like object) to a `.Transport`,
+and use `start_server <.Transport.start_server>` or `start_client
+<.Transport.start_client>` to negotiate with the remote host as either a server
+or client.
+
+As a client, you are responsible for authenticating using a password or private
+key, and checking the server's host key. (Key signature and verification is
+done by paramiko, but you will need to provide private keys and check that the
+content of a public key matches what you expected to see.)
+
+As a server, you are responsible for deciding which users, passwords, and keys
+to allow, and what kind of channels to allow.
+
+Once you have finished, either side may request flow-controlled `channels
+<.Channel>` to the other side, which are Python objects that act like sockets,
+but send and receive data over the encrypted session.
+
+For details, please see the following tables of contents (which are organized
+by area of interest.)
+
+
 Core SSH protocol classes
 -------------------------