Merge branch 'documentation' into 'master'

add autoreload/build to documentation server and enhace documentation

See merge request !246

README.rst

@@ -25,7 +25,7 @@ All documentation is in the ``docs`` directory and online at https://sith-ae.rea
 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.
+* If in the first part you realize that 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 :

core/management/commands/documentation.py

@@ -25,13 +25,12 @@
 
 import os
 import sys
+import signal
 
 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
+from django.utils import autoreload
 
 
 class Command(BaseCommand):
@@ -45,15 +44,15 @@ class Command(BaseCommand):
             "addrport", nargs="?", help="Optional port number, or ipaddr:port"
         )
 
-    def handle(self, *args, **kwargs):
-        os.chdir("doc")
+    def build_documentation(self):
+        os.chdir(os.path.join(self.project_dir, "doc"))
         err = os.system("make html")
 
         if err != 0:
-            self.stdout.write("A build error occured, exiting")
-            sys.exit(err)
+            self.stdout.write("A build error occured")
 
-        os.chdir("_build/html")
+    def start_server(self, **kwargs):
+        os.chdir(os.path.join(self.project_dir, "doc", "_build/html"))
         addr = self.default_addr
         port = self.default_port
         if kwargs["addrport"]:
@@ -69,3 +68,25 @@ class Command(BaseCommand):
                 sys.exit(0)
 
         test(HandlerClass=CGIHTTPRequestHandler, port=int(port), bind=addr)
+
+    def build_and_start_server(self, **kwargs):
+        self.build_documentation()
+        self.start_server(**kwargs)
+
+    def handle(self, *args, **kwargs):
+        self.project_dir = os.getcwd()
+
+        signal.signal(signal.SIGTERM, lambda *args: sys.exit(0))
+        try:
+            if os.environ.get(autoreload.DJANGO_AUTORELOAD_ENV) == "true":
+                reloader = autoreload.get_reloader()
+                reloader.watch_dir(os.path.join(self.project_dir, "doc"), "**/*.rst")
+                autoreload.logger.info(
+                    "Watching for file changes with %s", reloader.__class__.__name__
+                )
+                autoreload.start_django(reloader, self.build_and_start_server, **kwargs)
+            else:
+                exit_code = autoreload.restart_with_reloader()
+                sys.exit(exit_code)
+        except KeyboardInterrupt:
+            pass

core/models.py

@@ -65,11 +65,19 @@ class MetaGroupManager(AuthGroupManager):
 
 
 class Group(AuthGroup):
+    """
+    Implement both RealGroups and Meta groups
+
+    Groups are sorted by their is_meta property
+    """
+
+    #: If False, this is a RealGroup
     is_meta = models.BooleanField(
         _("meta group status"),
         default=False,
         help_text=_("Whether a group is a meta group or not"),
     )
+    #: Description of the group
     description = models.CharField(_("description"), max_length=60)
 
     class Meta:
@@ -83,6 +91,15 @@ class Group(AuthGroup):
 
 
 class MetaGroup(Group):
+    """
+    MetaGroups are dynamically created groups.
+    Generaly used with clubs where creating a club creates two groups:
+
+        * club-SITH_BOARD_SUFFIX
+        * club-SITH_MEMBER_SUFFIX
+    """
+
+    #: Assign a manager in a way that MetaGroup.objects only return groups with is_meta=False
     objects = MetaGroupManager()
 
     class Meta:
@@ -94,6 +111,12 @@ class MetaGroup(Group):
 
 
 class RealGroup(Group):
+    """
+    RealGroups are created by the developer.
+    Most of the time they match a number in settings to be easily used for permissions.
+    """
+
+    #: Assign a manager in a way that MetaGroup.objects only return groups with is_meta=True
     objects = RealGroupManager()
 
     class Meta:

doc/devenv/populate.rst

+Générer l'environnement avec populate
+=====================================
+
+Lors de l'installation du site en local (via la commande `setup`), la commande **populate** est appelée.
+
+Cette commande génère entièrement la base de donnée de développement. Elle se situe dans `core/management/commands/populate.py`.
+
+Utilisations :
+
+.. code-block:: shell
+
+    ./manage.py setup # Génère la base de test
+    ./manage.py setup --prod # Ne génère que le schéma de base et les données strictement nécessaires au fonctionnement
+
+Les groupes du site de dev
+==========================
+
+La liste exhaustive des groupes est disponible ici : :ref:`groups-list`.
+
+Les clubs du site de dev
+========================
+
+Voici la liste des groupes avec leur arborescence d'appartenance. 
+
+* AE
+
+    - Bibo'UT
+    - Carte AE
+    - Guy'UT
+
+        + Woenzel'UT
+
+    - Troll Penché
+
+* BdF
+* Laverie
+
+Les utilisateurs du site de dev
+===============================
+
+Le mot de passe de tous les utilisateurs est **plop**.
+
+* **root** -> Dans le groupe Root et cotisant
+* **skia** -> responsable info AE et cotisant, barmen MDE
+* **public** -> utilisateur non cotisant et sans groupe
+* **subscriber** -> utilisateur cotisant et sans groupe
+* **old_subscriber** -> utilisateur anciennement cotisant et sans groupe
+* **counter** -> administrateur comptoir
+* **comptable** -> administrateur comptabilité
+* **guy** -> utilisateur non cotisant et sans groupe
+* **rbatsbak** -> utilisateur non cotisant et sans groupe
+* **sli** -> cotisant avec carte étudiante attachée au compte
+* **krophil** -> cotisant avec des plein d'écocups, barmen foyer
+* **comunity** -> administrateur communication
+* **tutu** -> administrateur pédagogie
\ No newline at end of file

