[docs|clusters] Update docstrings to use Sphinx style formatting

Updates the docstrings for `Cluster()` to use SPhinx-style formatting as
part of the effort to bring our Sphinx docs up to date.

Related: #2172

Signed-off-by: Jake Hunsaker <jhunsake@redhat.com>

2 files changed, 84 insertions, 23 deletions

diff --git a/docs/clusters.rst b/docs/clusters.rst
index 4388edb0..109c2cd7 100644
--- a/docs/clusters.rst
+++ b/docs/clusters.rst
@@ -4,5 +4,4 @@
 .. automodule:: sos.collector.clusters
     :noindex:
     :members:
-    :undoc-members:
     :show-inheritance:
diff --git a/sos/collector/clusters/__init__.py b/sos/collector/clusters/__init__.py
index 43a4b49e..700687aa 100644
--- a/sos/collector/clusters/__init__.py
+++ b/sos/collector/clusters/__init__.py
@@ -14,6 +14,40 @@ from sos.options import ClusterOption
 
 
 class Cluster():
+    """This is the class that cluster profiles should subclass in order to
+    add support for different clustering technologies and environments to
+    sos-collector.
+
+    A profile should at minimum define a package that indicates the node is
+    configured for the type of cluster the profile is intended to serve and
+    then additionally be able to return a list of enumerated nodes via the
+    ``get_nodes()`` method
+
+
+    :param commons: The commons dict containing system information. The same as
+                    what is handed to ``Plugin()``
+    :type commons: ``dict``
+
+
+    :cvar option_list:  Options supported by the profile, and set by the
+                        --cluster-option cmdline arg
+    :vartype option_list: ``list`` of ``tuples``
+
+    :cvar packages: What package(s) should this profile enable on
+    :vartype packages: ``tuple``
+
+    :cvar sos_plugins: Which plugins to forcibly enable for node reports
+    :vartype sos_plugins: ``list``
+
+    :cvar sos_plugin_options: Plugin options to forcibly set for nodes
+    :vartype sos_plugin_options: ``dict``
+
+    :cvar sos_preset: A SoSReport preset to forcibly enable on nodes
+    :vartype sos_preset: ``str``
+
+    :cvar cluster_name: The name of the cluster type
+    :vartype cluster_name: ``str``
+    """
 
     option_list = []
     packages = ('',)
@@ -23,16 +57,6 @@ class Cluster():
     cluster_name = None
 
     def __init__(self, commons):
-        """This is the class that cluster profile should subclass in order to
-        add support for different clustering technologies and environments to
-        sos-collector.
-
-        A profile should at minimum define a package that indicates the node is
-        configured for the type of cluster the profile is intended to serve and
-        then additionall be able to return a list of enumerated nodes via the
-        get_nodes() method
-        """
-
         self.master = None
         self.cluster_ssh_key = None
         self.tmpdir = commons['tmpdir']
@@ -83,8 +107,14 @@ class Cluster():
         self.soslog.warn(self._fmt_msg(msg))
 
     def get_option(self, option):
-        """This is used to by clusters to check if a cluster option was
-        supplied to sos-collector.
+        """
+        This is used to by clusters to check if a cluster option was
+        supplied to sos collect
+
+        :param option: The name of the option to fetch
+        :type option: ``str``
+
+        :returns: The value of the requested option if it exists, or ``False``
         """
         # check CLI before defaults
         for opt in self.opts.cluster_options:
@@ -108,27 +138,42 @@ class Cluster():
         self.cluster_ssh_key = key
 
     def exec_master_cmd(self, cmd, need_root=False):
-        """Used to retrieve output from a (master) node in a cluster"""
+        """Used to retrieve command output from a (master) node in a cluster
+
+        :param cmd: The command to run
+        :type cmd: ``str``
+
+        :param need_root: Does the command require root privileges
+        :type need_root: ``bool``
+
+        :returns: The output and status of `cmd`
+        :rtype: ``dict``
+        """
         res = self.master.run_command(cmd, get_pty=True, need_root=need_root)
         if res['stdout']:
             res['stdout'] = res['stdout'].replace('Password:', '')
         return res
 
     def setup(self):
-        """This MAY be used by a cluster to do prep work in case there are
+        """
+        This MAY be used by a cluster to do prep work in case there are
         extra commands to be run even if a node list is given by the user, and
         thus get_nodes() would not be called
         """
         pass
 
     def check_enabled(self):
-        """This may be overridden by clusters
+        """
+        This may be overridden by clusters
 
-        This is called by sos-collector on each cluster type that exists, and
+        This is called by sos collect on each cluster type that exists, and
         is meant to return True when the cluster type matches a criteria
         that indicates that is the cluster type is in use.
 
         Only the first cluster type to determine a match is run
+
+        :returns: ``True`` if the cluster profile should be used, or ``False``
+        :rtype: ``bool``
         """
         for pkg in self.packages:
             if self.master.is_installed(pkg):
@@ -136,9 +181,14 @@ class Cluster():
         return False
 
     def get_nodes(self):
-        """This MUST be overridden by a cluster.
+        """
+        This MUST be overridden by a cluster profile subclassing this class
+
         A cluster should use this method to return a list or string that
         contains all the nodes that a report should be collected from
+
+        :returns: A list of node FQDNs or IP addresses
+        :rtype: ``list`` or ``None``
         """
         pass
 
@@ -150,15 +200,22 @@ class Cluster():
             return []
 
     def get_node_label(self, node):
-        """Used by SosNode() to retrieve the appropriate label from the cluster
-        as set by set_node_label() in the cluster profile.
+        """
+        Used by ``SosNode()`` to retrieve the appropriate label from the
+        cluster as set by ``set_node_label()`` in the cluster profile.
+
+        :param node: The name of the node to get a label for
+        :type node: ``str``
+
+        :returns: The label to use for the node's report
+        :rtype: ``str``
         """
         label = self.set_node_label(node)
         node.manifest.add_field('label', label)
         return label
 
     def set_node_label(self, node):
-        """This may be overridden by clusters.
+        """This may be overridden by clusters profiles subclassing this class
 
         If there is a distinction between masters and nodes, or types of nodes,
         then this can be used to label the sosreport archive differently.
@@ -166,8 +223,12 @@ class Cluster():
         return ''
 
     def format_node_list(self):
-        """Format the returned list of nodes from a cluster into a known
+        """
+        Format the returned list of nodes from a cluster into a known
         format. This being a list that contains no duplicates
+
+        :returns: A list of nodes, without extraneous entries from cmd output
+        :rtype: ``list``
         """
         try:
             nodes = self.get_nodes()
@@ -185,7 +246,8 @@ class Cluster():
         return node_list
 
     def _run_extra_cmd(self):
-        """Ensures that any files returned by a cluster's run_extra_cmd()
+        """
+        Ensures that any files returned by a cluster's run_extra_cmd()
         method are properly typed as a list for iterative collection. If any
         of the files are an additional sosreport (e.g. the ovirt db dump) then
         the md5 sum file is automatically added to the list