Updates to some python client classes for prettier API docs.

Added missing .rst annotations and missing docstrings.
Added log file for sphinx runs.

1 files changed, 105 insertions, 0 deletions

diff --git a/base/common/python/pki/system.py b/base/common/python/pki/system.py
index a4b5c2fee..1cc2a7a5a 100644
--- a/base/common/python/pki/system.py
+++ b/base/common/python/pki/system.py
@@ -29,6 +29,10 @@ if os.path.exists("/etc/debian_version"):
 
 
 class SecurityDomainHost(object):
+    """
+    Class representing a security domain host.
+    """
+
     def __init__(self):
         """ constructor """
         self.id = None
@@ -44,6 +48,13 @@ class SecurityDomainHost(object):
 
     @classmethod
     def from_json(cls, json_value):
+        """
+        Constructs a SecurityDomainHost object from JSON.
+
+        :param json_value: JSON string representing a security domain host.
+        :type json_value: str
+        :returns: SecurityDomainHost
+        """
         host = cls()
         host.admin_port = json_value['SecureAdminPort']
         host.agent_port = json_value['SecureAgentPort']
@@ -59,12 +70,25 @@ class SecurityDomainHost(object):
 
 
 class SecurityDomainSubsystem(object):
+    """
+    Class representing a security domain subsystem.
+    This is essentially a list of SecurityDomainHost objects of a
+    particular subsystem type (ca, kra, tps, tks, ocsp).
+    """
+
     def __init__(self):
         self.name = None
         self.hosts = {}
 
     @classmethod
     def from_json(cls, json_value):
+        """
+        Constructs a SecurityDomainSubsystem from a JSON representation.
+
+        :param json_value: JSON representation of the Security Domain Subsystem
+        :type json_value: str
+        :returns: SecurityDomainSubsystem
+        """
         ret = cls()
         ret.name = json_value['id']
         for host in json_value['Host']:
@@ -73,12 +97,24 @@ class SecurityDomainSubsystem(object):
 
 
 class SecurityDomainInfo(object):
+    """
+    Class representing the entire security domain.
+    This is essentially a list of SecurityDomainSubsystem components.
+    """
+
     def __init__(self):
         self.name = None
         self.systems = {}
 
     @classmethod
     def from_json(cls, json_value):
+        """
+        Create a SecurityDomainInfo object from JSON.
+
+        :param json_value: JSON representation of a security domain.
+        :type json_value: str
+        :returns: SecurityDomainInfo
+        """
         ret = cls()
         ret.name = json_value['id']
         for slist in json_value['Subsystem']:
@@ -88,15 +124,36 @@ class SecurityDomainInfo(object):
 
 
 class SecurityDomainClient(object):
+    """
+    Client used to get the security domain from a security domain CA.
+    The connection details for the security domain CA are specified in
+    a PKIConnection object used to construct this client.
+    """
+
     def __init__(self, connection):
         self.connection = connection
 
     def get_security_domain_info(self):
+        """
+        Contact the security domain CA specified in the connection object
+        used to construct this client and get the security domain using the
+        REST API.
+
+        :returns: pki.system.SecurityDomainInfo
+        """
         response = self.connection.get('/rest/securityDomain/domainInfo')
         info = SecurityDomainInfo.from_json(response.json())
         return info
 
     def get_old_security_domain_info(self):
+        """
+        Contact the security domain CA specified in the connection object
+        used to construct this client and get the security domain using the
+        old servlet-based interface.  This method is useful when contacting
+        old servers which do not provide the REST API.
+
+        :returns: pki.system.SecurityDomainInfo
+        """
         response = self.connection.get('/admin/ca/getDomainXML')
         root = ETree.fromstring(response.text)
         domaininfo = ETree.fromstring(root.find("DomainInfo").text)
@@ -106,6 +163,13 @@ class SecurityDomainClient(object):
 
 
 class ConfigurationRequest(object):
+    """
+    Class used to represent a configuration request to be submitted to the
+    Java installation servlet during the execution of pkispawn.
+
+    This class is the python equivalent of the Java class:
+    com.netscape.certsrv.system.ConfigurationRequest
+    """
     def __init__(self):
         self.token = "Internal Key Storage Token"
         self.isClone = "false"
@@ -115,20 +179,51 @@ class ConfigurationRequest(object):
 
 
 class ConfigurationResponse(object):
+    """
+    Class used to represent the response from the Java configuration
+    servlet during the execution of pkispawn.
+
+    This class is the python equivalent of the Java class:
+    com.netscape.certsrv.system.ConfigurationRequest
+    """
     def __init__(self):
         pass
 
 
 class SystemCertData(object):
+    """
+    Class used to represent the data for a system certificate, which is
+    used in the data passed into and returned from the Java installation
+    servlet during the execution of pkispawn.
+
+    This class is the python equivalent of the Java class:
+    com.netscape.certsrv.system.SystemCertData
+    """
     def __init__(self):
         pass
 
 
 class SystemConfigClient(object):
+    """
+    Client used to interact with the Java configuration servlet to configure
+    a Dogtag subsystem during the execution of pkispawn.
+
+    The connection details for the system being configured are passed in
+    the PKIConnection object used when constructing this object.
+    """
     def __init__(self, connection):
         self.connection = connection
 
     def configure(self, data):
+        """
+        Contacts the server and invokes the Java configuration REST API to
+        configure a Dogtag subsystem.
+
+        :param data: Configuration request containing all the input needed to
+            configure the subsystem
+        :type data: ConfigurationRequest
+        :return: ConfigurationResponse -- response from configuration servlet.
+        """
         headers = {'Content-type': 'application/json',
                    'Accept': 'application/json'}
         response = self.connection.post('/rest/installer/configure', data,
@@ -137,10 +232,20 @@ class SystemConfigClient(object):
 
 
 class SystemStatusClient(object):
+    """
+    Client used to check the status of a Dogtag subsystem.
+    """
     def __init__(self, connection):
         self.connection = connection
 
     def get_status(self):
+        """
+        Checks the status of the subsystem by calling the getStatus()
+        servlet.  This is used to determine if the server is up and ready to
+        receive and process requests.
+
+        :return: str - getStatus response
+        """
         response = self.connection.get('/admin/' +
                                        self.connection.subsystem + '/getStatus')
         return response.text