Fix wrapping in reference docs

1 files changed, 139 insertions, 147 deletions

diff --git a/docs/reference.rst b/docs/reference.rst
index 282126b..90c7975 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -4,14 +4,14 @@
 API Reference
 =============
 
-The ``StatsClient`` provides accessors for all the types of data the
-statsd_ server supports.
+The ``StatsClient`` provides accessors for all the types of data the statsd_
+server supports.
 
 .. note::
 
-    Each public stats API method supports a ``rate`` parameter, but
-    statsd doesn't always use it the same way. See the
-    :ref:`types-chapter` for more information.
+    Each public stats API method supports a ``rate`` parameter, but statsd
+    doesn't always use it the same way. See the :ref:`types-chapter` for more
+    information.
 
 
 .. _StatsClient:
@@ -21,17 +21,17 @@ statsd_ server supports.
 
 .. py:class:: StatsClient(host='localhost', port=8125, prefix=None, maxudpsize=512)
 
-   Create a new ``StatsClient`` instance with the appropriate connection
-   and prefix information.
+    Create a new ``StatsClient`` instance with the appropriate connection and
+    prefix information.
 
-   :param str host: the hostname or IP address of the statsd_ server
-   :param int port: the port of the statsd server
-   :param prefix: a prefix to distinguish and group stats from an
-       application or environment
-   :type prefix: str or None
-   :param int maxudpsize: the largest safe UDP packet to send. 512 is
-       generally considered safe for the public internet, but private
-       networks may support larger packet sizes.
+    :param str host: the hostname or IP address of the statsd_ server
+    :param int port: the port of the statsd server
+    :param prefix: a prefix to distinguish and group stats from an application
+        or environment
+    :type prefix: str or None
+    :param int maxudpsize: the largest safe UDP packet to send. 512 is
+        generally considered safe for the public internet, but private networks
+        may support larger packet sizes.
 
 .. _incr:
 
@@ -40,15 +40,14 @@ statsd_ server supports.
 
 .. py:method:: StatsClient.incr(stat, count=1, rate=1)
 
-   Increment a :ref:`counter <counter-type>`.
+    Increment a :ref:`counter <counter-type>`.
 
-   :param str stat: the name of the counter to increment
-   :param int count: the amount to increment by. Typically an integer.
-       May be negative, but see also :py:meth:`decr()
-       <StatsClient.decr()>`.
-   :param float rate: a sample rate, a float between 0 and 1. Will only
-       send data this percentage of the time. The statsd server will
-       take the sample rate into account for counters.
+    :param str stat: the name of the counter to increment
+    :param int count: the amount to increment by. Typically an integer.  May be
+        negative, but see also :py:meth:`decr() <StatsClient.decr()>`.
+    :param float rate: a sample rate, a float between 0 and 1. Will only send
+        data this percentage of the time. The statsd server will take the
+        sample rate into account for counters.
 
 
 .. _decr:
@@ -58,15 +57,15 @@ statsd_ server supports.
 
 .. py:method:: StatsClient.decr(stat, count=1, rate=1)
 
-   Decrement a :ref:`counter <counter-type>`.
+    Decrement a :ref:`counter <counter-type>`.
 
-   :param str stat: the name of the counter to increment
-   :param int count: the amount to increment by. Typically an integer.
-       May be negative, but that will have the impact of incrementing
-       the counter but see also :py:meth:`incr() <StatsClient.incr()>`.
-   :param float rate: a sample rate, a float between 0 and 1. Will only
-       send data this percentage of the time. The statsd server will
-       take the sample rate into account for counters
+    :param str stat: the name of the counter to increment
+    :param int count: the amount to increment by. Typically an integer.  May be
+        negative, but that will have the impact of incrementing the counter but
+        see also :py:meth:`incr() <StatsClient.incr()>`.
+    :param float rate: a sample rate, a float between 0 and 1. Will only send
+        data this percentage of the time. The statsd server will take the
+        sample rate into account for counters
 
 
 .. _gauge:
@@ -76,23 +75,20 @@ statsd_ server supports.
 
 .. py:method:: StatsClient.gauge(stat, value, rate=1, delta=False)
 
-   Set a :ref:`gauge <gauge-type>` value.
+    Set a :ref:`gauge <gauge-type>` value.
 
