Some additional documentation

docs/connection.rst

@@ -18,7 +18,7 @@ For example if you wanted to use your own implementation of the
 Transport
 ---------
 
-.. autoclass:: Transport(hosts, connection_class=Urllib3HttpConnection, connection_pool_class=ConnectionPool, nodes_to_host_callback=construct_hosts_list, sniff_on_start=False, sniff_after_requests=None, sniff_on_connection_fail=False, serializer=JSONSerializer(), max_retries=3, ** kwargs)
+.. autoclass:: Transport(hosts, connection_class=Urllib3HttpConnection, connection_pool_class=ConnectionPool, nodes_to_host_callback=construct_hosts_list, sniff_on_start=False, sniffer_timeout=None, sniff_on_connection_fail=False, serializer=JSONSerializer(), max_retries=3, ** kwargs)
    :members:
 
 

docs/index.rst

@@ -56,14 +56,29 @@ allow for maximum flexibility. This means that there are no opinions in this
 client; it also means that some of the APIs are a little cumbersome to use from
 Python. We have created some :ref:`helpers` to help with this issue.
 
-Extendability
+Persistent Connections
-~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~
 
-Configurable connections and load balancing (see :ref:`connection_api`)::
+``elasticsearch-py`` uses persistent connections inside of individual connection
- * persistent connections
+pools (one per each configured or sniffed node). Out of the box you can choose
- * configurable load balancing strategy
+to use ``http``, ``thrift`` or an experimental ``memcached`` protocol to
- * different protocols and connection classes
+communicate with the elasticsearch nodes. See :ref:`transports` for more
- * ...
+information.
+
+The transport layer will create an instance of the selected connection class
+per node and keep track of the health of individual nodes - if a node becomes
+unresponsive (throwing exceptions while connecting to it) it's put on a timeout
+by the :class:`~elasticsearch.ConnectionPool` class and only returned to the
+circulation after the timeout is over (or when no live nodes are left). By
+default node are randomized before passed into the pool and round-robin
+strategy is used for load balancing.
+
+You can customize this behavior by passing parameters to the
+:ref:`connection_api` (all keyword arguments to the
+:class:`~elasticsearch.Elasticsearch` class will be passed through). If what
+you want to accomplish is not supported you should be able to create a subclass
+of the relevant component and pass it in as a parameter to be used instead of
+the default implementation.
 
 
 Sniffing
@@ -73,6 +88,34 @@ The client can be configured to inspect the cluster state to get a list of
 nodes upon startup, periodically and/or on failure. See
 :class:`~elasticsearch.Transport` parameters for details.
 
+Some example configurations::
+
+    from elasticsearch import Elasticsearch
+
+    # by default we don't sniff, ever
+    es = Elasticsearch()
+
+    # you can specify to sniff on startup to inspect the cluster and load
+    # balance across all nodes
+    es = Elasticsearch(["seed1", "seed2"], sniff_on_start=True)
+
+    # you can also sniff periodically and/or after failure:
+    es = Elasticsearch(["seed1", "seed2"], sniff_on_start=True, sniff_on_connection_fail=True, sniffer_timeout=60)
+
+
+Logging
+~~~~~~~
+
+``elasticsearch-py`` uses the standard `logging library`_ from python to define
+two loggers: ``elasticsearch`` and ``elasticsearch.trace``. ``elasticsearch``
+is used by the client to log standard activity, depending on the log level.
+``elasticsearch.trace`` can be used to log requests to the server in the form
+of ``curl`` commands using pretty-printed json that can then be executed from
+command line. The tace logger doesn't inherit from the base one - it needs to
+be activated separately.
+
+.. _logging library: http://docs.python.org/3.3/library/logging.html
+
 Contents
 --------
 

docs/transports.rst

@@ -1,3 +1,5 @@
+.. _transports:
+
 Transport classes
 =================
 
@@ -7,6 +9,14 @@ it to the constructor of :class:`~elasticsearch.Elasticsearch` as
 and require a plugin to be installed in your cluster as well as additional
 dependencies (`thrift==0.9` and `pylibmc==1.2`).
 
+For example to use the thrift connection just import it and use it. The
+connection classes are aware of their respective default ports (9500 for
+thrift) so there is no need to specify them unless modified::
+
+    from elasticsearch import Elasticsearch, ThriftConnection
+    es = Elasticsearch(connection_class=ThriftConnection)
+
+
 .. py:module:: elasticsearch.connection
 
 Connection