Complete doc for the ArticleViewset

apps/rp/api/views.py

@@ -11,24 +11,77 @@ ArticleMixin = get_viewset_transition_actions_mixin(Article)
 
 class ArticleViewSet(ArticleMixin, viewsets.ModelViewSet):
     """
+    articles:
+    This viewset describes all the method usable on the API
+    using Article.
+
+    The RequestBody is only needed for the create, update and partial_update
+    functions.
+
     list:
     List all known articles in database.
 
+    permissions ```None```
+
     create:
     Create an article from its URL and inserts it with the
-    status NEW
+    status _NEW_.
+
+    permissions ```None```
 
     read:
-    Get a specific article by id
+    Get a specific article by id.
+
+    permissions ```None```
 
     update:
-    Change the content of an article
+    Change the content of an article.
+
+    permissions ```rp.can_edit```
 
     partial_update:
-    Change only some fields of an article
+    Change only some fields of an article.
+
+    permissions ```rp.can_edit```
 
     downvote:
-    Decrement the score of an article by one.
+    Decrement the score of an article by one. If the score goes below the
+    ```ARTICLE_SCORE_THRESHOLD```, the article will stay in _DRAFT_ state.
+
+    permissions ```rp.can_vote```
+
+    upvote:
+    Increment the score of an article by one. It it goes above the
+    ```ARTICLE_SCORE_THRESHOLD```, its state will change to _DRAFT_.
+
+    permissions ```rp.can_vote```
+
+    recover:
+    Force an Article status at _DRAFT_. It is used to recover _REJECTED_
+    articles or ones with a score below ```ARTICLE_SCORE_THRESHOLD```.
+
+    permissions ```rp.can_change_status```
+
+    publish:
+    Change the state of a _DRAFT_ article to _PUBLISHED_
+
+    permissions ```rp.can_change_status```
+
+    reject:
+    Force an article status to _REJECTED_. It can only be brought back with
+    the recover function.
+
+    permissions ```rp.can_change_status```
+
+    set_priority:
+    Set the boolean priority of an article to True.
+
+    permissions ```rp.can_change_priority```
+
+    unset_priority:
+    Set the boolean priority of an article to False.
+
+    permissions ```rp.can_change_priority```
     """
     queryset = Article.objects.all()
     serializer_class = ArticleSerializer

apps/rp/models.py

@@ -123,7 +123,7 @@ class Article(VoteMixin):
     @transition(field=status, source='NEW', target='DRAFT',
                 permission="rp.can_change_status")
     def recover(self):
-        """ Force an article to be considered as a draft. """
+        """ Force an article to be considered as _DRAFT_. """
         pass
 
     @transition(field=status, source=['NEW', 'DRAFT'], target='REJECTED',