-   :param str stat: the name of the gauge to set
-   :param value: the current value of the gauge
-   :type value: int or float
-   :param float rate: a sample rate, a float between 0 and 1. Will only
-       send data this percentage of the time. The statsd server does
-       *not* take the sample rate into account for gauges. Use with care
-   :param bool delta: whether or not to consider this a delta value or
-       an absolute value. See the :ref:`gauge <gauge-type>` type for
-       more detail
+    :param str stat: the name of the gauge to set
+    :param value: the current value of the gauge
+    :type value: int or float
+    :param float rate: a sample rate, a float between 0 and 1. Will only send
+        data this percentage of the time. The statsd server does *not* take the
+        sample rate into account for gauges. Use with care
+    :param bool delta: whether or not to consider this a delta value or an
+        absolute value. See the :ref:`gauge <gauge-type>` type for more detail
 
 .. note::
 
-   Gauges were added to the statsd server in version 0.1.1. If you try
-   to use this method with an older version of the server, the data will
-   not be recorded.
+    Gauges were added to the statsd server in version 0.1.1.
 
 .. note::
 
@@ -106,19 +102,17 @@ statsd_ server supports.
 
 .. py:method:: StatsClient.set(stat, value, rate=1)
 
-   Increment a :ref:`set <set-type>` value.
+    Increment a :ref:`set <set-type>` value.
 
-   :param str stat: the name of the set to update
-   :param value: the unique value to count
-   :param float rate: a sample rate, a float between 0 and 1. Will only
-       send data this percentage of the time. The statsd server does
-       *not* take the sample rate into account for sets. Use with care.
+    :param str stat: the name of the set to update
+    :param value: the unique value to count
+    :param float rate: a sample rate, a float between 0 and 1. Will only send
+        data this percentage of the time. The statsd server does *not* take the
+        sample rate into account for sets. Use with care.
 
 .. note::
 
-   Sets were added to the statsd server in version 0.6.0. If you
-   try to use this method with an older version of the server, the
-   data will not be recorded.
+   Sets were added to the statsd server in version 0.6.0.
 
 
 .. _timing:
@@ -128,15 +122,16 @@ statsd_ server supports.
 
 .. py:method:: StatsClient.timing(stat, delta, rate=1)
 
-   Record :ref:`timer <timer-type>` information.
+    Record :ref:`timer <timer-type>` information.
 
-   :param str stat: the name of the timer to use
-   :param delta: the number of milliseconds whatever action took. 
-       ``datetime.timedelta`` objects will be converted to milliseconds
-   :type delta: int or float or datetime.timedelta
-   :param float rate: a sample rate, a float between 0 and 1. Will only
-       send data this percentage of the time. The statsd server does
-       *not* take the sample rate into account for timers.
+    :param str stat: the name of the timer to use
+    :param delta: the number of milliseconds whatever action took.
+        :py:class:`datetime.timedelta` objects will be converted to
+        milliseconds
+    :type delta: int or float or datetime.timedelta
+    :param float rate: a sample rate, a float between 0 and 1. Will only send
+        data this percentage of the time. The statsd server does *not* take the
+        sample rate into account for timers.
 
 
 .. _timer:
@@ -146,15 +141,14 @@ statsd_ server supports.
 
 .. py:method:: StatsClient.timer(stat, rate=1)
 
-   Return a :py:class:`Timer` object that can be used as a context
-   manager or decorator to automatically record timing for a block or
-   function call. See also the :ref:`chapter on timing
-   <timing-chapter>`.
+    Return a :py:class:`Timer` object that can be used as a context manager or
+    decorator to automatically record timing for a block or function call. See
+    also the :ref:`chapter on timing <timing-chapter>`.
 
-   :param str stat: the name of the timer to use
-   :param float rate: a sample rate, a float between 0 and 1. Will only
-       send data this percentage of the time. The statsd server does
-       *not* take the sample rate into account for timers.
+    :param str stat: the name of the timer to use
+    :param float rate: a sample rate, a float between 0 and 1. Will only send
+        data this percentage of the time. The statsd server does *not* take the
+        sample rate into account for timers.
 
 .. code-block:: python
 
@@ -186,13 +180,13 @@ statsd_ server supports.
 
 .. py:class:: Timer()
 
-   The :ref:`Timer objects <timer-object>` returned by
-   :py:meth:`StatsClient.timer()`. These should never be
-   instantiated directly.
+    The :ref:`Timer objects <timer-object>` returned by
+    :py:meth:`StatsClient.timer()`. These should never be instantiated
+    directly.
 
-:py:class:`Timer` objects should not be shared between threads (except
-when used as decorators, which is thread-safe) but could be used within
-another context manager or decorator. For example:
+:py:class:`Timer` objects should not be shared between threads (except when
+used as decorators, which is thread-safe) but could be used within another
+context manager or decorator. For example:
 
 .. code-block:: python
 
@@ -216,9 +210,9 @@ another context manager or decorator. For example:
 
 .. py:method:: Timer.start()
 
