Reformat all the documentation

docs/index.rst

@@ -27,6 +27,7 @@ API Documentation:
 
     api/tensor.rst
     api/protocol.rst
+    api/logs.rst
     api/sources.rst
     api/outputs.rst
 

tensor/logs/follower.py

@@ -3,13 +3,10 @@
 class LogFollower(object):
     """Provides a class for following log files between runs
 
-    **Arguments:**
-
-    :logfile: Full path to logfile
-
-    **Keyword arguments:**
-
-    :parser: Optional parser method for log lines
+    :param logfile: Full path to logfile
+    :type logfile: str
+    :param parser: Optional parser method for log lines
+    :type parser: str
     """
 
     def __init__(self, logfile, parser=None, tmp_path="/var/lib/tensor/"):

tensor/logs/parsers.py

@@ -9,11 +9,10 @@ class ApacheLogParser:
 
     Adapted from http://code.google.com/p/apachelog
 
-    **Arguments:**
-
-    :format: Apache log format definition eg
+    :param format: Apache log format definition eg
              r'%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"'
              or one of 'common', 'vhcommon' or 'combined'
+    :type format: str
     """
     def __init__(self, format):
         formats = {

tensor/objects.py

@@ -13,19 +13,14 @@ class Event(object):
     All sources pass these to the queue, which form a proxy object
     to create protobuf Event objects
 
-    **Arguments:**
-
-    :state: Some sort of string < 255 chars describing the state
-    :service: The service name for this event
-    :description: A description for the event, ie. "My house is on fire!"
-    :metric: int or float metric for this event
-
-    **Keyword arguments:**
-
-    :tags: List of tag strings
-    :hostname: Hostname for the event (defaults to system fqdn)
-    :aggregation: Aggregation function
-    :evtime: Event timestamp override
+    :param state: Some sort of string < 255 chars describing the state
+    :param service: The service name for this event
+    :param description: A description for the event, ie. "My house is on fire!"
+    :param metric: int or float metric for this event
+    :param tags: List of tag strings
+    :param hostname: Hostname for the event (defaults to system fqdn)
+    :param aggregation: Aggregation function
+    :param evtime: Event timestamp override
     """
     def __init__(self, state, service, description, metric, ttl, tags=[],
             hostname=None, aggregation=None, evtime=None):
@@ -75,19 +70,11 @@ class Output(object):
     Outputs can inherit this object which provides a construct
     for a working output
 
