document classes properly

doc/conf.py

@@ -40,5 +40,4 @@
 pygments_style = 'sphinx'
 htmlhelp_basename = 'pykafkadoc'
 
-autodoc_default_flags = ['special-members', 'private-members', 'undoc-members',
-                         'show-inheritance']
+autodoc_default_flags = ['special-members', 'private-members', 'show-inheritance']

pykafka/balancedconsumer.py

@@ -35,6 +35,11 @@
 
 
 class BalancedConsumer():
+    """
+    Maintains a single instance of SimpleConsumer, periodically using the
+    consumer rebalancing algorithm to reassign partitions to this
+    SimpleConsumer.
+    """
     def __init__(self,
                  topic,
                  cluster,
@@ -59,10 +64,6 @@ def __init__(self,
                  auto_start=True):
         """Create a BalancedConsumer instance
 
-        Maintains a single instance of SimpleConsumer, periodically using the
-        consumer rebalancing algorithm to reassign partitions to this
-        SimpleConsumer.
-
         :param topic: The topic this consumer should consume
         :type topic: :class:`pykafka.topic.Topic`
         :param cluster: The cluster to which this consumer should connect

pykafka/broker.py

@@ -36,6 +36,10 @@
 
 
 class Broker(base.BaseBroker):
+    """
+    A Broker is an abstraction over a real kafka server instance.
+    It is used to perform requests to these servers.
+    """
     def __init__(self,
                  id_,
                  host,
@@ -46,9 +50,6 @@ def __init__(self,
                  buffer_size=64 * 1024):
         """Create a Broker instance.
 
-        A Broker is an abstraction over a real kafka server instance.
-        It is used to perform requests to these servers.
-
         :param id_: The id number of this broker
         :type id_: int
         :param host: The host address to which to connect. An IP address or a

pykafka/client.py

@@ -32,6 +32,9 @@
 
 
 class KafkaClient(object):
+    """
+    A high-level pythonic client for Kafka
+    """
     def __init__(self,
                  hosts='127.0.0.1:9092',
                  use_greenlets=False,

pykafka/cluster.py

@@ -69,6 +69,10 @@ def _create_topic(self, topic_name):
 
 
 class Cluster(object):
+    """
+    A Cluster is a high-level abstraction of the collection of brokers and
+    topics that makes up a real kafka cluster.
+    """
     def __init__(self,
                  hosts,
                  handler,
@@ -78,9 +82,6 @@ def __init__(self,
                  exclude_internal_topics=True):
         """Create a new Cluster instance.
 
-        A Cluster is a high-level abstraction of the collection of brokers and
-        topics that makes up a real kafka cluster.
-
         :param hosts: Comma-separated list of kafka hosts to used to connect.
         :type hosts: str
         :param handler: The concurrency handler for network requests.

pykafka/connection.py

@@ -29,13 +29,14 @@
 
 
 class BrokerConnection(object):
+    """
+    BrokerConnection thinly wraps a `socket.create_connection` call
+    and handles the sending and receiving of data that conform to the
+    kafka binary protocol over that socket.
+    """
     def __init__(self, host, port, buffer_size=64 * 1024):
         """Initialize a socket connection to Kafka.
 
-        BrokerConnection thinly wraps a `socket.create_connection` call
-        and handles the sending and receiving of data that conform to the
-        kafka binary protocol over that socket.
-
         :param host: The host to which to connect
         :type host: str
         :param port: The port on the host to which to connect

pykafka/partition.py

@@ -27,13 +27,14 @@
 
 
 class Partition(base.BasePartition):
+    """
+    A Partition is an abstraction over the kafka concept of a partition.
+    A kafka partition is a logical division of the logs for a topic. Its
+    messages are totally ordered.
+    """
     def __init__(self, topic, id_, leader, replicas, isr):
         """Instantiate a new Partition
 
-        A Partition is an abstraction over the kafka concept of a partition.
-        A kafka partition is a logical division of the logs for a topic. Its
-        messages are totally ordered.
-
         :param topic: The topic to which this Partition belongs
         :type topic: :class:`pykafka.topic.Topic`
         :param id_: The identifier for this partition

pykafka/producer.py

@@ -55,6 +55,10 @@ def __init__(self,
 
 
 class Producer(base.BaseProducer):
+    """
+    This class implements the synchronous producer logic found in the
+    JVM driver.
+    """
     def __init__(self,
                  cluster,
                  topic,
@@ -68,9 +72,6 @@ def __init__(self,
                  batch_size=200):
         """Instantiate a new Producer.
 
-        This class implements the synchronous producer logic found in the
-        JVM driver.
-
         :param cluster: The cluster to which to connect
         :type cluster: :class:`pykafka.cluster.Cluster`
         :param topic: The topic to which to produce messages

pykafka/simpleconsumer.py

@@ -36,6 +36,9 @@
 
 
 class SimpleConsumer(base.BaseSimpleConsumer):
+    """
+    A non-balancing consumer for Kafka
+    """
     def __init__(self,
                  topic,
                  cluster,

pykafka/topic.py

@@ -34,12 +34,13 @@
 
 
 class Topic(BaseTopic):
+    """
+    A Topic is an abstraction over the kafka concept of a topic.
+    It contains a dictionary of partitions that comprise it.
+    """
     def __init__(self, cluster, topic_metadata):
         """Create the Topic from metadata.
 
-        A Topic is an abstraction over the kafka concept of a topic.
-        It contains a dictionary of partitions that comprise it.
-
         :param cluster: The Cluster to use
         :type cluster: :class:`pykafka.cluster.Cluster`
         :param topic_metadata: Metadata for all topics.