-   Causes a timer object to start counting. Called automatically when
-   the object is used as a decorator or context manager. Returns the
-   timer object for simplicity.
+    Causes a timer object to start counting. Called automatically when the
+    object is used as a decorator or context manager. Returns the timer object
+    for simplicity.
 
 
 .. _timer-stop:
@@ -228,16 +222,15 @@ another context manager or decorator. For example:
 
 .. py:method:: Timer.stop(send=True)
 
-   Causes the timer object to stop timing and send the results to
-   statsd_.  Can be called with ``send=False`` to prevent immediate
-   sending immediately, and use :py:meth:`send() <Timer.send()>`. Called
-   automatically when the object is used as a decorator or context
-   manager. Returns the timer object.
+    Causes the timer object to stop timing and send the results to statsd_.
+    Can be called with ``send=False`` to prevent immediate sending immediately,
+    and use :py:meth:`send() <Timer.send()>`. Called automatically when the
+    object is used as a decorator or context manager. Returns the timer object.
 
-   If ``stop()`` is called before :py:meth:`start() <Timer.start()>`, a
-   ``RuntimeError`` is raised.
+    If ``stop()`` is called before :py:meth:`start() <Timer.start()>`, a
+    ``RuntimeError`` is raised.
 
-   :param bool send: Whether to automatically send the results
+    :param bool send: Whether to automatically send the results
 
 .. code-block:: python
 
@@ -252,9 +245,8 @@ another context manager or decorator. For example:
 
 .. py:method:: Timer.send()
 
-   Causes the timer to send any unsent data. If the data has already
-   been sent, or has not yet been recorded, a ``RuntimeError`` is
-   raised.
+    Causes the timer to send any unsent data. If the data has already been
+    sent, or has not yet been recorded, a ``RuntimeError`` is raised.
 
 .. code-block:: python
 
@@ -264,8 +256,7 @@ another context manager or decorator. For example:
 
 .. note::
 
-   See the note abbout :ref:`timer objects and pipelines
-   <timer-direct-note>`.
+    See the note abbout :ref:`timer objects and pipelines <timer-direct-note>`.
 
 
 .. _pipeline:
@@ -275,11 +266,19 @@ another context manager or decorator. For example:
 
 .. py:method:: StatsClient.pipeline()
 
-   Returns a :py:class:`Pipeline` object for collecting several stats.
-   Can also be used as a context manager::
+    Returns a :py:class:`Pipeline` object for collecting several stats.  Can
+    also be used as a context manager.
 
-    with StatsClient().pipeline() as pipe:
-        pipe.incr('foo')
+.. code-block:: python
+
+    pipe = StatsClient().pipeline()
+    pipe.incr('foo')
+    pipe.send()
+
+    # or
+
+    with StatsClient().pipeline as pipe:
+        pipe.incr('bar')
 
 
 .. _Pipeline:
@@ -289,13 +288,12 @@ another context manager or decorator. For example:
 
 .. py:class:: Pipeline()
 
-   A :ref:`Pipeline <pipeline-chapter>` object that can be used to
-   collect and send several stats at once. Useful for reducing network
-   traffic and speeding up instrumentation under certain loads. Can be
-   used as a context manager.
+    A :ref:`Pipeline <pipeline-chapter>` object that can be used to collect and
+    send several stats at once. Useful for reducing network traffic and
+    speeding up instrumentation under certain loads. Can be used as a context
+    manager.
 
-   Pipeline extends :py:class:`StatsClient` and has all associated
-   methods.
+    Pipeline extends :py:class:`StatsClient` and has all associated methods.
 
 .. code-block:: python
 
@@ -303,10 +301,11 @@ another context manager or decorator. For example:
     pipe.incr('foo')
     pipe.send()
 
+    # or
+
     with StatsClient().pipeline as pipe:
         pipe.incr('bar')
 
-
 .. _pipeline-send:
 
 ``send``
@@ -314,13 +313,8 @@ another context manager or decorator. For example:
 
 .. py:method:: Pipeline.send()
 
-   Causes the :py:class:`Pipeline` object to send all batched stats in
-   as few packets as possible.
-
-.. note::
-
-   This method is not implemented on the base :py:class:`StatsClient`
-   class.
+    Causes the :py:class:`Pipeline` object to send all batched stats in as few
+    packets as possible.
 
 
 .. _TCPStatsClient:
@@ -330,26 +324,25 @@ another context manager or decorator. For example:
 
 .. py:class:: TCPStatsClient(host='localhost', port=8125, prefix=None, timeout=None, ipv6=False)
 
