Sith/docs/tutorial/structure.md

211 lines
6.8 KiB
Markdown
Raw Normal View History

2024-07-16 16:39:54 +00:00
## La structure d'un projet Django
Un projet Django est structuré en applications.
Une application est un package Python
contenant un ensemble de vues, de modèles, de templates, etc.
Sémantiquement, une application représente
un ensemble de fonctionnalités cohérentes.
Par exemple, dans notre cas, nous avons une application
chargée de la gestion des comptoirs, une autre de la gestion
des clubs, une autre de la gestion du SAS, etc.
On trouve généralement dans un projet Django
une application principale qui contient les
fichiers de configuration du projet,
les urls et éventuellement des commandes d'administration.
## Arborescence du projet
Le code source du projet est organisé comme suit :
<div class="annotate">
```
sith3/
├── .github/
│ ├── actions/ (1)
│ └── workflows/ (2)
├── accounting/ (3)
│ └── ...
2024-07-23 21:25:17 +00:00
├── club/ (4)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── com/ (5)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── core/ (6)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── counter/ (7)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── docs/ (8)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── eboutic/ (9)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── election/ (10)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── forum/ (11)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── galaxy/ (12)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── launderette/ (13)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── locale/ (14)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── matmat/ (15)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── pedagogy/ (16)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── rootplace/ (17)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── sas/ (18)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── sith/ (19)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── stock/ (20)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── subscription/ (21)
2024-07-16 16:39:54 +00:00
│ └── ...
2024-07-23 21:25:17 +00:00
├── trombi/ (22)
2024-07-16 16:39:54 +00:00
│ └── ...
├── antispam/ (23)
│ └── ...
2024-07-16 16:39:54 +00:00
├── .coveragerc (24)
├── .envrc (25)
2024-07-16 16:39:54 +00:00
├── .gitattributes
├── .gitignore
├── .mailmap
├── .env.exemple
├── manage.py (26)
├── mkdocs.yml (27)
2024-07-16 16:39:54 +00:00
├── poetry.lock
├── pyproject.toml (28)
2024-07-16 16:39:54 +00:00
└── README.md
```
</div>
1. Dossier contenant certaines actions réutilisables
dans des workflows Github. Par exemple, l'action
`setup-project` installe poetry puis appelle
la commande `poetry install`.
2. Dossier contenant les fichiers de configuration
des workflows Github.
Par exemple, le workflow `docs.yml` compile
et publie la documentation à chaque push sur la branche `master`.
3. Application de gestion de la comptabilité.
2024-07-23 21:25:17 +00:00
4. Application de gestion des clubs et de leurs membres.
5. Application contenant les fonctionnalités
2024-07-16 16:39:54 +00:00
destinées aux responsables communication de l'AE.
2024-07-23 21:25:17 +00:00
6. Application contenant la modélisation centrale du site.
2024-07-16 16:39:54 +00:00
On en reparle plus loin sur cette page.
2024-07-23 21:25:17 +00:00
7. Application de gestion des comptoirs, des permanences
2024-07-16 16:39:54 +00:00
sur ces comptoirs et des transactions qui y sont effectuées.
2024-07-23 21:25:17 +00:00
8. Dossier contenant la documentation.
9. Application de gestion de la boutique en ligne.
10. Application de gestion des élections.
11. Application de gestion du forum
12. Application de gestion de la galaxie ; la galaxie
2024-07-16 16:39:54 +00:00
est un graphe des niveaux de proximité entre les différents
étudiants.
2024-07-23 21:25:17 +00:00
13. Gestion des machines à laver de l'AE
14. Dossier contenant les fichiers de traduction.
15. Fonctionnalités de recherche d'utilisateurs.
16. Le guide des UEs du site, sur lequel les utilisateurs
2024-07-16 16:39:54 +00:00
peuvent également laisser leurs avis.
2024-07-23 21:25:17 +00:00
17. Fonctionnalités utiles aux utilisateurs root.
18. Le SAS, où l'on trouve toutes les photos de l'AE.
19. Application principale du projet, contenant sa configuration.
20. Gestion des stocks des comptoirs.
21. Gestion des cotisations des utilisateurs du site.
22. Fonctionalitées pour gérer le spam.
23. Gestion des trombinoscopes.
24. Fichier de configuration de coverage.
25. Fichier de configuration de direnv.
26. Fichier généré automatiquement par Django. C'est lui
2024-07-16 16:39:54 +00:00
qui permet d'appeler des commandes de gestion du projet
avec la syntaxe `python ./manage.py <nom de la commande>`
27. Le fichier de configuration de la documentation,
2024-07-16 16:39:54 +00:00
avec ses plugins et sa table des matières.
28. Le fichier où sont déclarés les dépendances et la configuration
2024-07-16 16:39:54 +00:00
de certaines d'entre elles.
## L'application principale
L'application principale du projet est le package `sith`.
Ce package contient les fichiers de configuration du projet,
la racine des urls.
Il est organisé comme suit :
<div class="annotate">
```
sith/
├── settings.py (1)
├── settings_custom.py (2)
├── toolbar_debug.py (3)
├── urls.py (4)
└── wsgi.py (5)
```
</div>
1. Fichier de configuration du projet.
Ce fichier contient les paramètres de configuration du projet.
Par exemple, il contient la liste des applications
installées dans le projet.
2. Configuration maison pour votre environnement.
Toute variable que vous définissez dans ce fichier sera prioritaire
sur la configuration donnée dans `settings.py`.
3. Configuration de la barre de debug.
C'est inutilisé en prod, mais c'est très pratique en développement.
4. Fichier de configuration des urls du projet.
5. Fichier de configuration pour le serveur WSGI.
WSGI est un protocole de communication entre le serveur
et les applications.
Ce fichier ne vous servira sans doute pas sur un environnement
de développement, mais il est nécessaire en production.
## Les applications
Les applications sont des packages Python.
Dans ce projet, les applications sont généralement organisées
comme suit :
<div class="annotate">
```
.
├── migrations/ (1)
│ └── ...
├── templates/ (2)
│ └── ...
2024-07-23 21:25:17 +00:00
├── api.py (3)
├── admin.py (4)
├── models.py (5)
├── tests.py (6)
├── schemas.py (7)
├── urls.py (8)
└── views.py (9)
2024-07-16 16:39:54 +00:00
```
</div>
1. Dossier contenant les migrations de la base de données.
Les migrations sont des fichiers Python qui permettent
de mettre à jour la base de données.
cf. [Gestion des migrations](../howto/migrations.md)
2. Dossier contenant les templates jinja utilisés par cette application.
2024-07-23 21:25:17 +00:00
3. Fichier contenant les routes d'API liées à cette application
4. Fichier de configuration de l'interface d'administration.
2024-07-16 16:39:54 +00:00
Ce fichier permet de déclarer les modèles de l'application
dans l'interface d'administration.
2024-07-23 21:25:17 +00:00
5. Fichier contenant les modèles de l'application.
2024-07-16 16:39:54 +00:00
Les modèles sont des classes Python qui représentent
les tables de la base de données.
2024-07-23 21:25:17 +00:00
6. Fichier contenant les tests de l'application.
7. Schémas de validation de données utilisés principalement dans l'API.
8. Configuration des urls de l'application.
9. Fichier contenant les vues de l'application.
2024-07-16 16:39:54 +00:00
Dans les plus grosses applications,
ce fichier peut être remplacé par un package
`views` dans lequel les vues sont réparties entre
plusieurs fichiers.
L'organisation peut éventuellement être un peu différente
pour certaines applications, mais le principe
général est le même.