Update reclass_adapter documentation

Signed-off-by: martin f. krafft <madduck@madduck.net>

salt/pillar/reclass_adapter.py

@@ -1,10 +1,13 @@
 '''
-ext_pillar adapter for reclass.
+This ``ext_pillar`` plugin provides access to the |reclass| database, such
+that Pillar data for a specific minion are fetched using |reclass|.
 
-Please refer to the file ``README.Salt`` in the reclass source for more
-information on how to use these. In a nutshell, you'll just add the plugin to
-the ext_pillar hash in the master config and tell reclass by way of a few
-options how and where to find the inventory:
+You can find more information about |reclass| at
+http://reclass.pantsfullofunix.net.
+
+To use the plugin, add it to the ``ext_pillar`` list in the Salt master config
+and tell |reclass| by way of a few options how and where to find the
+inventory:
 
 .. code-block:: yaml
 
@@ -13,13 +16,12 @@ options how and where to find the inventory:
             storage_type: yaml_fs
             base_inventory_uri: /srv/salt
 
-This would cause reclass to read the inventory from YAML files in
+This would cause |reclass| to read the inventory from YAML files in
 ``/srv/salt/nodes`` and ``/srv/salt/classes``.
 
-More information about reclass: http://github.com/madduck/reclass
-
-If you are also using master_tops and you want to avoid having to specify the
-same information for both, use YAML anchors:
+If you are also using |reclass| as ``master_tops`` plugin, and you want to
+avoid having to specify the same information for both, use YAML anchors (take
+note of the differing data types for ``ext_pillar`` and ``master_tops``):
 
 .. code-block:: yaml
 
@@ -37,7 +39,10 @@ same information for both, use YAML anchors:
 If you want to run reclass from source, rather than installing it, you can
 either let the master know via the ``PYTHONPATH`` environment variable, or by
 setting the configuration option, like in the example above.
+
+.. |reclass| replace:: **reclass**
 '''
+
 # This file cannot be called reclass.py, because then the module import would
 # not work. Thanks to the __virtual__ function, however, the plugin still
 # responds to the name 'reclass'.
@@ -73,6 +78,10 @@ def __virtual__(retry=False):
 from salt.exceptions import SaltInvocationError
 
 def ext_pillar(minion_id, pillar, **kwargs):
+    '''
+    Obtain the Pillar data from **reclass** for the given ``minion_id``.
+    '''
+
     # If reclass is installed, __virtual__ put it onto the search path, so we
     # don't need to protect against ImportError:
     from reclass.adapters.salt import ext_pillar as reclass_ext_pillar

salt/tops/reclass_adapter.py

@@ -1,25 +1,27 @@
 '''
-master_tops adapter for reclass.
+This ``master_tops`` plugin provides access to the |reclass| database, such
+that state information (top data) are retrieved from |reclass|.
 
-Please refer to the file ``README.Salt`` in the reclass source for more
-information on how to use these. In a nutshell, you'll just add the plugin to
-the master_tops hash in the master config and tell reclass by way of a few
-options how and where to find the inventory:
+You can find more information about |reclass| at
+http://reclass.pantsfullofunix.net.
+
+To use the plugin, add it to the ``master_tops`` list in the Salt master config
+and tell |reclass| by way of a few options how and where to find the
+inventory:
 
 .. code-block:: yaml
 
     master_tops:
         reclass:
-            storage_type: yaml_fs
-            base_inventory_uri: /srv/salt
+          storage_type: yaml_fs
+          base_inventory_uri: /srv/salt
 
-This would cause reclass to read the inventory from YAML files in
+This would cause |reclass| to read the inventory from YAML files in
 ``/srv/salt/nodes`` and ``/srv/salt/classes``.
 
-More information about reclass: http://github.com/madduck/reclass
-
-If you are also using ext_pillar and you want to avoid having to specify the
-same information for both, use YAML anchors:
+If you are also using |reclass| as ``ext_pillar`` plugin, and you want to
+avoid having to specify the same information for both, use YAML anchors (take
+note of the differing data types for ``ext_pillar`` and ``master_tops``):
 
 .. code-block:: yaml
 
@@ -37,7 +39,10 @@ same information for both, use YAML anchors:
 If you want to run reclass from source, rather than installing it, you can
 either let the master know via the ``PYTHONPATH`` environment variable, or by
 setting the configuration option, like in the example above.
+
+.. |reclass| replace:: **reclass**
 '''
+
 # This file cannot be called reclass.py, because then the module import would
 # not work. Thanks to the __virtual__ function, however, the plugin still
 # responds to the name 'reclass'.
@@ -64,6 +69,10 @@ def __virtual__(retry=False):
 from salt.exceptions import SaltInvocationError
 
 def top(**kwargs):
+    '''
+    Query |reclass| for the top data (states of the minions).
+    '''
+
     # If reclass is installed, __virtual__ put it onto the search path, so we
     # don't need to protect against ImportError:
     from reclass.adapters.salt import top as reclass_top

salt/utils/reclass.py

@@ -1,5 +1,6 @@
 '''
 Common utility functions for the reclass adapters
+http://reclass.pantsfullofunix.net
 '''
 import sys
 import os