fix(docs): clean up sources and treat warnings as errors

Many deficiencies in the docs were being skipped over because
`sphinx-build` is lenient. Adding the `-W` flag treats issues
such as "missing reference" and "class not found" as errors.

Author: mboersma

api/serializers.py

@@ -33,7 +33,7 @@ def from_native(self, data):
 
 
 class UserSerializer(serializers.ModelSerializer):
-    """Serialize a :class:`~api.models.User` model."""
+    """Serialize a User model."""
 
     class Meta:
         """Metadata options for a UserSerializer."""
@@ -52,7 +52,7 @@ def data(self):
 
 
 class AdminUserSerializer(serializers.ModelSerializer):
-    """Serialize admin status for a :class:`~api.models.User` model."""
+    """Serialize admin status for a User model."""
 
     class Meta:
         model = User

api/urls.py

@@ -27,7 +27,7 @@
 
 .. http:get:: /api/apps/(string:id)/
 
-  Retrieve a :class:`~api.models.Application` by its `id`.
+  Retrieve a :class:`~api.models.App` by its `id`.
 
 .. http:delete:: /api/apps/(string:id)/
 
@@ -65,14 +65,6 @@
 
   Create a new :class:`~api.models.Build`.
 
-.. http:get:: /api/apps/(string:id)/limits/
-
-  Retrieve the latest :class:`~api.models.Limit`.
-
-.. http:post:: /api/apps/(string:id)/limits/
-
-  Create a new :class:`~api.models.Limit`.
-
 .. http:get:: /api/apps/(string:id)/releases/(int:version)/
 
   Retrieve a :class:`~api.models.Release` by its `version`.
@@ -137,11 +129,6 @@
   See also
   :meth:`AppViewSet.run() <api.views.AppViewSet.run>`
 
-.. http:post:: /api/apps/(string:id)/calculate/
-
-  See also
-  :meth:`AppViewSet.calculate() <api.views.AppViewSet.calculate>`
-
 
 Application Sharing
 ===================
@@ -200,11 +187,11 @@
 
 .. http:post:: /api/auth/register/
 
-  Create a new :class:`~django.contrib.auth.models.User`.
+  Create a new User.
 
 .. http:delete:: /api/auth/register/
 
-  Destroy the logged-in :class:`~django.contrib.auth.models.User`.
+  Destroy the logged-in User.
 
 .. http:post:: /api/auth/login
 
@@ -292,8 +279,6 @@
         views.AppViewSet.as_view({'post': 'logs'})),
     url(r'^apps/(?P<id>{})/run/?'.format(settings.APP_URL_REGEX),
         views.AppViewSet.as_view({'post': 'run'})),
-    url(r'^apps/(?P<id>{})/calculate/?'.format(settings.APP_URL_REGEX),
-        views.AppViewSet.as_view({'post': 'calculate'})),
     # apps sharing
     url(r'^apps/(?P<id>{})/perms/(?P<username>[-_\w]+)/?'.format(settings.APP_URL_REGEX),
         views.AppPermsViewSet.as_view({'delete': 'destroy'})),

registry/private.py

@@ -19,9 +19,12 @@ def publish_release(source, config, target):
     Given a source image and dictionary of last-mile configuration,
     create a target Docker image on the registry.
 
-    For example publish_release('registry.local:5000/gabrtv/myapp:v22',
-                                {'ENVVAR': 'values'},
-                                'registry.local:5000/gabrtv/myapp:v23',)
+    For example::
+
+        publish_release('registry.local:5000/gabrtv/myapp:v22',
+                        {'ENVVAR': 'values'},
+                        'registry.local:5000/gabrtv/myapp:v23')
+
     results in a new Docker image at 'registry.local:5000/gabrtv/myapp:v23' which
     contains the new configuration as ENV entries.
     """