doc/index.rst

@@ -33,6 +33,13 @@ Bienvenue sur la documentation du Sith de l'AE
     :caption: La surcouche "Site AE"
 
     overlay/rights
+    overlay/groups
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contenu de l'environnement de développement
+
+    devenv/populate
 
 .. toctree::
     :maxdepth: 1
@@ -63,6 +70,7 @@ Python et Django
 ~~~~~~~~~~~~~~~~
 
 * `Apprendre Python <https://openclassrooms.com/fr/courses/235344-apprenez-a-programmer-en-python>`__
+* `Apprendre Django <https://openclassrooms.com/fr/courses/1871271-developpez-votre-site-web-avec-le-framework-django>`__
 * `Documentation de Django <https://docs.djangoproject.com/fr/1.11/>`__
 * `Classy Class-Based Views <http://ccbv.co.uk/projects/Django/1.11/>`__
 

doc/overlay/groups.rst

+Le système de groupes
+=====================
+
+Il existe deux types de groupes sur le site AE. L'un se base sur des groupes enregistrés en base de données pendant le développement, c'est le système de groupes réels. L'autre est plus dynamique et comprend tous les groupes générés pendant l'exécution et l'utilisation du programme. Cela correspond généralement aux groupes liés aux clubs. Ce sont les méta groupes.
+
+La définition d'un groupe
+--------------------------
+
+Comme on peut l'observer, il existe une entrée de groupes dans la base de données. Cette classe implémente à la fois les groupes réels et les méta groupes.
+
+Ce qui différencie ces deux types de groupes ce sont leur utilisation et leur manière d'être générés. La distinction est faite au travers de la propriété `is_meta`.
+
+.. autoclass:: core.models.Group
+    :members:
+
+Les groupes réels
+-----------------
+
+Pour simplifier l'utilisation de ces deux types de groupe, il a été crée une classe proxy (c'est à dire qu'elle ne correspond pas à une vraie table en base de donnée) qui encapsule leur utilisation. RealGroup peut être utilisé pour créer des groupes réels dans le code et pour faire une recherche sur ceux-ci (dans le cadre d'une vérification de permissions par exemple).
+
+.. autoclass:: core.models.RealGroup
+    :members:
+
+.. note::
+
+    N'oubliez pas de créer une variable dans les settings contenant le numéro du groupe pour facilement l'utiliser dans le code plus tard. Ces variables sont du type `SITH_GROUP_GROUPE_NAME_ID`.
+
+Les méta groupes
+----------------
+
+Les méta groupes, comme expliqué précédemment, sont utilisés dans les contextes où il est nécessaire de créer un groupe *on runtime*. Les objets `MetaGroup`, bien que dynamiques, doivent tout de même s'enregistrer en base de donnée comme des vrais groupes afin de pouvoir être affectés dans les permissions d'autres objets, comme un forum ou une page de wiki par exemple. C'est principalement utilisé au travers des clubs qui génèrent automatiquement deux groupes à leur création :
+
+* club-bureau : contient tous les membres d'un club **au dessus** du grade défini dans settings.SITH_MAXIMUM_FREE_ROLE.
+* club-membres : contient tous les membres d'un club **en dessous** du grade défini dans settings.SITH_MAXIMUM_FREE_ROLE.
+
+.. autoclass:: core.models.MetaGroup
+    :members:
+
+
+.. _groups-list:
+
+La liste des groupes réels
+--------------------------
+
+Les groupes réels existant par défaut dans le site sont les suivants :
+
+Groupes gérés automatiquement par le site :
+
+* **Public** -> tous les utilisateurs du site
+* **Subscribers** -> tous les cotisants du site
+* **Old subscribers** -> tous les anciens cotisants
+
+Groupes gérés par les administrateurs (à appliquer à la main sur un utilisateur) :
+
+* **Root** -> administrateur global du site
+* **Accounting admin** -> les administrateurs de la comptabilité
+* **Communication admin** -> les administrateurs de la communication
+* **Counter admin** -> les administrateurs des comptoirs (foyer et autre)
+* **SAS admin** -> les administrateurs du SAS
+* **Forum admin** -> les administrateurs du forum
+* **Pedagogy admin** -> les administrateurs de la pédagogie (guide des UVs)
+* **Banned from buying alcohol** -> les utilisateurs interdits de vente d'alcool (non mineurs)
+* **Banned from counters** -> les utilisateurs interdits d'utilisation des comptoirs
+* **Banned to subscribe** -> les utilisateurs interdits de cotisation

