Merge branch 'documentation' into 'master'

write a new shiny and comprehensive documentation

See merge request ae/Sith!224

.envrc

+source ./env/bin/activate
\ No newline at end of file

.gitignore

@@ -13,3 +13,4 @@ sith/settings_custom.py
 sith/search_indexes/
 .coverage
 coverage_report/
+doc/_build

.gitlab-ci.yml

@@ -15,6 +15,8 @@ test:
   - coverage run ./manage.py test
   - coverage html
   - coverage report
+  - cd doc
+  - make html # Make documentation
   artifacts:
     paths:
       - coverage_report/

.readthedocs.yml

+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the doc/ directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.6
+  install:
+    - requirements: requirements.txt
\ No newline at end of file

CONTRIBUTING.md

-*Contribuer c'est la vie*
-=========================
-
-Hey ! Tu veux devenir un mec bien et en plus devenir bon en python si tu l'es pas déjà ?
-Il se trouve que le sith AE prévu pour l'été 2016 a besoin de toi !
-
-Pour faire le sith, on utilise le framework Web [Django](https://docs.djangoproject.com/fr/1.11/intro/)  
-N'hésite pas à lire les tutos et à nous demander (ae.info@utbm.fr).
-
-Bon, passons aux choses sérieuses, pour bidouiller le sith sans le casser :  
-Ben en fait, tu peux pas le casser, tu vas juste t'amuser comme un petit fou sur un clone du sith.
-
-C'est pas compliqué, il suffit d'avoir [Git](http://www.git-scm.com/book/fr/v2), python et pip (pour faciliter la gestion des paquets python).
-
-Tout d'abord, tu vas avoir besoin d'un compte Gitlab pour pouvoir te connecter.  
-Ensuite, tu fais :
-`git clone https://ae-dev.utbm.fr/ae/Sith.git`
-Avec cette commande, tu clones le sith AE dans le dossier courant.
-
-```bash
-cd Sith
-virtualenv --system-site-packages --python=python3 env
-source env/bin/activate
-pip install -r requirements.txt
-./manage runserver
-```
-
-Attention aux dépendances système, à voir dans le README.md
-
-Maintenant, faut passer le sith en mode debug dans le fichier de settings personnalisé.
-
-```bash
-echo "DEBUG=True" > sith/settings_custom.py
-echo 'SITH_URL = "localhost:8000"' >> sith/settings_custom.py
-```
-
-Enfin, il s'agit de créer la base de donnée de test lors de la première utilisation
-
-```bash
-./manage.py setup
-```
-
-Et pour lancer le sith, tu fais `python3 manage.py runserver`
-
-Voilà, c'est le sith AE. Il y a des issues dans le gitlab qui sont à régler. Si tu as un domaine qui t'intéresse, une appli que tu voudrais développer, n'hésites pas et contacte-nous.
-Va, et que l'AE soit avec toi.
-
-# Black
-
-Pour uniformiser le formattage du code nous utilisons [Black](https://github.com/ambv/black). Cela permet d'avoir le même codestyle et donc le codereview prend moins de temps. Tout étant dans le même format, il est plus facile pour chacun de comprendre le code de chacun ! Cela permet aussi d'éviter des erreurs (y parait 🤷‍♀️).
-
-Installation de black:
-
-```bash
-pip install black
-```
-
-## Sous VsCode:
-Attention, pour VsCode, Black doit être installé dans votre virtualenv !
-Ajouter ces deux lignes dans les settings de VsCode
-
-```json
-{
-    "python.formatting.provider": "black",
-    "editor.formatOnSave": true
-}
-```
-
-## Sous Sublime Text
-Il faut installer le plugin [sublack](https://packagecontrol.io/packages/sublack) depuis Package Control.
-
-Il suffit ensuite d'ajouter dans les settings du projet (ou en global)
-
-```json
-{
-    "sublack.black_on_save": true
-}
-```
-
-Si vous utilisez le plugin [anaconda](http://damnwidget.github.io/anaconda/), pensez à modifier les paramètres du linter pep8 pour éviter de recevoir des warnings dans le formatage de black
-
-```json
-{
-    "pep8_ignore": [
-      "E203",
-      "E266",
-      "E501",
-      "W503"
-    ]
-}
-```
-
-Sites et doc cools
-------------------
-
-[Classy Class-Based Views](http://ccbv.co.uk/projects/Django/1.11/)
-
-Helpers:
-
-`./manage.py makemessages --ignore "env/*" -e py,jinja`
-
-`for f in $(find . -name "*.py" ! -path "*migration*" ! -path "./env/*" ! -path "./doc/*"); do cat ./doc/header "$f" > /tmp/temp && mv /tmp/temp "$f"; done`
-
-
-
-

CONTRIBUTING.rst

+Pour contribuer au projet, vous pouvez vous référer à la documentation disponible à https://sith-ae.readthedocs.io/.
+
+Et n'oubliez pas, contribuer c'est la vie !
\ No newline at end of file

README.md

-[![pipeline status](https://ae-dev.utbm.fr/ae/Sith/badges/master/pipeline.svg)](https://ae-dev.utbm.fr/ae/Sith/commits/master)
-[![coverage report](https://ae-dev.utbm.fr/ae/Sith/badges/master/coverage.svg)](https://ae-dev.utbm.fr/ae/Sith/commits/master)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
-[![project chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://ae-dev.zulipchat.com)
-
-## Sith AE
-
-### Dependencies:
-See requirements.txt
-
-You may need to install some dev libraries like `libmysqlclient-dev`, `libssl-dev`, `libjpeg-dev`, `python3-xapian`, or `zlib1g-dev` to install all the
-requiered dependancies with pip. You may also need `mysql-client`. Don't also forget `python3-dev` if you don't have it
-already.
-
-You can check all of them with:
-
-```bash
-sudo apt install libmysqlclient-dev libssl-dev libjpeg-dev zlib1g-dev python3-dev libffi-dev python3-dev libgraphviz-dev pkg-config python3-xapian gettext
-```
-
-On macos, you will need homebrew
-
-```bash
-brew install xapian
-```
-
-If it doesn't work it's because it need [this pull request](https://github.com/Homebrew/homebrew-core/pull/34835) to be validated.
-
-The development is done with sqlite, but it is advised to set a more robust DBMS for production (Postgresql for example)
-
-### Get started
-
-To start working on the project, just run the following commands:
-
-```bash
-git clone https://ae-dev.utbm.fr/ae/Sith.git
-cd Sith
-virtualenv --system-site-packages --python=python3 env
-source env/bin/activate
-pip install -r requirements.txt
-./manage.py setup
-```
-
-To start the simple development server, just run `python3 manage.py runserver`
-
-For more informations, check out the CONTRIBUTING.md file.
-
-### Logging errors with sentry
-
-To connect the app to sentry.io, you must set the variable SENTRY_DSN in your settings custom. It's composed of the full link given on your sentry project
-
-### Generating documentation
-
-There is a Doxyfile at the root of the project, meaning that if you have Doxygen, you can run `doxygen Doxyfile` to
-generate a complete HTML documentation that will be available in the *./doc/html/* folder.
-
-### Collecting statics for production:
-
-We use scss in the project. In development environment (DEBUG=True), scss is compiled every time the file is needed. For production, it assumes you have already compiled every files and to do so, you need to use the following commands : 
-
-```bash
-./manage.py collectstatic # To collect statics
-./manage.py compilestatic # To compile scss in those statics
-```
-
-### Misc about development
-
-#### Controlling the rights
-
-When you need to protect an object, there are three levels:
-  * Editing the object properties
-  * Editing the object various values
-  * Viewing the object
-
-Now you have many solutions in your model:
-  * You can define a `is_owned_by(self, user)`, a `can_be_edited_by(self, user)`, and/or a `can_be_viewed_by(self, user)`
-    method, each returning True is the user passed can edit/view the object, False otherwise.   
-    This allows you to make complex request when the group solution is not powerful enough.    
-    It's useful too when you want to define class-wide permissions, e.g. the club members, that are viewable only for
-    Subscribers.
-  * You can add an `owner_group` field, as a ForeignKey to Group.  Second is an `edit_groups` field, as a ManyToMany to
-    Group, and third is a `view_groups`, same as for edit.
-
-Finally, when building a class based view, which is highly advised, you just have to inherit it from CanEditPropMixin,
-CanEditMixin, or CanViewMixin, which are located in core.views. Your view will then be protected using either the
-appropriate group fields, or the right method to check user permissions.
-
-#### Counting the number of line of code
-
-```bash
-sudo apt install cloc
-cloc --exclude-dir=doc,env .
-```
-
-#### Updating doc/SYNTAX.md
-
-If you make an update in the Markdown syntax parser, it's good to document
-update the syntax reference page in `doc/SYNTAX.md`. But updating this file will
-break the tests if you don't update the corresponding `doc/SYNTAX.html` file at
-the same time.  
-To do that, simply run `./manage.py markdown > doc/SYNTAX.html`,
-and the tests should pass again.
-
-

README.rst

+.. image:: https://ae-dev.utbm.fr/ae/Sith/badges/master/pipeline.svg
+  :target: https://ae-dev.utbm.fr/ae/Sith/commits/master
+  :alt: pipeline status
+
+.. image:: https://readthedocs.org/projects/sith-ae/badge/?version=latest
+  :target: https://sith-ae.readthedocs.io/?badge=latest
+  :alt: documentation Status
+
+.. image:: https://ae-dev.utbm.fr/ae/Sith/badges/master/coverage.svg
+  :target: https://ae-dev.utbm.fr/ae/Sith/commits/master
+  :alt: coverage report
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+  :target: https://github.com/ambv/black
+  :alt: code style: black
+
+.. image:: https://img.shields.io/badge/zulip-join_chat-brightgreen.svg
+  :target: https://ae-dev.zulipchat.com
+  :alt: project chat
+
+This is the source code of the UTBM's student association available at https://ae.utbm.fr/.
+
+All documentation is in the ``docs`` directory and online at https://sith-ae.readthedocs.io/. This documentation is written in French because it targets a French audience and it's too much work to maintain two versions. The code and code comments are strictly written in English.
+
+If you want to contribute, here's how we recommend to read the docs:
+
+* First, it's advised to read the about part of the project to understand the goals and the mindset of the current and previous maintainers and know what to expect to learn.
+* If in the first part you find you need more background about what we use, we provide some links to tutorials and documentation at the end of our documentation. Feel free to use it and complete it with what you found helpful.
+* Keep in mind that this documentation is thought to be read in order.
+
+To join our team :
+
+* Send a mail at mailto:ae.utbm.fr
+* Join our group chat at https://ae-dev.zulipchat.com
+* See and join our Trello at https://trello.com/b/YQOaF33m/site-ae.
+
+This project is licenced under GNU GPL, see the LICENSE file at the top of the repository for more details.

TODO.md

-# TODO
-
-## Easter eggs
-
-  * 'A' 'L' 'L' 'O': Entendre le Allooo de Madame Coucoune
-  * idem avec cacafe
-  * Un meat spin quelque part
-  * Konami code
-

com/models.py

@@ -149,6 +149,13 @@ class NewsDate(models.Model):
 class Weekmail(models.Model):
     """
     The weekmail class
+
+    :ivar title: Title of the weekmail
+    :ivar intro: Introduction of the weekmail
+    :ivar joke: Joke of the week
+    :ivar protip: Tip of the week
+    :ivar conclusion: Conclusion of the weekmail
+    :ivar sent: Track if the weekmail has been sent
     """
 
     title = models.CharField(_("title"), max_length=64, blank=True)
@@ -162,6 +169,10 @@ class Weekmail(models.Model):
         ordering = ["-id"]
 
     def send(self):
+        """
+        Send the weekmail to all users with the receive weekmail option opt-in.
+        Also send the weekmail to the mailing list in settings.SITH_COM_EMAIL.
+        """
         dest = [
             i[0]
             for i in Preferences.objects.filter(receive_weekmail=True).values_list(
@@ -183,19 +194,31 @@ class Weekmail(models.Model):
             Weekmail().save()
 
     def render_text(self):
+        """
+        Renders a pure text version of the mail for readers without HTML support.
+        """
         return render(
             None, "com/weekmail_renderer_text.jinja", context={"weekmail": self}
         ).content.decode("utf-8")
 
     def render_html(self):
+        """
+        Renders an HTML version of the mail with images and fancy CSS.
+        """
         return render(
             None, "com/weekmail_renderer_html.jinja", context={"weekmail": self}
         ).content.decode("utf-8")
 
     def get_banner(self):
+        """
+        Return an absolute link to the banner.
+        """
         return "http://" + settings.SITH_URL + static("com/img/weekmail_bannerA19.jpg")
 
     def get_footer(self):
+        """
+        Return an absolute link to the footer.
+        """
         return "http://" + settings.SITH_URL + static("com/img/weekmail_footerA19.jpg")
 
     def __str__(self):

core/management/commands/compilemessages.py

+#!/usr/bin/env python3
+# -*- coding:utf-8 -*
+#
+# Copyright 2019
+# - Sli <antoine@bartuccio.fr>
+#
+# Ce fichier fait partie du site de l'Association des Étudiants de l'UTBM,
+# http://ae.utbm.fr.
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License a published by the Free Software
+# Foundation; either version 3 of the License, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+# details.
+#
+# You should have received a copy of the GNU General Public License along with
+# this program; if not, write to the Free Sofware Foundation, Inc., 59 Temple
+# Place - Suite 330, Boston, MA 02111-1307, USA.
+#
+#
+
+
+import os
+from django.core.management.commands import compilemessages
+
+
+class Command(compilemessages.Command):
+    """
+    Wrap call to compilemessages to avoid building whole env
+    """
+
+    help = """
+        The usage is the same as the real compilemessages
+         but it goes into the sith dir first
+    """
+
+    def handle(self, *args, **options):
+
+        os.chdir("sith")
+        super(Command, self).handle(*args, **options)

core/management/commands/documentation.py

+#!/usr/bin/env python3
+# -*- coding:utf-8 -*
+#
+# Copyright 2019
+# - Sli <antoine@bartuccio.fr>
+#
+# Ce fichier fait partie du site de l'Association des Étudiants de l'UTBM,
+# http://ae.utbm.fr.
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License a published by the Free Software
+# Foundation; either version 3 of the License, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+# details.
+#
+# You should have received a copy of the GNU General Public License along with
+# this program; if not, write to the Free Sofware Foundation, Inc., 59 Temple
+# Place - Suite 330, Boston, MA 02111-1307, USA.
+#
+#
+
+import os
+import sys
+
+from http.server import test, CGIHTTPRequestHandler
+
+from django.core.management.base import BaseCommand
+
+# TODO Django 2.2 : implement autoreload following
+# https://stackoverflow.com/questions/42907285/django-autoreload-add-watched-file
+
+
+class Command(BaseCommand):
+    help = "Generate Sphinx documentation and launch basic server"
+
+    default_addr = "127.0.0.1"
+    default_port = "8080"
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "addrport", nargs="?", help="Optional port number, or ipaddr:port"
+        )
+
+    def handle(self, *args, **kwargs):
+        os.chdir("doc")
+        err = os.system("make html")
+
+        if err != 0:
+            self.stdout.write("A build error occured, exiting")
+            sys.exit(err)
+
+        os.chdir("_build/html")
+        addr = self.default_addr
+        port = self.default_port
+        if kwargs["addrport"]:
+            addrport = kwargs["addrport"].split(":")
+
+            addr = addrport[0]
+
+            if len(addrport) > 1:
+                port = addrport[1]
+
+            if not port.isnumeric():
+                self.stdout.write("%s is not a valid port" % (port,))
+                sys.exit(0)
+
+        test(HandlerClass=CGIHTTPRequestHandler, port=int(port), bind=addr)

core/management/commands/populate.py

@@ -377,13 +377,6 @@ Welcome to the wiki page!
 
 """,
             ).save()
-            # Adding README
-            p = Page(name="README")
-            p.save(force_lock=True)
-            p.view_groups = [settings.SITH_GROUP_PUBLIC_ID]
-            p.save(force_lock=True)
-            with open(os.path.join(root_path) + "/README.md", "r") as rm:
-                PageRev(page=p, title="README", author=skia, content=rm.read()).save()
 
             # Subscription
             default_subscription = "un-semestre"

core/views/__init__.py

@@ -81,18 +81,60 @@ def internal_servor_error(request):
 
 
 def can_edit_prop(obj, user):
+    """
+    :param obj: Object to test for permission
+    :param user: core.models.User to test permissions against
+    :return: if user is authorized to edit object properties
+    :rtype: bool
+
+    :Example:
+
+    .. code-block:: python
+
+        if not can_edit_prop(self.object ,request.user):
+            raise PermissionDenied
+
+    """
     if obj is None or user.is_owner(obj):
         return True
     return False
 
 
 def can_edit(obj, user):
+    """
+    :param obj: Object to test for permission
+    :param user: core.models.User to test permissions against
+    :return: if user is authorized to edit object
+    :rtype: bool
+
+    :Example:
+
+    .. code-block:: python
+
+        if not can_edit(self.object ,request.user):
+            raise PermissionDenied
+
+    """
     if obj is None or user.can_edit(obj):
         return True
     return can_edit_prop(obj, user)
 
 
 def can_view(obj, user):
+    """
+    :param obj: Object to test for permission
+    :param user: core.models.User to test permissions against
+    :return: if user is authorized to see object
+    :rtype: bool
+
+    :Example:
+
+    .. code-block:: python
+
+        if not can_view(self.object ,request.user):
+            raise PermissionDenied
+
+    """
     if obj is None or user.can_view(obj):
         return True
     return can_edit(obj, user)
@@ -102,6 +144,8 @@ class CanCreateMixin(View):
     """
     This view is made to protect any child view that would create an object, and thus, that can not be protected by any
     of the following mixin
+
+    :raises: PermissionDenied
     """
 
     def dispatch(self, request, *arg, **kwargs):
@@ -123,6 +167,8 @@ class CanEditPropMixin(View):
     to only the owner group of the given object.
     In other word, you can make a view with this view as parent, and it would be retricted to the users that are in the
     object's owner_group
+
+    :raises: PermissionDenied
     """
 
     def dispatch(self, request, *arg, **kwargs):
@@ -150,6 +196,8 @@ class CanEditMixin(View):
     """
     This view makes exactly the same thing as its direct parent, but checks the group on the edit_groups field of the