-   Create a new ``TCPStatsClient`` instance with the appropriate connection
-   and prefix information.
+    Create a new ``TCPStatsClient`` instance with the appropriate connection
+    and prefix information.
 
-   :param str host: the hostname or IP address of the statsd_ server
-   :param int port: the port of the statsd server
-   :param prefix: a prefix to distinguish and group stats from an
-       application or environment.
-   :type prefix: str or None
-   :param float timeout: socket timeout for any actions on the
-       connection socket.
+    :param str host: the hostname or IP address of the statsd_ server
+    :param int port: the port of the statsd server
+    :param prefix: a prefix to distinguish and group stats from an application
+        or environment.
+    :type prefix: str or None
+    :param float timeout: socket timeout for any actions on the connection
+        socket.
 
 
-``TCPStatsClient`` implements all methods of :py:class:`StatsClient`,
-including :py:meth:`pipeline() <StatsClient.pipeline>`, with the
-difference that it is not thread safe and it can raise exceptions on
-connection errors. Unlike :py:class:`StatsClient` it uses a TCP
-connection to communicate with StatsD.
+``TCPStatsClient`` implements all methods of :py:class:`StatsClient`, including
+:py:meth:`pipeline() <StatsClient.pipeline>`, with the difference that it is
+not thread safe and it can raise exceptions on connection errors. Unlike
+:py:class:`StatsClient` it uses a TCP connection to communicate with StatsD.
 
-In addition to the stats methods, ``TCPStatsClient`` supports the
-following TCP-specific methods.
+In addition to the stats methods, ``TCPStatsClient`` supports the following
+TCP-specific methods.
 
 
 .. _tcp_close:
@@ -359,9 +352,9 @@ following TCP-specific methods.
 
 .. py:method:: TCPStatsClient.close()
 
-   Closes a connection that's currently open and deletes it's socket. If
-   this is called on a :py:class:`TCPStatsClient` which currently has no
-   open connection it is a non-action.
+    Closes a connection that's currently open and deletes it's socket. If this
+    is called on a :py:class:`TCPStatsClient` which currently has no open
+    connection it is a non-action.
 
 .. code-block:: python
 
@@ -379,12 +372,11 @@ following TCP-specific methods.
 
 .. py:method:: TCPStatsClient.connect()
 
-   Creates a connection to StatsD. If there are errors like connection
-   timed out or connection refused, the according exceptions will be
-   raised. It is usually not necessary to call this method because
-   sending data to StatsD will call ``connect`` implicitely if the
-   current instance of :py:class:`TCPStatsClient` does not already hold
-   an open connection.
+    Creates a connection to StatsD. If there are errors like connection timed
+    out or connection refused, the according exceptions will be raised. It is
+    usually not necessary to call this method because sending data to StatsD
+    will call ``connect`` implicitely if the current instance of
+    :py:class:`TCPStatsClient` does not already hold an open connection.
 
 .. code-block:: python
 
@@ -403,11 +395,11 @@ following TCP-specific methods.
 
 .. py:method:: TCPStatsClient.reconnect()
 
-   Closes a currently existing connection and replaces it with a new
-   one.  If no connection exists already it will simply create a new
-   one.  Internally this does nothing else than calling
-   :py:meth:`close() <TCPStatsClient.close()>` and :py:meth:`connect()
-   <TCPStatsClient.connect()>`.
+    Closes a currently existing connection and replaces it with a new one.  If
+    no connection exists already it will simply create a new one.  Internally
+    this does nothing else than calling :py:meth:`close()
+    <TCPStatsClient.close()>` and :py:meth:`connect()
+    <TCPStatsClient.connect()>`.
 
 .. code-block:: python
 
@@ -425,15 +417,15 @@ following TCP-specific methods.
 
 .. py:class:: UnixSocketStatsClient(socket_path, prefix=None, timeout=None)
 
-   A version of :py:class:`StatsClient` that communicates over Unix
-   sockets. It implements all methods of :py:class:`StatsClient`.
+    A version of :py:class:`StatsClient` that communicates over Unix sockets.
+    It implements all methods of :py:class:`StatsClient`.
 
-   :param str socket_path: the path to the (writeable) Unix socket
-   :param prefix: a prefix to distinguish and group stats from an
-       application or environment
-   :type prefix: str or None
-   :param float timeout: socket timeout for any actions on the
-       connection socket.
+    :param str socket_path: the path to the (writeable) Unix socket
+    :param prefix: a prefix to distinguish and group stats from an application
+        or environment
+    :type prefix: str or None
+    :param float timeout: socket timeout for any actions on the connection
+        socket.
 
 
 .. _statsd: https://github.com/etsy/statsd