Make the documentation being on several pages and improve root files layout

Author: mlorant

AUTHORS

@@ -0,0 +1,22 @@
+IMAPClient was created and is maintained by Menno Finlay-Smits <[email protected]>.
+Thanks go to the following people for their help with this project.
+
+- Mathieu Agopian
+- Chris Arndt
+- Jp Calderone
+- John Louis del Rosario
+- Dave Eckhardt
+- Eben Freeman
+- Helder Guerreiro
+- Mark Hammond <mhammond _AT_ skipinet.com.au>
+- Johannes Heckel
+- Thomas Jost <schnouki _AT_ schnouki.net>
+- Maxime Lorant
+- Lukasz Mierzwa
+- Naveen Nathan
+- Brian Neal
+- Phil Peterson
+- Aviv Salem
+- Andrew Scheller
+- Thomas Steinacher
+- Zac Witte

AUTHORS.rst

@@ -71,17 +71,7 @@ via PyPI use the pip or easy_install tools::
 
     easy_install IMAPClient
 
-The source distributions of all IMAPClient versions are available at
-http://menno.io/projects/IMAPClient/. Alternatively you can also use
-the PyPI page at https://pypi.python.org/pypi/IMAPClient/.
-
-To install from source run::
-
-    python setup.py install
-
-The project is packaged using Distribute (mostly compatible with
-setuptools) and all the usual setup.py installation options are
-available. See http://packages.python.org/distribute/ for more info.
+More installation methods are described in the documentation.
 
 Documentation
 -------------

README.rst

@@ -0,0 +1,111 @@
+Advanced Usage
+--------------
+This document covers some more advanced features and tips for handling
+specific usages.
+
+Watching a mailbox asynchronously using idle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+TODO
+
+Handling large mailboxes
+~~~~~~~~~~~~~~~~~~~~~~~~
+TODO
+
+Interactive Sessions
+~~~~~~~~~~~~~~~~~~~~
+When developing program using IMAPClient is it sometimes useful to
+have an interactive shell to play with. IMAPClient ships with a module
+that lets you fire up an interactive shell with an IMAPClient instance
+connected to an IMAP server.
+
+Start a session like this::
+
+   python -m imapclient.interact -H <host> -u <user> ...
+
+Various options are available to specify the IMAP server details. See
+the help (--help) for more details. You'll be prompted for a username
+and password if one isn't provided on the command line.
+
+It is also possible to pass connection details as a configuration file
+like this::
+
+   python -m imapclient.interact -f <config file>
+
+See below for details of the :ref:`configuration file format<conf-files>`.
+
+If installed, IPython will be used as the embedded shell. Otherwise
+the basic built-in Python shell will be used.
+
+The connected IMAPClient instance is available as the variable
+"c". Here's an example session::
+
+    $ python -m imapclient.interact -H <host> -u <user> ...
+    Connecting...
+    Connected.
+
+    IMAPClient instance is "c"
+    In [1]: c.select_folder('inbox')
+    Out[1]:
+    {b'EXISTS': 2,
+     b'FLAGS': (b'\\Answered',
+         b'\\Flagged',
+         b'\\Deleted',
+         b'\\Seen',
+         b'\\Draft'),
+     b'PERMANENTFLAGS': (b'\\Answered',
+         b'\\Flagged',
+         b'\\Deleted',
+         b'\\Seen',
+         b'\\Draft'),
+     b'READ-WRITE': True,
+     b'RECENT': 0,
+     b'UIDNEXT': 1339,
+     b'UIDVALIDITY': 1239278212}
+
+    In [2]: c.search()
+    Out[2]: [1123, 1233]
+
+    In [3]: c.logout()
+    Out[3]: b'Logging out'
+
+
+.. _conf-files:
+
+Configuration File Format
++++++++++++++++++++++++++
+Both the IMAPClient interactive shell and the live tests take
+configuration files which specify how to to connect to an IMAP
+server. The configuration file format is the same for both.
+
+Configuration files use the INI format and must always have a section
+called ``DEFAULT``. Here's a simple example::
+
+    [DEFAULT]
+    host = imap.mailserver.com
+    username = bob
+    password = sekret
+    ssl = True
+
+The supported options are:
+
+==================== ======= =========================================================================================
+Name                 Type    Description
+==================== ======= =========================================================================================
+host                 string  IMAP hostname to connect to.
+username             string  The username to authenticate as.
+password             string  The password to use with ``username``.
+port                 int     Server port to connect to. Defaults to 143 unless ``ssl`` is True.
+ssl                  bool    Use SSL/TLS to connect.
+starttls             bool    Use STARTTLS to connect.
+ssl_check_hostname   bool    If true and SSL is in use, check that certificate matches the hostname (defaults to true)
+ssl_verify_cert      bool    If true and SSL is in use, check that the certifcate is valid (defaults to true).
+ssl_ca_file          string  If SSL is true, use this to specify certificate authority certs to validate with.
+timeout              int     Time out I/O operations after this many seconds.
+oauth2               bool    If true, use OAUTH2 to authenticate (``username`` and ``password`` are ignored).
+oauth2_client_id     string  OAUTH2 client id.
+oauth2_client_secret string  OAUTH2 client secret.
+oauth2_refresh_token string  OAUTH2 token for refreshing the secret.
+==================== ======= =========================================================================================
+
+Acceptable boolean values are "1", "yes", "true", and "on", for true;
+and "0", "no", "false", and "off", for false.

THANKS

@@ -0,0 +1,47 @@
+IMAPClient Class
+~~~~~~~~~~~~~~~~
+The primary class used by the imapclient package is the IMAPClient
+class. All interaction with a remote IMAP server is performed via an
+IMAPClient instance.
+
+.. autoclass:: imapclient.IMAPClient
+   :members:
+
+Fetch Response Types
+~~~~~~~~~~~~~~~~~~~~
+Various types may be used in the data structures returned by
+:py:meth:`.IMAPClient.fetch` when certain response types
+are encountered during parsing.
+
+.. automodule:: imapclient.response_types
+   :members:
+
+Exceptions
+~~~~~~~~~~
+The following exceptions may be raised by IMAPClient directly. They
+are attached to the IMAPClient class.
+
+* IMAPClient.Error: the base class for IMAPClient's exceptions and the
+  most commonly used error.
+* IMAPClient.AbortError: raised if a serious error has occurred that
+  means the IMAP connection is no longer usable. The connection should
+  be dropped without logout if this occurs.
+* IMAPClient.ReadOnlyError: raised if a modifying operation was
+  attempted on a read-only folder.
+
+Exceptions from lower network layers are also possible, in particular:
+
+* socket.error
+* socket.timeout: raised if a timeout was specified when creating the
+  IMAPClient instance and a network operation takes too long.
+* backports.ssl.SSLError: the base class for network or SSL protocol
+  errors when ssl=True or starttls() is used.
+* backports.ssl.CertificateError: raised when TLS certification
+  verification fails. This is *not* a subclass of SSLError.
+
+
+TLS Support
+~~~~~~~~~~~
+
+.. automodule:: imapclient.tls
+   :members: