doc: Clean up of docstrings/files.

doc/conf.py

@@ -49,8 +49,8 @@
 
 # General information about the project.
 project = u'commissaire'
-copyright = u'2016, Steve Milner, Chris Murphy, Ryan Cook'
-author = u'Steve Milner, Chris Murphy, Ryan Cook'
+author = 'Matthew Barnes, Ryan Cook, Steve Milner, and Chris Murphy'
+copyright = u'2016, {0}'.format(author)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/index.rst

@@ -17,14 +17,6 @@ Contents:
    endpoints
    enums
 
-API Documentation:
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   apidoc/*
-
 
 Indices and tables
 ==================

src/commissaire/__init__.py

@@ -12,3 +12,6 @@
 #
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+The commissaire package.
+"""

src/commissaire/authentication/__init__.py

@@ -12,6 +12,9 @@
 #
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+Authentication related code for commissaire.
+"""
 
 import logging
 

src/commissaire/authentication/httpauth.py

@@ -35,6 +35,7 @@ def _decode_basic_auth(self, req):
         :param req: Request instance that will be passed through.
         :type req: falcon.Request
         :returns: tuple -- (username, passphrase) or (None, None) if empty.
+        :rtype: tuple
         """
         if req.auth is not None:
             if req.auth.lower().startswith('basic '):

src/commissaire/compat/__init__.py

@@ -18,4 +18,5 @@
 
 import platform
 
+#: Version of the current interpreter
 __python_version__ = platform.python_version()[0]

src/commissaire/compat/b64.py

@@ -25,4 +25,5 @@
     _patched_b64.decodebytes = _patched_b64.decodestring
 
 
+#: Version of base64 which will work for Python 2 and 3
 base64 = _patched_b64

src/commissaire/handlers/__init__.py

@@ -12,3 +12,6 @@
 #
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+All REST handlers for commissaire.
+"""

src/commissaire/handlers/clusters.py

@@ -12,6 +12,9 @@
 #
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+Cluster(s) handlers.
+"""
 
 import falcon
 import etcd

src/commissaire/handlers/hosts.py

@@ -12,7 +12,10 @@
 #
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+Host(s) handlers.
 
+"""
 import datetime
 import falcon
 import etcd

src/commissaire/handlers/status.py

@@ -12,6 +12,9 @@
 #
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+Status handlers.
+"""
 
 import falcon
 import etcd

src/commissaire/middleware.py

@@ -12,13 +12,29 @@
 #
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+Middleware classes for commissaire.
+"""
 
 
 class JSONify:
+    """
+    Turns Resources into JSON on responses.
+    """
 
     # def process_request(self, req, resp):
 
     def process_response(self, req, resp, resource):
+        """
+        Intercepts a response and attempts to turn it into JSON.
+
+        :param req: Request instance that will be passed through.
+        :type req: falcon.Request
+        :param resp: Response instance that will be passed through.
+        :type resp: falcon.Response
+        :param resource: The Resource which has been intercepted.
+        :type resource: commissaire.resource.Resource
+        """
         if 'model' in req.context.keys() and resp.body is None:
             try:
                 resp.body = req.context['model'].to_json()

src/commissaire/model.py

@@ -12,7 +12,9 @@
 #
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
+"""
+Basic Model structure for commissaire.
+"""
 
 import json
 
@@ -21,11 +23,20 @@ class Model:
     """
     Parent class for models.
     """
+
     _json_type = None
     _attributes = ()
     _hidden_attributes = ()
 
     def __init__(self, **kwargs):
+        """
+        Creates a new instance of a Model.
+
+        :param kwargs: All keyword arguments to create the model.
+        :type kwargs: dict
+        :returns: The Model instance.
+        :rtype: commissaire.model.Model
+        """
         for key in self._attributes:
             if key not in kwargs:
                 raise TypeError(
@@ -35,17 +46,41 @@ def __init__(self, **kwargs):
             setattr(self, key, kwargs[key])
 
     def _struct_for_json(self, secure=False):
+        """
+        Returns the proper structure for a model to be used in JSON.
+
+        :param secure: If the structure needs to respect _hidden_attributes.
+        :type secure: bool
+        :returns: A dict or list depending
+        :rtype: dict or list
+        """
         if self._json_type is dict:
             return self._dict_for_json(secure)
         elif self._json_type is list:
             return self._list_for_json(secure)
 
     def _list_for_json(self, secure):
+        """
+        Returns a list structure of the data.
+
+        :param secure: If the structure needs to respect _hidden_attributes.
+        :type secure: bool
+        :returns: A list of the data.
+        :rtype: list
+        """
         if len(self._attributes) == 1:
             data = getattr(self, self._attributes[0])
         return data
 
     def _dict_for_json(self, secure):
+        """
+        Returns a dict structure of the data.
+
+        :param secure: If the structure needs to respect _hidden_attributes.
+        :type secure: bool
+        :returns: A dict of the data.
+        :rtype: dict
+        """
         data = {}
         for key in self._attributes:
             if secure:
@@ -55,6 +90,14 @@ def _dict_for_json(self, secure):
         return data
 
     def to_json(self, secure=False):
+        """
+        Returns a JSON representation of this model.
+
+        :param secure: If the structure needs to respect _hidden_attributes.
+        :type secure: bool
+        :returns: The JSON representation.
+        :rtype: str
+        """
         return json.dumps(
             self._struct_for_json(secure=secure),
             default=lambda o: o._struct_for_json(secure=secure))

src/commissaire/queues.py

@@ -12,14 +12,18 @@
 #
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://
-from gevent.queue import Queue, Empty
+"""
+All global queues.
+"""
 
+from gevent.queue import Queue
 
+#: Input queue for the investigator thread(s)
 INVESTIGATE_QUEUE = Queue()
-'''
-ROUTER_QUEUE = Queue()
-QUEUES = {
-    "ALL": [Queue(), Queue()],
-    "10.2.0.2": [Queue()],
-}
-'''
+
+
+# ROUTER_QUEUE = Queue()
+# QUEUES = {
+#     "ALL": [Queue(), Queue()],
+#     "10.2.0.2": [Queue()],
+# }

src/commissaire/resource.py

@@ -12,13 +12,31 @@
 #
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+Basic Resource for commissaire.
+"""
 
 import logging
 
 
 class Resource:
+    """
+    Parent class for all commissaire Resources.
+    """
 
     def __init__(self, store, queue=None, **kwargs):
+        """
+        Creates a new Resource instance.
+
+        :param store: The etcd client to for storing/retrieving data.
+        :type store: etcd.Client
+        :param queue: Optional queue to use with the Resource instance.
+        :type queue: gevent.queue.Queue
+        :param kwargs: All other keyword arguemtns.
+        :type kwargs: dict
+        :returns: A new Resource instance.
+        :rtype: commissaire.resource.Resource
+        """
         self.store = store
         self.queue = queue
         self.logger = logging.getLogger('resources')

src/commissaire/script.py

@@ -96,23 +96,34 @@ def router(q):  # pragma: no cover
 '''
 
 
-def create_app(ds):  # pragma: no cover
+def create_app(store):  # pragma: no cover
+    """
+    Creates a new WSGI compliant commissaire application.
+
+    :param store: The etcd client to for storing/retrieving data.
+    :type store: etcd.Client
+    :returns: The commissaire application.
+    :rtype: falcon.API
+    """
     # TODO: Make this configurable
     try:
-        http_auth = httpauth.HTTPBasicAuthByEtcd(ds)
+        http_auth = httpauth.HTTPBasicAuthByEtcd(store)
     except etcd.EtcdKeyNotFound:
         # TODO: Fall back to empty users file instead
         http_auth = httpauth.HTTPBasicAuthByFile('./conf/users.json')
 
     app = falcon.API(middleware=[http_auth, JSONify()])
 
-    app.add_route('/api/v0/status', StatusResource(ds, None))
-    app.add_route('/api/v0/host/{address}', HostResource(ds, None))
-    app.add_route('/api/v0/hosts', HostsResource(ds, None))
+    app.add_route('/api/v0/status', StatusResource(store, None))
+    app.add_route('/api/v0/host/{address}', HostResource(store, None))
+    app.add_route('/api/v0/hosts', HostsResource(store, None))
     return app
 
 
 def main():  # pragma: no cover
+    """
+    Main script entry point.
+    """
     import sys
     import urlparse