doc/start/install.rst

@@ -7,12 +7,14 @@ Dépendances du système
 Certaines dépendances sont nécessaires niveau système :
 
 * virtualenv
-* limysqlclient
+* libmysqlclient
 * libssl
 * libjpeg
 * python3-xapian
 * zlib1g-dev
 * python3
+* gettext
+* graphviz
 * mysql-client (pour migrer de l'ancien site)
 
 Sur Ubuntu
@@ -20,8 +22,8 @@ Sur Ubuntu
 
 .. sourcecode:: 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 git
-	sudo pip3 install virtualenv
+    sudo apt install libmysqlclient-dev libssl-dev libjpeg-dev zlib1g-dev python3-dev libffi-dev python3-dev libgraphviz-dev pkg-config python3-xapian gettext git
+    sudo pip3 install virtualenv
 
 Sur MacOS
 ~~~~~~~~~
@@ -30,26 +32,45 @@ Pour installer les dépendances, il est fortement recommandé d'installer le ges
 
 .. sourcecode:: bash
 
-	brew install git python xapian
-	pip install virtualenv
+    brew install git python xapian graphviz
+
+    # Si vous aviez une version de python ne venant pas de homebrew
+    brew link --overwrite python
+
+
+    # Pour bien configurer gettext
+    brew link gettext # (suivez bien les instructions supplémentaires affichées)
+
+    # Pour installer virtualenv
+    pip3 install virtualenv
+
+.. note::
+
+    Si vous rencontrez des erreurs lors de votre configuration, n'hésitez pas à vérifier l'état de votre installation homebrew avec :code:`brew doctor`
 
 Installer le projet
 -------------------
 
 .. sourcecode:: bash
 
-	git clone https://ae-dev.utbm.fr/ae/Sith.git
-	cd Sith
+    git clone https://ae-dev.utbm.fr/ae/Sith.git
+    cd Sith
+
+    # Prépare et active l'environnement du projet
+    virtualenv --system-site-packages --python=python3 env
+    source env/bin/activate
+
+    # Installe les dépendances du projet
+    pip install -r requirements.txt
 
-	# Prépare et active l'environnement du projet
-	virtualenv --system-site-packages --python=python3 env
-	source env/bin/activate
+    # Si vous avez des problèmes avec graphiviz
+    pip install pygraphviz --install-option="--include-path=/usr/include/graphviz" --install-option="--library-path=/usr/lib/graphviz/"
 
-	# Installe les dépendances du projet
-	pip install -r requirements.txt
+    # Prépare la base de donnée
+    ./manage.py setup
 
-	# Prépare la base de donnée
-	./manage.py setup
+    # Installe les traductions
+    ./manage compilemessages
 
 .. note::
 
@@ -62,8 +83,8 @@ Lorsqu'on souhaite développer pour le site, il est nécessaire de passer le log
 
 .. sourcecode:: bash
 
-	echo "DEBUG=True" > sith/settings_custom.py
-	echo 'SITH_URL = "localhost:8000"' >> sith/settings_custom.py
+    echo "DEBUG=True" > sith/settings_custom.py
+    echo 'SITH_URL = "localhost:8000"' >> sith/settings_custom.py
 
 Démarrer le serveur de développement
 ------------------------------------
@@ -72,11 +93,11 @@ Il faut toujours avoir préalablement activé l'environnement virtuel comme fait
 
 .. sourcecode:: bash
 
-	./manage.py runserver
+    ./manage.py runserver
 
 .. note::
 
-	Le serveur est alors accessible à l'adresse http://localhost:8000.
+    Le serveur est alors accessible à l'adresse http://localhost:8000.
 
 Générer la documentation
 ------------------------
@@ -85,9 +106,14 @@ La documentation est automatiquement mise en ligne sur readthedocs à chaque env
 
 Pour l'utiliser en local ou globalement pour la modifier, il existe une commande du site qui génère la documentation et lance un serveur la rendant accessible à l'adresse http://localhost:8080.
 
+Cette commande génère la documentation à chacune de ses modifications, inutile de relancer le serveur à chaque fois.
+
 .. sourcecode:: bash
 
-	./manage.py documentation
+    ./manage.py documentation
+
+    # Il est possible de spécifier un port et une adresse d'écoute différente
+    ./manage.py documentation adresse:port
 
 Lancer les tests
 ----------------