Merge branch 'Improving-documentation' into 'rp2'

Improving documentation

Closes #39, #37, and #35

See merge request !29

apps/rp/api/serializers.py

@@ -20,10 +20,9 @@ class TagListSerializer(serializers.Field):
 class ArticleSerializer(serializers.ModelSerializer):
     #: List of short tags to describe the article (eg. "Privacy", "Copyright")
     tags = TagListSerializer(help_text="""
-        List of short tags to describe the article (eg."Privacy", "Copyright").
-        Can also be a list of tags or an empty list.
+        List of short tags to describe the article (eg."Privacy, Copyright").
+        Must be a list of tags, coma separated (or an empty string).
         """)
-
     und_score_up = serializers.IntegerField(
             required=False,
             help_text="This is used to increase the vote count by this value")

apps/rp/api/views.py

@@ -10,6 +10,81 @@ 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_. If the article already exists, it is upvoted
+    by one, and the tags are merged (in case new tags are given
+    to this command).
+
+    permissions ```None```
+
+    read:
+    Get a specific article by id.
+
+    permissions ```None```
+
+    update:
+    Change the content of an article.
+
+    permissions ```rp.can_edit```
+
+    partial_update:
+    Change only some fields of an article.
+
+    permissions ```rp.can_edit```
+
+    downvote:
+    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

@@ -91,7 +91,7 @@ class Article(VoteMixin):
     #: priority: True if article have priority
     priority = models.BooleanField(default=False)
 
-    #: List of short tags to describe the article (eg. "Privacy", "Copyright")
+    #: Comma separated list of short tags to describe the article (eg: "Privacy", "Copyright").
     tags = TaggableManager(blank=True)
 
     class Meta:
@@ -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',