collectd-python(5): Improve formatting of the classes.

diff --git a/src/collectd-python.pod b/src/collectd-python.pod
index f6c42eb22da465e0779a0dbf6d439e640d11137c..785e7e78f84720f60653c6eba6f35d8399765c15 100644 (file)
--- a/src/collectd-python.pod
+++ b/src/collectd-python.pod
@@ -186,190 +186,226 @@ collectd you're done.
 The following complex types are used to pass values between the Python plugin
 and collectd:
 
-=over 4
-
-=item Config
+=head2 Config
 
 The Config class is an object which keeps the informations provided in the
 configuration file. The sequence of children keeps one entry for each
 configuration option. Each such entry is another Config instance, which
 may nest further if nested blocks are used.
 
-class Config(object)
- |  This represents a piece of collectd's config file.
- |  It is passed to scripts with config callbacks (see B<register_config>)
- |  and is of little use if created somewhere else.
- |
- |  It has no methods beyond the bare minimum and only exists for its
- |  data members
- |
- |  ----------------------------------------------------------------------
- |  Data descriptors defined here:
- |
- |  parent
- |      This represents the parent of this node. On the root node
- |      of the config tree it will be None.
- |
- |  key
- |      This is the keyword of this item, ie the first word of any
- |      given line in the config file. It will always be a string.
- |
- |  values
- |      This is a tuple (which might be empty) of all value, ie words
- |      following the keyword in any given line in the config file.
- |
- |      Every item in this tuple will be either a string or a float or a bool,
- |      depending on the contents of the configuration file.
- |
- |  children
- |      This is a tuple of child nodes. For most nodes this will be
- |      empty. If this node represents a block instead of a single line of the config
- |      file it will contain all nodes in this block.
+ class Config(object)
 
+This represents a piece of collectd's config file. It is passed to scripts with
+config callbacks (see B<register_config>) and is of little use if created
+somewhere else.
 
-=item PluginData
+It has no methods beyond the bare minimum and only exists for its data members.
+
+Data descriptors defined here:
+
+=over 4
+ 
+=item parent
+
+This represents the parent of this node. On the root node
+of the config tree it will be None.
+ 
+=item key
+
+This is the keyword of this item, ie the first word of any given line in the
+config file. It will always be a string.
+ 
+=item values
+
+This is a tuple (which might be empty) of all value, ie words following the
+keyword in any given line in the config file.
+
+Every item in this tuple will be either a string or a float or a bool,
+depending on the contents of the configuration file.
+ 
+=item children
+
+This is a tuple of child nodes. For most nodes this will be empty. If this node
+represents a block instead of a single line of the config file it will contain
+all nodes in this block.
+
+=back
+
+=head2 PluginData
 
 This should not be used directly but it is the base class for both Values and
 Notification. It is used to identify the source of a value or notification.
 
-class PluginData(object)
- |  This is an internal class that is the base for Values
- |  and Notification. It is pretty useless by itself and was therefore not
- |  exported to the collectd module.
- |
- |  ----------------------------------------------------------------------
- |  Data descriptors defined here:
- |
- |  host
- |      The hostname of the host this value was read from.
- |      For dispatching this can be set to an empty string which means
- |      the local hostname as defined in collectd.conf.
- |
- |  plugin
- |      The name of the plugin that read the data. Setting this
- |      member to an empty string will insert "python" upon dispatching.
- |
- |  plugin_instance
- |
- |  time
- |      This is the Unix timestap of the time this value was read.
- |      For dispatching values this can be set to 0 which means "now".
- |      This means the time the value is actually dispatched, not the time
- |      it was set to 0.
- |
- |  type
- |      The type of this value. This type has to be defined
- |      in your types.db. Attempting to set it to any other value will
- |      raise a TypeError exception.
- |      Assigning a type is mandetory, calling dispatch without doing
- |      so will raise a RuntimeError exception.
- |
- |  type_instance
+ class PluginData(object)
 
+This is an internal class that is the base for Values and Notification. It is
+pretty useless by itself and was therefore not exported to the collectd module.
 
-=item Values
+Data descriptors defined here:
+
+=over 4
+
+=item host
+
+The hostname of the host this value was read from. For dispatching this can be
+set to an empty string which means the local hostname as defined in
+collectd.conf.
+
+=item plugin
+
+The name of the plugin that read the data. Setting this member to an empty
+string will insert "python" upon dispatching.
+
+=item plugin_instance
+
+Plugin instance string. May be empty.
+
+=item time
+
+This is the Unix timestamp of the time this value was read. For dispatching
+values this can be set to zero which means "now". This means the time the value
+is actually dispatched, not the time it was set to 0.
+
+=item type
+
+The type of this value. This type has to be defined in your I<types.db>.
+Attempting to set it to any other value will raise a I<TypeError> exception.
+Assigning a type is mandatory, calling dispatch without doing so will raise a
+I<RuntimeError> exception.
+
+=item type_instance
+
+Type instance string. May be empty.
+
+=back
+
+=head2 Values
 
 A Value is an object which features a sequence of values. It is based on then
 I<PluginData> type and uses its members to identify the values.
 
