Serializer docstrings

Author: humitos

readthedocs/api/v3/serializers.py

@@ -32,7 +32,13 @@ def _absolute_url(self, path):
         return urllib.parse.urlunparse((scheme, domain, path, '', '', ''))
 
 
-class BuildTriggerSerializer(serializers.ModelSerializer):
+class BuildCreateSerializer(serializers.ModelSerializer):
+
+    """
+    Used when triggering (create action) a ``Build`` for a specific ``Version``.
+
+    This serializer validates that no field is sent at all in the request.
+    """
 
     class Meta:
         model = Build
@@ -76,6 +82,15 @@ def get_project(self, obj):
 
 class BuildConfigSerializer(FlexFieldsSerializerMixin, serializers.Serializer):
 
+    """
+    Render ``Build.config`` property without modifying it.
+
+    .. note::
+
+       Any change on the output of that property will be reflected here,
+       which may produce incompatible changes in the API.
+    """
+
     def to_representation(self, obj):
         # For now, we want to return the ``config`` object as it is without
         # manipulating it.
@@ -231,6 +246,12 @@ def get_downloads(self, obj):
 
 class VersionUpdateSerializer(serializers.ModelSerializer):
 
+    """
+    Used when modifying (update action) a ``Version``.
+
+    It only allows to make the Version active/non-active and private/public.
+    """
+
     class Meta:
         model = Version
         fields = [

readthedocs/api/v3/views.py

@@ -31,7 +31,7 @@
 from .renderer import AlphabeticalSortedJSONRenderer
 from .serializers import (
     BuildSerializer,
-    BuildTriggerSerializer,
+    BuildCreateSerializer,
     ProjectSerializer,
     UserSerializer,
     VersionSerializer,
@@ -252,7 +252,7 @@ class BuildsViewSet(APIv3Settings, APIAuthMixin, NestedViewSetMixin,
     def get_serializer_class(self):
         if self.action in ('list', 'retrieve'):
             return BuildSerializer
-        return BuildTriggerSerializer
+        return BuildCreateSerializer
 
     def create(self, request, **kwargs):
         parent_lookup_project__slug = kwargs.get('parent_lookup_project__slug')