Merge pull request #716 from ae-utbm/docs

Use MkDocs for documentation

.github/workflows/deploy.yml

@@ -37,7 +37,7 @@ jobs:
           pushd ${{secrets.SITH_PATH}}
 
           git pull
-          poetry install
+          poetry install --with prod --without docs,tests
           poetry run ./manage.py install_xapian
           poetry run ./manage.py migrate
           echo "yes" | poetry run ./manage.py collectstatic

.github/workflows/deploy_docs.yml

@@ -0,0 +1,21 @@
+name: deploy_docs
+on:
+  push:
+    branches:
+      - master
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ./.github/actions/setup_project
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: poetry run mkdocs gh-deploy --force

.github/workflows/taiste.yml

@@ -36,7 +36,7 @@ jobs:
           pushd ${{secrets.SITH_PATH}}
 
           git pull
-          poetry install
+          poetry install --with prod --without docs,tests
           poetry run ./manage.py install_xapian
           poetry run ./manage.py migrate
           echo "yes" | poetry run ./manage.py collectstatic

README.md

@@ -1,40 +1,20 @@
-<p align="center">
-  <a href="#">
-    <img src="https://img.shields.io/badge/Code%20Style-Black-000000?style=for-the-badge">
-  </a>
-  <a href="#">
-    <img src="https://img.shields.io/github/checks-status/ae-utbm/sith3/master?logo=github&style=for-the-badge&label=BUILD">
-  </a>
-  <a href="https://sith-ae.readthedocs.io/">
-    <img src="https://img.shields.io/readthedocs/sith-ae?logo=readthedocs&style=for-the-badge">
-  </a>
-  <a href="https://discord.gg/XK9WfPsUFm">
-    <img src="https://img.shields.io/discord/971448179075731476?label=Discord&logo=discord&style=for-the-badge">
-  </a>
-</p>
+# Sith
 
