adding more python docs

docs/api.rst

@@ -4,13 +4,13 @@ API
 .. toctree::
    :maxdepth: 4
 
-   api/paperboy.server.rst
    api/paperboy.config.rst
    api/paperboy.scheduler.rst
    api/paperboy.scheduler.airflow.rst
    api/paperboy.storage.rst
    api/paperboy.storage.sqla.rst
    api/paperboy.storage.sqla.models.rst
+   api/paperboy.server.rst
    api/paperboy.output.rst
    api/paperboy.resources.rst
 

paperboy/config/base.py

@@ -9,21 +9,58 @@
 
 
 class Base(HasTraits):
+    '''Base HasTraits abstract base class for all paperboy configureables'''
+
     def __init__(self, config, *args, **kwargs):
         super(Base, self).__init__(*args, **kwargs)
         self.config = config
 
     @staticmethod
     def from_json(jsn, config):
+        '''create a paperboy config object from a json
+
+        Args:
+            jsn: python dictionary from json representing the configuration object
+            config: paperboy configuration to populate from json
+
+        Returns:
+            subclass of Base populated from jsn
+        '''
         raise NotImplementedError()
 
     def to_json(self, include_notebook=False):
+        '''convert a paperboy config to a json
+
+        Args:
+            self: subclass of Base
+            include_notebook: if config would include a notebook (potentially several MB in size), should
+                we include it or strip it?
+
+        Returns:
+            dict: python dictionary representing the response json
+        '''
         raise NotImplementedError()
 
     def form(self):
+        '''generate a JSON form template for the subclass of Base
+
+        Args:
+            self: subclass of Base
+
+        Returns:
+            dict: python dictionary representing the form template as a JSON
+        '''
         raise NotImplementedError()
 
     def edit(self):
+        '''generate a JSON edit template for the subclass of Base
+
+        Args:
+            self: subclass of Base
+
+        Returns:
+            dict: python dictionary representing the edit template as a JSON
+        '''
         raise NotImplementedError()
 
     def entry(self):

paperboy/config/forms.py

@@ -6,6 +6,7 @@
 
 
 class FormEntry(HasTraits):
+    '''Form template entry to be rendered on the client'''
     name = Unicode(allow_none=False)
     type = Unicode(default_value='text')
 
@@ -25,6 +26,7 @@ def _validate_type(self, proposal):
     hidden = Bool(default_value=False)
 
     def to_json(self):
+        '''Convert form entry to JSON'''
         ret = {}
         ret['name'] = self.name
         ret['type'] = self.type
@@ -47,6 +49,7 @@ def to_json(self):
 
 
 class DOMEntry(HasTraits):
+    '''DOM node template to be rendered on the client'''
     name = Unicode(allow_none=False)
     type = Unicode(default_value='p')
 
@@ -91,6 +94,7 @@ def from_json(jsn):
 
 
 class Response(HasTraits):
+    '''Response modal template for client'''
     entries = List()
 
     def to_json(self):
@@ -101,6 +105,7 @@ def to_json(self):
 
 
 class ListResult(HasTraits):
+    '''List result metadata for pagination'''
     page = Int(default_value=1)
     pages = Int(default_value=1)
     count = Int(default_value=1)

paperboy/config/job.py

@@ -7,6 +7,7 @@
 
 
 class JobMetadataConfig(HasTraits):
+    '''Paperboy configuration object representing a Job (metadata component)'''
     notebook = Instance(NotebookConfig)
     username = Unicode()
     userid = Unicode()
@@ -26,6 +27,7 @@ def _validate_interval(self, proposal):
     modified = Instance(datetime)
 
     def to_json(self, include_notebook=False):
+        '''Convert JobMetadata to a JSON'''
         ret = {}
         ret['notebook'] = self.notebook.name
         if include_notebook:
@@ -40,6 +42,7 @@ def to_json(self, include_notebook=False):
 
     @staticmethod
     def from_json(jsn):
+        '''Create JobMetadata from a JSON'''
         ret = JobMetadataConfig()
         for k, v in jsn.items():
             if k in ('created', 'modified'):
@@ -50,18 +53,21 @@ def from_json(jsn):
 
 
 class JobConfig(Base):
