Merge pull request #437 from opdemand/more-docstrings

More docstrings, FAQ update.

Author: mboersma

api/admin.py

@@ -1,4 +1,3 @@
-#!/usr/bin/python
 # -*- coding: utf-8 -*-
 
 """

api/exceptions.py

@@ -1,5 +1,5 @@
 """
-Deis exception classes.
+Deis API exception classes.
 """
 
 from __future__ import unicode_literals
@@ -9,7 +9,12 @@
 
 
 class BuildNodeError(APIException):
-    """Indicates a problem in building or bootstrapping a node."""
+    """
+    Indicates a problem in building or bootstrapping a node.
+
+    This exception is subclassed from rest_framework's APIException so it
+    isn't reported as "500 SERVER ERROR."
+    """
 
     status_code = status.HTTP_401_UNAUTHORIZED
 

api/fields.py

@@ -10,9 +10,7 @@
 
 
 class UuidField(models.CharField):
-
     """A univerally unique ID field."""
-    # pylint: disable=R0904
 
     description = __doc__
 
@@ -24,13 +22,11 @@ def __init__(self, *args, **kwargs):
         super(UuidField, self).__init__(*args, **kwargs)
 
     def db_type(self, connection=None):
-        """Return the database type for a UuidField."""
-        db_type = None
+        """Return the database column type for a UuidField."""
         if connection and 'postgres' in connection.vendor:
-            db_type = 'uuid'
+            return 'uuid'
         else:
-            db_type = "char({})".format(self.max_length)
-        return db_type
+            return "char({})".format(self.max_length)
 
     def pre_save(self, model_instance, add):
         """Initialize an empty field with a new UUID before it is saved."""
@@ -55,12 +51,5 @@ def formfield(self, **kwargs):
     from south.modelsinspector import add_introspection_rules
     # Tell the South schema migration tool to handle our custom fields.
     add_introspection_rules([], [r'^api\.fields\.UuidField'])
-    add_introspection_rules([], [r'^api\.fields\.EnvVarsField'])
-    add_introspection_rules([], [r'^api\.fields\.DataBagField'])
-    add_introspection_rules([], [r'^api\.fields\.ProcfileField'])
-    add_introspection_rules([], [r'^api\.fields\.CredentialsField'])
-    add_introspection_rules([], [r'^api\.fields\.ParamsField'])
-    add_introspection_rules([], [r'^api\.fields\.CloudInitField'])
-    add_introspection_rules([], [r'^api\.fields\.NodeStatusField'])
 except ImportError:  # pragma: no cover
     pass

api/models.py

@@ -1,10 +1,8 @@
-#!/usr/bin/python
 # -*- coding: utf-8 -*-
 
 """
 Data models for the Deis API.
 """
-# pylint: disable=R0903,W0232
 
 from __future__ import unicode_literals
 import importlib
@@ -36,7 +34,6 @@
 
 # base models
 
-
 class AuditedModel(models.Model):
     """Add created and updated fields to a model."""
 
@@ -57,8 +54,8 @@ class Meta:
         """Mark :class:`UuidAuditedModel` as abstract."""
         abstract = True
 
-# deis core models
 
+# deis core models
 
 @python_2_unicode_compatible
 class Key(UuidAuditedModel):
@@ -127,7 +124,7 @@ def __str__(self):
 
 
 class FlavorManager(models.Manager):
-    """Manage database interactions for :class:`Flavor`."""
+    """Manage database interactions for :class:`Flavor`\s."""
 
     def seed(self, user, **kwargs):
         """Seed the database with default Flavors for each cloud region."""
@@ -164,7 +161,6 @@ def __str__(self):
 
 @python_2_unicode_compatible
 class Formation(UuidAuditedModel):
-
     """
     Formation of nodes used to host applications
     """
@@ -250,7 +246,6 @@ def calculate(self):
 
 @python_2_unicode_compatible
 class Layer(UuidAuditedModel):
-
     """
     Layer of nodes used by the formation
 
@@ -763,7 +758,7 @@ class Release(UuidAuditedModel):
     """
     Software release deployed by the application platform
 
-    Releases contain a Build and a Config.
+    Releases contain a :class:`Build` and a :class:`Config`.
     """
 
     owner = models.ForeignKey(settings.AUTH_USER_MODEL)
@@ -844,10 +839,10 @@ def _user_purge(self):
 User.publish = _user_publish
 User.purge = _user_purge
 
+
 # define update/delete callbacks for synchronizing
 # models with the configuration management backend
 
-
 def _publish_to_cm(**kwargs):
     kwargs['instance'].publish()
 

api/serializers.py

@@ -1,7 +1,6 @@
 """
 Classes to serialize the RESTful representation of Deis API models.
 """
-# pylint: disable=R0903,W0232
 
 from __future__ import unicode_literals
 

client/setup.py

@@ -30,7 +30,6 @@
     KWARGS = {'scripts': ['deis']}
 
 
-# pylint: disable=W0142
 setup(name='deis',
       version='0.4.0',
       license=APACHE_LICENSE,

deis/urls.py

@@ -14,7 +14,6 @@
 admin.autodiscover()
 
 
-# pylint: disable=C0103
 urlpatterns = patterns(
     '',
     url(r'^accounts/', include('allauth.urls')),

deis/wsgi.py

@@ -27,7 +27,7 @@
 # file. This includes Django's development server, if the WSGI_APPLICATION
 # setting points here.
 from django.core.wsgi import get_wsgi_application
-application = get_wsgi_application()  # pylint: disable=C0103
+application = get_wsgi_application()
 
 # Apply WSGI middleware here.
 # from helloworld.wsgi import HelloWorldApplication

docs/faq.rst

@@ -1,6 +1,6 @@
 :title: FAQ
 :description: Frequently asked questions about the Deis project. Deis FAQ.
-:keywords: deis, PaaS, cloud, faq
+:keywords: deis, PaaS, cloud, faq, custom buildpack
 
 .. _faq:
 
@@ -16,3 +16,13 @@ FAQ
     DAY-iss
 
 .. _dais: https://en.wiktionary.org/wiki/dais
+
+- How can I use custom buildpacks with Deis?
+
+    1. Clone the `deis-cookbook`_ repository.
+    2. Change the *buildpacks* definition in *recipes/build.rb*.
+    3. Upload the changed cookbook to the Chef server
+       with ``berks upload --force``.
+    4. SSH into your Deis controller and run ``sudo chef-client``.
+
+.. _`deis-cookbook`: https://github.com/opdemand/deis-cookbook.git

web/static/css/deis-docs.css

@@ -14,3 +14,15 @@ h6:hover > a.headerlink,
 dt:hover > a.headerlink {
   visibility: visible;
 }
+
+span.viewcode-link {
+	font-size: 10px;
+	margin-left: 6px;
+	vertical-align: super;
+}
+
+a.viewcode-back {
+	font-size: 10px;
+	margin-right: 6px;
+	vertical-align: super;
+}