-<h3 align="center">This is the source code of the UTBM's student association available at https://ae.utbm.fr/.</h3>
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](#)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![CI status](https://github.com/ae-utbm/sith3/actions/workflows/ci.yml/badge.svg)](#)
+[![Docs status](https://github.com/ae-utbm/sith3/actions/workflows/deploy_docs.yml/badge.svg)](https://ae-utbm.github.io/sith3)
+[![Built with Material for MkDocs](https://img.shields.io/badge/Material_for_MkDocs-526CFE?style=default&logo=MaterialForMkDocs&logoColor=white)](https://squidfunk.github.io/mkdocs-material/)
+[![discord](https://img.shields.io/discord/971448179075731476?label=discord&logo=discord&style=default)](https://discord.gg/xk9wfpsufm)
 
-<p align="justify">All documentation is in the <code>docs</code> 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.</p>
+### This is the source code of the UTBM's student association available at [https://ae.utbm.fr/](https://ae.utbm.fr/).
 
-<h4>If you want to contribute, here's how we recommend to read the docs:</h4>
+All documentation is in the `docs` directory and online at [https://ae-utbm.github.io/sith3](https://ae-utbm.github.io/sith3). 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.
 
-<ul>
-  <li>
-    <p align="justify">
-      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.
-    </p>
-  </li>
-  <li>
-    <p align="justify">
-      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.
-    </p>
-  </li>
-  <li>
-    <p align="justify">
-      Keep in mind that this documentation is thought to be read in order.
-    </p>
-  </li>
-</ul>
+#### 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 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.
 
 > This project is licensed under GNU GPL, see the LICENSE file at the top of the repository for more details.

accounting/models.py

@@ -29,9 +29,7 @@
 
 
 class CurrencyField(models.DecimalField):
-    """
-    This is a custom database field used for currency
-    """
+    """Custom database field used for currency."""
 
     def __init__(self, *args, **kwargs):
         kwargs["max_digits"] = 12
@@ -71,30 +69,22 @@ def get_display_name(self):
         return self.name
 
     def is_owned_by(self, user):
-        """
-        Method to see if that object can be edited by the given user
-        """
+        """Check if that object can be edited by the given user."""
         if user.is_in_group(pk=settings.SITH_GROUP_ACCOUNTING_ADMIN_ID):
             return True
         return False
 
     def can_be_edited_by(self, user):
-        """
-        Method to see if that object can be edited by the given user
-        """
-        for club in user.memberships.filter(end_date=None).all():
-            if club and club.role == settings.SITH_CLUB_ROLES_ID["Treasurer"]:
-                return True
-        return False
+        """Check if that object can be edited by the given user."""
+        return user.memberships.filter(
+            end_date=None, club__role=settings.SITH_CLUB_ROLES_ID["Treasurer"]
+        ).exists()
 
     def can_be_viewed_by(self, user):
-        """
-        Method to see if that object can be viewed by the given user
-        """
-        for club in user.memberships.filter(end_date=None).all():
-            if club and club.role >= settings.SITH_CLUB_ROLES_ID["Treasurer"]:
-                return True
-        return False
+        """Check if that object can be viewed by the given user."""
+        return user.memberships.filter(
+            end_date=None, club__role_gte=settings.SITH_CLUB_ROLES_ID["Treasurer"]
+        ).exists()
 
 
 class BankAccount(models.Model):
@@ -119,9 +109,7 @@ def get_absolute_url(self):
         return reverse("accounting:bank_details", kwargs={"b_account_id": self.id})
 
     def is_owned_by(self, user):
-        """
-        Method to see if that object can be edited by the given user
-        """
+        """Check if that object can be edited by the given user."""
         if user.is_anonymous:
             return False
         if user.is_in_group(pk=settings.SITH_GROUP_ACCOUNTING_ADMIN_ID):
@@ -158,28 +146,22 @@ def get_absolute_url(self):
         return reverse("accounting:club_details", kwargs={"c_account_id": self.id})
 
     def is_owned_by(self, user):
-        """
-        Method to see if that object can be edited by the given user
-        """
+        """Check if that object can be edited by the given user."""
         if user.is_anonymous:
             return False
         if user.is_in_group(pk=settings.SITH_GROUP_ACCOUNTING_ADMIN_ID):
             return True
         return False
 
     def can_be_edited_by(self, user):
-        """
-        Method to see if that object can be edited by the given user
-        """
+        """Check if that object can be edited by the given user."""
         m = self.club.get_membership_for(user)
         if m and m.role == settings.SITH_CLUB_ROLES_ID["Treasurer"]:
             return True
         return False
 
     def can_be_viewed_by(self, user):
-        """
-        Method to see if that object can be viewed by the given user
-        """
+        """Check if that object can be viewed by the given user."""
         m = self.club.get_membership_for(user)
         if m and m.role >= settings.SITH_CLUB_ROLES_ID["Treasurer"]:
             return True
@@ -202,9 +184,7 @@ def get_display_name(self):
 
 
 class GeneralJournal(models.Model):
-    """
-    Class storing all the operations for a period of time
-    """
+    """Class storing all the operations for a period of time."""
 
     start_date = models.DateField(_("start date"))
     end_date = models.DateField(_("end date"), null=True, blank=True, default=None)
@@ -231,9 +211,7 @@ def get_absolute_url(self):
         return reverse("accounting:journal_details", kwargs={"j_id": self.id})
 
     def is_owned_by(self, user):
-        """
-        Method to see if that object can be edited by the given user
-        """
+        """Check if that object can be edited by the given user."""
         if user.is_anonymous:
             return False
         if user.is_in_group(pk=settings.SITH_GROUP_ACCOUNTING_ADMIN_ID):
@@ -243,9 +221,7 @@ def is_owned_by(self, user):
         return False
 
     def can_be_edited_by(self, user):
-        """
-        Method to see if that object can be edited by the given user
-        """
+        """Check if that object can be edited by the given user."""
         if user.is_in_group(pk=settings.SITH_GROUP_ACCOUNTING_ADMIN_ID):
             return True
         if self.club_account.can_be_edited_by(user):
@@ -271,9 +247,7 @@ def update_amounts(self):
 
 
 class Operation(models.Model):
-    """
-    An operation is a line in the journal, a debit or a credit
-    """
+    """An operation is a line in the journal, a debit or a credit."""
 
     number = models.IntegerField(_("number"))
     journal = models.ForeignKey(
@@ -422,9 +396,7 @@ def get_target(self):
         return tar
 
     def is_owned_by(self, user):
-        """
-        Method to see if that object can be edited by the given user
-        """
+        """Check if that object can be edited by the given user."""
         if user.is_anonymous:
             return False
         if user.is_in_group(pk=settings.SITH_GROUP_ACCOUNTING_ADMIN_ID):
@@ -437,9 +409,7 @@ def is_owned_by(self, user):
         return False
 
     def can_be_edited_by(self, user):
-        """
-        Method to see if that object can be edited by the given user
-        """
+        """Check if that object can be edited by the given user."""
         if user.is_in_group(pk=settings.SITH_GROUP_ACCOUNTING_ADMIN_ID):
             return True
         if self.journal.closed:
@@ -451,10 +421,9 @@ def can_be_edited_by(self, user):
 
 
 class AccountingType(models.Model):
-    """
-    Class describing the accounting types.
+    """Accounting types.
 
-    Thoses are numbers used in accounting to classify operations
+    Those are numbers used in accounting to classify operations
     """
 
     code = models.CharField(
@@ -488,9 +457,7 @@ def get_absolute_url(self):
         return reverse("accounting:type_list")
 
     def is_owned_by(self, user):
-        """
-        Method to see if that object can be edited by the given user
-        """
+        """Check if that object can be edited by the given user."""
         if user.is_anonymous:
             return False
         if user.is_in_group(pk=settings.SITH_GROUP_ACCOUNTING_ADMIN_ID):
@@ -499,9 +466,7 @@ def is_owned_by(self, user):
 
 
 class SimplifiedAccountingType(models.Model):
-    """
-    Class describing the simplified accounting types.
-    """
+    """Simplified version of `AccountingType`."""
 
     label = models.CharField(_("label"), max_length=128)
     accounting_type = models.ForeignKey(
@@ -533,7 +498,7 @@ def get_movement_type_display(self):
 
 
 class Label(models.Model):
-    """Label allow a club to sort its operations"""
+    """Label allow a club to sort its operations."""
 
     name = models.CharField(_("label"), max_length=64)
     club_account = models.ForeignKey(