Many small documentation tweaks

Removed the quickstart section as it's not necessary. The README as an
introductory example now, and the current documentation structure is
better now.

Author: mjs

AUTHORS.rst

@@ -1,9 +1,11 @@
 IMAPClient was created by Menno Finlay-Smits <[email protected]>. The
-project is now Nicolas Le Manchet and Menno Finlay-Smits.
+project is now maintained by Nicolas Le Manchet and Menno
+Finlay-Smits.
 
 Many thanks go to the following people for their help with this
 project:
 
+- Maxime Lorant
 - Mathieu Agopian
 - Chris Arndt
 - Jp Calderone
@@ -14,7 +16,6 @@ project:
 - Mark Hammond
 - Johannes Heckel
 - Thomas Jost
-- Maxime Lorant
 - Lukasz Mierzwa
 - Naveen Nathan
 - Brian Neal

doc/src/advanced.rst

@@ -22,15 +22,15 @@ However if an error is raised when selecting the folder, the connection may be
 left open.
 
 IMAPClient may be used as a context manager that automatically closes
-connections when they are not needed anymore::
+connections when they are not needed any more::
 
   import imapclient
 
   with imapclient.IMAPClient(host="imap.foo.org") as c:
       c.login("[email protected]", "passwd")
       c.select_folder("INBOX")
 
-Watching a mailbox using idle
+Watching a Mailbox Using IDLE
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The IDLE extension allows an IMAP server to notify a client when something
 changes in a mailbox. It can be used as an alternative to polling to receive
@@ -39,7 +39,7 @@ new messages.
 The concept is simple: the client connects to the server, selects a mailbox and
 enters the IDLE mode. At this point the server sends notifications whenever
 something happens in the selected mailbox until the client ends the IDLE mode
-by issuing a `DONE` command. This is explained in :rfc:`2177`.
+by issuing a ``DONE`` command. This is explained in :rfc:`2177`.
 
 .. literalinclude:: ../../examples/idle_example.py
 
@@ -48,10 +48,6 @@ when maintaining long-lived TCP connections. Users are advised to renew the
 IDLE command every 10 minutes to avoid the connection from being abruptly
 closed.
 
-Handling large mailboxes
-~~~~~~~~~~~~~~~~~~~~~~~~
-TODO
-
 Interactive Sessions
 ~~~~~~~~~~~~~~~~~~~~
 When developing program using IMAPClient is it sometimes useful to
@@ -150,8 +146,3 @@ 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.
-
-Thread Safety
-~~~~~~~~~~~~~
-Instances of IMAPClient are NOT thread safe. They should not be shared and
-accessed concurrently from multiple threads.

doc/src/api.rst

@@ -61,3 +61,8 @@ TLS Support
 
 .. automodule:: imapclient.tls
    :members:
+
+Thread Safety
+~~~~~~~~~~~~~
+Instances of IMAPClient are NOT thread safe. They should not be shared and
+accessed concurrently from multiple threads.

doc/src/concepts.rst

@@ -1,4 +1,4 @@
-IMAPClient concepts
+IMAPClient Concepts
 -------------------
 
 Message Identifiers
@@ -77,13 +77,14 @@ connections and also allows for a high level of control of TLS
 parameters if required. It uses the built-in `ssl` package, 
 provided since Python 2.7.9 and 3.4.
 
-TLS parameters are controlled by passing a ``ssl.SSLContext``
-when creating an IMAPClient instance. When ``ssl=True`` is used
-without passing a SSLContext, a default context is used. The default
-context avoids the use of known insecure ciphers and SSL protocol
-versions, with certificate verification and hostname verification
-turned on. The default context will use system installed certificate
-authority trust chains, if available.
+TLS parameters are controlled by passing a ``ssl.SSLContext`` when
+creating an IMAPClient instance (or to the `starttls` method when the
+STARTTLS is used). When ``ssl=True`` is used without passing a
+SSLContext, a default context is used. The default context avoids the
+use of known insecure ciphers and SSL protocol versions, with
+certificate verification and hostname verification turned on. The
+default context will use system installed certificate authority trust
+chains, if available.
 
 When constructing a custom context it is usually best to start with
 the default context, created by the ``ssl`` module, and modify it to
@@ -109,7 +110,7 @@ certificate used by the IMAP server.
 
 If your operating system comes with an outdated list of CA certificates you can
 use the `certifi <https://pypi.python.org/pypi/certifi>`_ package that provides
-a list of common and respectable CAs::
+an up-to-date set of trusted CAs::
 
   import certifi
 
@@ -121,11 +122,11 @@ the Python 3 :py:mod:`ssl` package documentation for further options.
 
 Logging
 ~~~~~~~
-IMAPClient logs debug lines using the standard Python `logging module
-<https://docs.python.org/3/library/logging.html>`_. Its logger is
-``imapclient.*``.
+IMAPClient logs debug lines using the standard Python :py:mod:`logging`
+module. Its logger prefix is ``imapclient.``.
 
-A simple way to display log messages is to setup logging::
+One way to see debug messages from IMAPClient is to set up logging
+like this::
 
   import logging
 
@@ -134,4 +135,5 @@ A simple way to display log messages is to setup logging::
       level=logging.DEBUG
   )
 
-For advanced usage please refer to the Python documentation.
+For advanced usage, please refer to the documentation ``logging``
+module.

doc/src/index.rst

@@ -69,7 +69,7 @@ messages in the INBOX folder.
     >>>     print('ID #%d: "%s" received %s' % (msgid, envelope.subject.decode(), envelope.date))
     ID #62: "Our holidays photos" received 2017-07-20 21:47:42
     ID #55: "Re: did you book the hotel?" received 2017-06-26 10:38:09
-    ID #53: "Re: did you book the holel?" received 2017-06-25 22:02:58
+    ID #53: "Re: did you book the hotel?" received 2017-06-25 22:02:58
     ID #44: "See that fun article about lobsters in Pacific ocean!" received 2017-06-09 09:49:47
     ID #46: "Planning for our next vacations" received 2017-05-12 10:29:30
 
@@ -85,7 +85,6 @@ help you start.
     :maxdepth: 2
 
     installation
-    quickstart
     concepts
     advanced