-    **Arguments:**
-
-    :config: Dictionary config for this queue (usually read from the
+    :param config: Dictionary config for this queue (usually read from the
              yaml configuration)
-    :tensor: A TensorService object for interacting with the queue manager
+    :param tensor: A TensorService object for interacting with the queue manager
     """
     def __init__(self, config, tensor):
-        """Consturct a Output object
-
-        Arguments:
-        config -- Dictionary config for this output
-        tensor -- A TensorService object for interacting with the queue manager
-        """
         self.config = config
         self.tensor = tensor
 
@@ -115,25 +102,15 @@ class Source(object):
     Sources can inherit this object which provides a number of
     utility methods.
 
-    **Arguments:**
-
-    :config: Dictionary config for this queue (usually read from the
+    :param config: Dictionary config for this queue (usually read from the
              yaml configuration)
-    :queueBack: A callback method to recieve a list of Event objects
-    :tensor: A TensorService object for interacting with the queue manager
+    :param queueBack: A callback method to recieve a list of Event objects
+    :param tensor: A TensorService object for interacting with the queue manager
     """
 
     sync = False
 
     def __init__(self, config, queueBack, tensor):
-        """Consturct a Source object
-
-        Arguments:
-        config -- Dictionary config for this source
-        queueBack -- Callback method for events originating from this source
-                     called on config['interval']
-        tensor -- A TensorService object for interacting with the queue manager
-        """
         self.config = config
         self.t = task.LoopingCall(self.tick)
 

tensor/outputs/riemann.py

@@ -11,15 +11,15 @@ class RiemannTCP(Output):
 
     **Configuration arguments:**
 
-    :server: Riemann server hostname (default: localhost)
+    :param server: Riemann server hostname (default: localhost)
     :type server: str.
-    :port: Riemann server port (default: 5555)
+    :param port: Riemann server port (default: 5555)
     :type port: int.
-    :maxrate: Maximum de-queue rate (0 is no limit)
+    :param maxrate: Maximum de-queue rate (0 is no limit)
     :type maxrate: int.
-    :interval: De-queue interval in seconds (default: 1.0)
+    :param interval: De-queue interval in seconds (default: 1.0)
     :type interval: float.
-    :pressure: Maximum backpressure (-1 is no limit)
+    :param pressure: Maximum backpressure (-1 is no limit)
     :type pressure: int.
     """
     def __init__(self, *a):
@@ -109,9 +109,9 @@ class RiemannUDP(Output):
 
     **Configuration arguments:**
 
-    :server: Riemann server IP address (default: 127.0.0.1)
+    :param server: Riemann server IP address (default: 127.0.0.1)
     :type server: str.
-    :port: Riemann server port (default: 5555)
+    :param port: Riemann server port (default: 5555)
     :type port: int.
     """
 

tensor/sources/media/libav.py

@@ -15,7 +15,7 @@ class DarwinRTSP(Source):
 
     **Configuration arguments:**
 
-    :destination: Host name or IP address to check
+    :param destination: Host name or IP address to check
     :type method: str.
 
     **Metrics:**

tensor/sources/munin.py

@@ -61,15 +61,15 @@ class MuninNode(Source):
 
     **Configuration arguments:**
     
-    :host: munin-node hostname (probably localhost)
+    :param host: munin-node hostname (probably localhost)
     :type host: str.
-    :port: munin-node port (probably 4949)
+    :param port: munin-node port (probably 4949)
     :type port: int.
     
     **Metrics:**
 
-    :(service name).(plugin name).(keys...): A dot separated tree of munin
-                                             plugin keys
+    :(service name).(plugin name).(keys...): A dot separated tree of
+                                             munin plugin keys
     """
 
     implements(ITensorSource)

tensor/sources/network.py

@@ -24,11 +24,11 @@ class HTTP(Source):
 
     **Configuration arguments:**
     
-    :method: HTTP request method to use
+    :param method: HTTP request method to use
     :type method: str.
-    :match: A text string to match in the document when it is correct
+    :param match: A text string to match in the document when it is correct
     :type match: str.
-    :useragent: User-Agent header to use
+    :param useragent: User-Agent header to use
     :type useragent: str.
 
     **Metrics:**
@@ -84,8 +84,8 @@ class Ping(Source):
 
     **Configuration arguments:**
     
-    :destination: Host name or IP address to ping
-    :type method: str.
+    :param destination: Host name or IP address to ping
+    :type destination: str.
 
     **Metrics:**
 

tensor/sources/nginx.py

@@ -26,7 +26,7 @@ class Nginx(Source):
 
     **Configuration arguments:**
     
-    :stats_url: URL to fetch stub_status from
+    :param stats_url: URL to fetch stub_status from
     :type stats_url: str.
 
     **Metrics:**
@@ -99,14 +99,16 @@ class NginxLogMetrics(Source):
 
     **Configuration arguments:**
     
-    :log_format: Log format passed to parser, same as the config definition
+    :param log_format: Log format passed to parser, same as the config
+                       definition
     :type log_format: str.
-    :file: Log file
+    :param file: Log file
     :type file: str.
-    :max_lines: Maximum number of log lines to read per interval to prevent
-                overwhelming Tensor when reading large logs (default 2000)
+    :param max_lines: Maximum number of log lines to read per interval to
+                      prevent overwhelming Tensor when reading large logs
+                      (default 2000)
     :type max_lines: int.
-    :resolution: Aggregate bucket resolution in seconds (default 10)
+    :param resolution: Aggregate bucket resolution in seconds (default 10)
     :type resolution: int.
 
     **Metrics:**

tensor/sources/rabbitmq.py

@@ -14,7 +14,7 @@ class Queues(Source):
 
     **Configuration arguments:**
 
-    :vhost: Vhost name
+    :param vhost: Vhost name
     :type vhost: str.
 
     **Metrics:**

tensor/sources/riak.py

@@ -25,9 +25,9 @@ class RiakStats(Source):
 
     **Configuration arguments:**
 
-    :url: Riak stats URL
+    :param url: Riak stats URL
     :type url: str.
-    :useragent: User-Agent header to use
+    :param useragent: User-Agent header to use
     :type useragent: str.
 
     **Metrics:**

tensor/sources/sflow.py

@@ -175,9 +175,9 @@ class sFlow(Source):
 
     **Configuration arguments:**
     
-    :port: UDP port to listen on
+    :param port: UDP port to listen on
     :type port: int.
-    :dnslookup: Enable reverse DNS lookup for device IPs (default: True)
+    :param dnslookup: Enable reverse DNS lookup for device IPs (default: True)
     :type dnslookup: bool.
 
     **Metrics:**

tensor/sources/snmp.py

@@ -26,14 +26,14 @@
 class SNMPConnection(object):
     """A wrapper class for PySNMP functions
 
-    **Arguments:**
-
-    :host: SNMP agent host
+    :param host: SNMP agent host
     :type host: str.
-    :port: SNMP port
+    :param port: SNMP port
     :type port: int.
-    :community: SNMP read community
+    :param community: SNMP read community
     :type community: str.
+
+    (This is not a source and you shouldn't try to use it as one)
     """
 
     def __init__(self, host, port, community):
@@ -100,11 +100,11 @@ class SNMP(Source):
 
     **Configuration arguments:**
 
-    :ip: SNMP agent host (default: 127.0.0.1)
+    :param ip: SNMP agent host (default: 127.0.0.1)
     :type ip: str.
-    :port: SNMP port (default: 161)
+    :param port: SNMP port (default: 161)
     :type port: int.
-    :community: SNMP read community
+    :param community: SNMP read community
     :type community: str.
     """
 
@@ -182,11 +182,11 @@ class SNMPCisco837(SNMP):
 
     **Configuration arguments:**
 
-    :ip: SNMP agent host (default: 127.0.0.1)
+    :param ip: SNMP agent host (default: 127.0.0.1)
     :type ip: str.
-    :port: SNMP port (default: 161)
+    :param port: SNMP port (default: 161)
     :type port: int.
-    :community: SNMP read community
+    :param community: SNMP read community
     :type community: str.
     """
 

tensor/utils.py

@@ -8,6 +8,9 @@
 
 
 class Resolver(object):
+    """Helper class for DNS resolution
+    """
+
     def __init__(self):
         self.recs = {}
 
@@ -93,18 +96,13 @@ def fork(executable, args=(), env={}, path=None, timeout=3600):
     """fork
     Provides a deferred wrapper function with a timeout function
 
-    **Arguments:**
-
-    :executable: Executable
+    :param executable: Executable
     :type executable: str.
-
-    **Keyword arguments:**
-
-    :args: Tupple of arguments
+    :param args: Tupple of arguments
     :type args: tupple.
-    :env: Environment dictionary
+    :param env: Environment dictionary
     :type env: dict.
-    :timeout: Kill the child process if timeout is exceeded
+    :param timeout: Kill the child process if timeout is exceeded
     :type timeout: int.
     """
     d = defer.Deferred()