-class Values(PluginData)
- |  A Values object used for dispatching values to collectd and receiving
- |  values from write callbacks.
- |  
- |  Method resolution order:
- |      Values
- |      PluginData
- |      object
- |  
- |  Methods defined here:
- |  
- |  dispatch(...)
- |      dispatch([type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.  Dispatch a value list.
- |      
- |      Dispatch this instance to the collectd process. The object has members
- |      for each of the possible arguments for this method. For a detailed
- |      explanation of these parameters see the member of the same same.
- |      
- |      If you do not submit a parameter the value saved in its member will be
- |      submitted. If you do provide a parameter it will be used instead,
- |      without altering the member.
- |  
- |  write(...)
- |      write([destination][, type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.  Dispatch a value list.
- |
- |      Write this instance to a single plugin or all plugins if 'destination' is obmitted.
- |      This will bypass the main collectd process and all filtering and caching.
- |      Other than that it works similar to 'dispatch'. In most cases 'dispatch' should be
- |      used instead of 'write'.
- |
- |  ----------------------------------------------------------------------
- |  Data descriptors defined here:
- |  
- |  interval
- |      The interval is the timespan in seconds between two submits for the
- |      same data source. This value has to be a positive integer, so you can't
- |      submit more than one value per second. If this member is set to a
- |      non-positive value, the default value as specified in the config file
- |      will be used (default: 10).
- |      
- |      If you submit values more often than the specified interval, the average
- |      will be used. If you submit less values, your graphs will have gaps.
- |  
- |  values
- |      These are the actual values that get dispatched to collectd.
- |      It has to be a sequence (a tuple or list) of numbers.
- |      The size of the sequence and the type of its content depend on the type
- |      member your types.db file. For more information on this read the
- |      types.db man page.
- |      
- |      If the sequence does not have the correct size upon dispatch a
- |      RuntimeError exception will be raised. If the content of the sequence
- |      is not a number, a TypeError exception will be raised.
+ class Values(PluginData)
 
+A Values object used for dispatching values to collectd and receiving values
+from write callbacks.
 
-=item Notification
+Method resolution order:
+
+=over 4
+
+=item Values
+
+=item PluginData
+
+=item object
+
+=back
+
+Methods defined here:
+
+=over 4
+
+=item B<dispatch>([type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.
+    
+Dispatch this instance to the collectd process. The object has members for each
+of the possible arguments for this method. For a detailed explanation of these
+parameters see the member of the same same.
+
+If you do not submit a parameter the value saved in its member will be
+submitted. If you do provide a parameter it will be used instead, without
+altering the member.
+
+=item B<write>([destination][, type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.
+
+Write this instance to a single plugin or all plugins if "destination" is
+omitted. This will bypass the main collectd process and all filtering and
+caching. Other than that it works similar to "dispatch". In most cases
+"dispatch" should be used instead of "write".
+
+=back
+
+Data descriptors defined here:
+
+=over 4
+
+=item interval
+
+The interval is the timespan in seconds between two submits for the same data
+source. This value has to be a positive integer, so you can't submit more than
+one value per second. If this member is set to a non-positive value, the
+default value as specified in the config file will be used (default: 10).
+    
+If you submit values more often than the specified interval, the average will
+be used. If you submit less values, your graphs will have gaps.
+
+=item values
+
+These are the actual values that get dispatched to collectd. It has to be a
+sequence (a tuple or list) of numbers. The size of the sequence and the type of
+its content depend on the type member your I<types.db> file. For more
+information on this read the L<types.db(5)> manual page.
+
+If the sequence does not have the correct size upon dispatch a I<RuntimeError>
+exception will be raised. If the content of the sequence is not a number, a
+I<TypeError> exception will be raised.
+
+=back
+
+=head2 Notification
 
 A notification is an object defining the severity and message of the status
 message as well as an identification of a data instance by means of the members
 of PluginData on which it is based.
 
 class Notification(PluginData)
- |  The Notification class is a wrapper around the collectd notification.
- |  It can be used to notify other plugins about bad stuff happening. It works
- |  similar to Values but has a severity and a message instead of interval
- |  and time.
- |  Notifications can be dispatched at any time and can be received with
- |  register_notification.
- |  
- |  Method resolution order:
- |      Notification
- |      PluginData
- |      object
- |  
- |  Methods defined here:
- |  
- |  dispatch(...)
- |      dispatch([type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.  Dispatch a value list.
- |      
- |      Dispatch this instance to the collectd process. The object has members
- |      for each of the possible arguments for this method. For a detailed
- |      explanation of these parameters see the member of the same same.
- |      
- |      If you do not submit a parameter the value saved in its member will be
- |      submitted. If you do provide a parameter it will be used instead,
- |      without altering the member.
- |  
- |  ----------------------------------------------------------------------
- |  Data descriptors defined here:
- |  
- |  message
- |      Some kind of description what's going on and why this Notification
- |      was generated.
- |  
- |  severity
- |      The severity of this notification. Assign or compare to
- |      NOTIF_FAILURE, NOTIF_WARNING or NOTIF_OKAY.
+The Notification class is a wrapper around the collectd notification.
+It can be used to notify other plugins about bad stuff happening. It works
+similar to Values but has a severity and a message instead of interval
+and time.
+Notifications can be dispatched at any time and can be received with
+register_notification.
+
+Method resolution order:
+
+=over 4
+
+=item Notification
+
+=item PluginData
+
+=item object
+
+=back
+
+Methods defined here:
+
+=over 4
+
+=item B<dispatch>([type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.  Dispatch a value list.
+    
+Dispatch this instance to the collectd process. The object has members for each
+of the possible arguments for this method. For a detailed explanation of these
+parameters see the member of the same same.
+    
+If you do not submit a parameter the value saved in its member will be
+submitted. If you do provide a parameter it will be used instead, without
+altering the member.
+
+=back
+
+Data descriptors defined here:
+
+=over 4
+
+=item message
+
+Some kind of description what's going on and why this Notification was
+generated.
+
+=item severity
 
+The severity of this notification. Assign or compare to I<NOTIF_FAILURE>,
+I<NOTIF_WARNING> or I<NOTIF_OKAY>.
 
 =back