+    '''Paperboy configuration object representing a Job'''
     name = Unicode()
     id = Unicode()
     meta = Instance(JobMetadataConfig)
 
     def to_json(self, include_notebook=False):
+        '''Convert Job to a JSON'''
         ret = {}
         ret['name'] = self.name
         ret['id'] = self.id
         ret['meta'] = self.meta.to_json(include_notebook)
         return ret
 
     def form(self):
+        '''Generate Form template for client from a Job object'''
         f = Response()
         f.entries = [
             FormEntry(name='name', type='text', label='Name', value=self.name, placeholder='Name for Job...', required=True),
@@ -82,6 +88,7 @@ def form(self):
 
     @staticmethod
     def from_json(jsn, config):
+        '''Create Job from a JSON'''
         ret = JobConfig(config)
         ret.name = jsn['name']
         ret.id = jsn['id']
@@ -90,6 +97,7 @@ def from_json(jsn, config):
         return ret
 
     def edit(self):
+        '''Generate Edit template for client from a Job object'''
         f = Response()
         f.entries = [
             FormEntry(name='name', type='text', value=self.name, label='Name', placeholder='Name for Job...', required=True),
@@ -106,6 +114,7 @@ def edit(self):
         return f.to_json()
 
     def entry(self):
+        '''Generate ListTable entry for client from a Job object'''
         f = Response()
         f.entries = [
             DOMEntry(name='name', type='label', value=self.name, label='Name'),
@@ -121,6 +130,7 @@ def entry(self):
         return f.to_json()
 
     def store(self):
+        '''Generate response modal for client when saving a Job object'''
         ret = Response()
         ret.entries = [
             DOMEntry(type='h2', value='Success!'),

paperboy/config/notebook.py

@@ -6,6 +6,7 @@
 
 
 class NotebookMetadataConfig(HasTraits):
+    '''Paperboy configuration object representing a Notebook (metadata component)'''
     username = Unicode()
     userid = Unicode()
 
@@ -22,6 +23,7 @@ class NotebookMetadataConfig(HasTraits):
     modified = Instance(datetime)
 
     def to_json(self, include_notebook=False):
+        '''Convert NotebookMetadata to a JSON'''
         ret = {}
         ret['username'] = self.username
         # ret['userid'] = self.userid
@@ -37,6 +39,7 @@ def to_json(self, include_notebook=False):
 
     @staticmethod
     def from_json(jsn):
+        '''Create NotebookMetadata from a JSON'''
         ret = NotebookMetadataConfig()
         for k, v in jsn.items():
             if k in ('created', 'modified'):
@@ -47,18 +50,21 @@ def from_json(jsn):
 
 
 class NotebookConfig(Base):
+    '''Paperboy configuration object representing a Notebook'''
     name = Unicode()
     id = Unicode()
     meta = Instance(NotebookMetadataConfig)
 
     def to_json(self, include_notebook=False):
+        '''Convert Notebook to a JSON'''
         ret = {}
         ret['name'] = self.name
         ret['id'] = self.id
         ret['meta'] = self.meta.to_json(include_notebook)
         return ret
 
     def form(self):
+        '''Generate Form template for client from a Notebook object'''
         f = Response()
         f.entries = [
             FormEntry(name='file', type='file', label='File', required=True),
@@ -74,6 +80,7 @@ def form(self):
 
     @staticmethod
     def from_json(jsn, config):
+        '''Create Notebook from a JSON'''
         ret = NotebookConfig(config)
         ret.name = jsn.pop('name')
         ret.id = jsn.pop('id')
@@ -86,6 +93,7 @@ def from_json(jsn, config):
         return ret
 
     def edit(self):
+        '''Generate Edit template for client from a Notebook object'''
         f = Response()
         f.entries = [
             FormEntry(name='name', type='text', value=self.name, placeholder='Name for Job...', required=True),
@@ -103,6 +111,7 @@ def edit(self):
         return f.to_json()
 
     def entry(self):
+        '''Generate ListTable entry for client from a Notebook object'''
         f = Response()
         f.entries = [
             DOMEntry(name='name', type='label', value=self.name, label='Name'),
@@ -121,6 +130,7 @@ def entry(self):
         return f.to_json()
 
     def store(self):
+        '''Generate response modal for client when saving a Notebook object'''
         ret = Response()
         ret.entries = [
             DOMEntry(type='p', value='Success!'),

paperboy/config/report.py

@@ -29,6 +29,7 @@ def _type_to_template(output, strip_code):
 
 
 class ReportMetadataConfig(HasTraits):
+    '''Paperboy configuration object representing a Report (metadata component)'''
     notebook = Instance(NotebookConfig)
     job = Instance(JobConfig)
 
@@ -48,6 +49,7 @@ class ReportMetadataConfig(HasTraits):
     modified = Instance(datetime)
 
     def to_json(self, include_notebook=False):
+        '''Convert ReportMetadata to a JSON'''
         ret = {}
         ret = {}
         ret['notebook'] = self.notebook.name
@@ -76,6 +78,7 @@ def to_json(self, include_notebook=False):
 
     @staticmethod
     def from_json(jsn):
+        '''Create ReportMetadata from a JSON'''
         ret = ReportMetadataConfig()
         for k, v in jsn.items():
             if k in ('created', 'modified', 'run'):
@@ -86,18 +89,21 @@ def from_json(jsn):
 
 
 class ReportConfig(Base):
+    '''Paperboy configuration object representing a Report'''
     name = Unicode()
     id = Unicode()
     meta = Instance(ReportMetadataConfig)
 
     def to_json(self, include_notebook=False):
+        '''Convert Report to a JSON'''
         ret = {}
         ret['name'] = self.name
         ret['id'] = self.id
         ret['meta'] = self.meta.to_json(include_notebook)
         return ret
 
     def form(self):
+        '''Generate Form template for client from a Report object'''
         f = Response()
         f.entries = [
             FormEntry(name='name', type='text', label='Name', placeholder='Name for Report...', required=True),
@@ -114,6 +120,7 @@ def form(self):
 
     @staticmethod
     def from_json(jsn, config):
+        '''Create Report from a JSON'''
         ret = ReportConfig(config)
         ret.name = jsn['name']
         ret.id = jsn['id']
@@ -123,6 +130,7 @@ def from_json(jsn, config):
         return ret
 
     def edit(self):
+        '''Generate Edit template for client from a Report object'''
         f = Response()
         f.entries = [
             FormEntry(name='name', type='text', value=self.name, label='Name', placeholder='Name for Report...', required=True),
@@ -141,6 +149,7 @@ def edit(self):
         return f.to_json()
 
     def entry(self):
+        '''Generate ListTable entry for client from a Report object'''
         f = Response()
         f.entries = [
             DOMEntry(name='name', type='label', value=self.name, label='Name'),
@@ -160,6 +169,7 @@ def entry(self):
         return f.to_json()
 
     def store(self):
+        '''Generate response modal for client when saving a Report object'''
         ret = Response()
         ret.entries = [
             DOMEntry(type='h2', value='Success!'),

paperboy/config/user.py

@@ -5,16 +5,19 @@
 
 
 class UserConfig(Base):
+    '''Paperboy configuration object representing a User'''
     name = Unicode()
     id = Unicode()
 
     def to_json(self):
+        '''Convert User to a JSON'''
         ret = {}
         ret['name'] = self.name
         ret['id'] = self.id
         return ret
 
     def form(self):
+        '''Generate Form template for client from a User object'''
         f = Response()
         f.entries = [
             FormEntry(name='name', type='text', label='Name', placeholder='Name for Notebook...', required=True),
@@ -24,12 +27,14 @@ def form(self):
 
     @staticmethod
     def from_json(jsn, config):
+        '''Create User from a JSON'''
         ret = UserConfig(config)
         ret.name = jsn.pop('name')
         ret.id = jsn.pop('id')
         return ret
 
     def edit(self):
+        '''Generate Edit template for client from a User object'''
         f = Response()
         f.entries = [
             FormEntry(name='name', type='text', value=self.name, placeholder='Name for Job...', required=True),
@@ -38,6 +43,7 @@ def edit(self):
         return f.to_json()
 
     def store(self):
+        '''Generate response modal for client when saving a User object'''
         ret = Response()
         ret.entries = [
             DOMEntry(type='p', value='Success!'),