Fix up Chartbuilder docstrings

This PS simply updates, corrects and polishes up docstrings in
armada.handlers.chartbuilder. The information related to pulling
source in Chartbuilder class is not correct as source is actually
pulled in armada.handlers.armada instead [0].

Also removes ``parent`` kwarg from ChartBuilder class as it
wasn't being used anywhere, neither as metadata nor internal
processing.

[0] 60b8a37f47/armada/handlers/armada.py (L206)

Change-Id: I117e1c8ec2582b8dcbee47598349b4e98bec71af

armada/handlers/chartbuilder.py

@@ -33,29 +33,20 @@ CONF = cfg.CONF
 
 class ChartBuilder(object):
     '''
-    This class handles taking chart intentions as a parameter and
-    turning those into proper protoc helm charts that can be
-    pushed to tiller.
-
-    It also processes chart source declarations, fetching chart
-    source from external resources where necessary
+    This class handles taking chart intentions as a parameter and turning those
+    into proper ``protoc`` Helm charts that can be pushed to Tiller.
     '''
 
-    def __init__(self, chart, parent=None):
-        '''
-        Initialize the ChartBuilder class
+    def __init__(self, chart):
+        '''Initialize the :class:`ChartBuilder` class.
 
-        Note that this will trigger a source pull as part of
-        initialization as its necessary in order to examine
-        the source service many of the calls on ChartBuilder
+        :param dict chart: The document containing all intentions to pass to
+                           Tiller.
         '''
 
         # cache for generated protoc chart object
         self._helm_chart = None
 
-        # record whether this is a dependency based chart
-        self.parent = parent
-
         # store chart schema
         self.chart = chart
 
@@ -66,8 +57,10 @@ class ChartBuilder(object):
         self.ignored_files = self.get_ignored_files()
 
     def get_source_path(self):
-        '''
-        Return the joined path of the source directory and subpath
+        '''Return the joined path of the source directory and subpath.
+
+        Returns "<source directory>/<subpath>" taken from the "source_dir"
+        property from the chart, or else "" if the property isn't a 2-tuple.
         '''
         source_dir = self.chart.get('source_dir')
         return (
@@ -79,9 +72,7 @@ class ChartBuilder(object):
         )
 
     def get_ignored_files(self):
-        '''
-        Load files from .helmignore if present
-        '''
+        '''Load files to ignore from .helmignore if present.'''
         try:
             ignored_files = []
             if os.path.exists(os.path.join(self.source_directory,
@@ -94,11 +85,11 @@ class ChartBuilder(object):
             raise chartbuilder_exceptions.IgnoredFilesLoadException()
 
     def ignore_file(self, filename):
-        '''
-        :params file - filename to compare against list of ignored files
+        '''Returns whether a given ``filename`` should be ignored.
 
-        Returns true if file matches an ignored file wildcard or exact name,
-         false otherwise
+        :param filename: Filename to compare against list of ignored files.
+        :returns: True if file matches an ignored file wildcard or exact name,
+                  False otherwise.
         '''
         for ignored_file in self.ignored_files:
             if (ignored_file.startswith('*') and
@@ -109,11 +100,9 @@ class ChartBuilder(object):
         return False
 
     def get_metadata(self):
+        '''Extract metadata from Chart.yaml to construct an instance of
+        :class:`hapi.chart.metadata_pb2.Metadata`.
         '''
-        Process metadata
-        '''
-        # extract Chart.yaml to construct metadata
-
         try:
             with open(os.path.join(self.source_directory, 'Chart.yaml')) as f:
                 chart_yaml = yaml.safe_load(f.read().encode('utf-8'))
@@ -121,7 +110,7 @@ class ChartBuilder(object):
         except Exception:
             raise chartbuilder_exceptions.MetadataLoadException()
 
-        # construct Metadata object
+        # Construct Metadata object.
         return Metadata(
             description=chart_yaml.get('description'),
             name=chart_yaml.get('name'),
@@ -199,9 +188,7 @@ class ChartBuilder(object):
         return non_template_files
 
     def get_values(self):
-        '''
-        Return the chart (default) values
-        '''
+        '''Return the chart's (default) values.'''
 
         # create config object representing unmarshaled values.yaml
         if os.path.exists(os.path.join(self.source_directory, 'values.yaml')):
@@ -215,12 +202,11 @@ class ChartBuilder(object):
         return Config(raw=raw_values)
 
     def get_templates(self):
-        '''
-        Return all the chart templates
-        '''
+        '''Return all the chart templates.
 
-        # process all files in templates/ as a template to attach to the chart
-        # building a Template object
+        Process all files in templates/ as a template to attach to the chart,
+        building a :class:`hapi.chart.template_pb2.Template` object.
+        '''
         chart_name = self.chart.get('chart_name')
         templates = []
         if not os.path.exists(
@@ -245,8 +231,10 @@ class ChartBuilder(object):
         return templates
 
     def get_helm_chart(self):
-        '''
-        Return a helm chart object
+        '''Return a Helm chart object.
+
+        Constructs a :class:`hapi.chart.chart_pb2.Chart` object from the
+        ``chart`` intentions, including all dependencies.
         '''
         if self._helm_chart:
             return self._helm_chart
@@ -280,10 +268,9 @@ class ChartBuilder(object):
         return helm_chart
 
     def dump(self):
-        '''
-        This method is used to dump a chart object as a
-        serialized string so that we can perform a diff
+        '''Dumps a chart object as a serialized string so that we can perform a
+        diff.
 
-        It should recurse into dependencies
+        It recurses into dependencies.
         '''
         return self.get_helm_chart().SerializeToString()