mirror of
https://github.com/ae-utbm/sith.git
synced 2025-07-11 12:29:24 +00:00
Rewrite documentation with MkDocs
This commit is contained in:
150
docs/tutorial/devtools.md
Normal file
150
docs/tutorial/devtools.md
Normal file
@ -0,0 +1,150 @@
|
||||
Le projet n'est en aucun cas lié à un
|
||||
quelconque environnement de développement.
|
||||
Il est possible pour chacun de travailler
|
||||
avec les outils dont il a envie et d'utiliser
|
||||
l'éditeur de code avec lequel il est le plus à l'aise.
|
||||
|
||||
Pour donner une idée, Skia a écrit une énorme
|
||||
partie de projet avec l'éditeur *Vim* sur du GNU/Linux
|
||||
alors que Sli a utilisé *Sublime Text* sur MacOS
|
||||
et que Maréchal travaille avec PyCharm
|
||||
sur ~~Windows muni de WSL~~ Arch Linux btw.
|
||||
|
||||
## Configurer les pre-commit hooks
|
||||
|
||||
La procédure habituelle pour contribuer au
|
||||
projet consiste à commit des modifications,
|
||||
puis à les push sur le dépôt distant et
|
||||
à ouvrir une pull request.
|
||||
Cette PR va faire tourner les outils de vérification
|
||||
de la qualité de code.
|
||||
Si la vérification échoue, la PR est bloquée,
|
||||
et il faut réparer le problème
|
||||
(ce qui implique de push un micro-commit
|
||||
ou de push force sur la branche).
|
||||
|
||||
Dans l'idéal, on aimerait donc qu'il soit
|
||||
impossible d'oublier de faire tourner ces vérifications.
|
||||
Pour ça, il existe un mécanisme : les pre-commits hooks.
|
||||
Ce sont des actions qui tournent automatiquement
|
||||
lorsque vous effectuez un `git commit`.
|
||||
Ces dernières vont analyser et éventuellement modifier le code,
|
||||
avant que Git n'ajoute effectivement le commit sur l'arbre git.
|
||||
Voyez ça comme une micro-CI qui tourne en local.
|
||||
|
||||
Les git hooks sont une fonctionnalité par défaut de Git.
|
||||
Cependant, leur configuration peut-être un peu
|
||||
embêtante si vous le faites manuellement.
|
||||
Pour gérer ça plus simplement,
|
||||
nous utilisons le logiciel python [pre-commit](https://pre-commit.com/)
|
||||
qui permet de contrôler leur installation via un seul fichier de configuration,
|
||||
placé à la racine du projet
|
||||
(plus précisément, il s'agit du fichier `.pre-commit-config.yaml`).
|
||||
|
||||
!!!note
|
||||
|
||||
Les pre-commits sont également utilisés dans la CI.
|
||||
Si ces derniers fonctionnent localement, vous avez la garantie que la pipeline ne sera pas fachée. ;)
|
||||
|
||||
C'est une fonctionnalité de git lui-même,
|
||||
mais c'est assez embêtant à gérer manuellement.
|
||||
Pour gérer ça plus simplement,
|
||||
nous utilisons le logiciel python [pre-commit](https://pre-commit.com/)
|
||||
qui permet de contrôller leur installation via un fichier yaml.
|
||||
|
||||
Le logiciel est installé par défaut par poetry.
|
||||
Il suffit ensuite de lancer :
|
||||
|
||||
```bash
|
||||
pre-commit install
|
||||
```
|
||||
Une fois que vous avez fait cette commande, pre-commit
|
||||
tournera automatiquement chaque fois que vous ferez
|
||||
un nouveau commit.
|
||||
|
||||
Il est également possible d'appeler soi-même les pre-commits :
|
||||
|
||||
```bash
|
||||
pre-commit run --all-files
|
||||
```
|
||||
|
||||
|
||||
## Configurer Ruff pour son éditeur
|
||||
|
||||
!!!note
|
||||
|
||||
Ruff est inclus dans les dépendances du projet.
|
||||
Si vous avez réussi à terminer l'installation, vous n'avez donc pas de configuration
|
||||
supplémentaire à effectuer.
|
||||
|
||||
Pour utiliser Ruff, placez-vous à la racine du projet et lancez la commande suivante :
|
||||
|
||||
```bash
|
||||
ruff format # pour formatter le code
|
||||
ruff check # pour linter le code
|
||||
```
|
||||
|
||||
Ruff va alors faire son travail sur l'ensemble du projet puis vous dire
|
||||
si des documents ont été reformatés (si vous avez fait `ruff format`)
|
||||
ou bien s'il y a des erreurs à réparer (si vous avez faire `ruff check`).
|
||||
|
||||
Appeler Ruff en ligne de commandes avant de pousser votre code sur Github
|
||||
est une technique qui marche très bien.
|
||||
Cependant, vous risquez de souvent l'oublier.
|
||||
Or, lorsque le code ne respecte pas les standards de qualité,
|
||||
la pipeline bloque les PR sur les branches protégées.
|
||||
|
||||
Pour éviter de vous faire régulièrement avoir, vous pouvez configurer
|
||||
votre éditeur pour que Ruff fasse son travail automatiquement à chaque édition d'un fichier.
|
||||
Nous tenterons de vous faire ici un résumé pour deux éditeurs de textes populaires
|
||||
que sont VsCode et Sublime Text.
|
||||
|
||||
### VsCode
|
||||
|
||||
Installez l'extension Ruff pour VsCode.
|
||||
Ensuite, ajoutez ceci dans votre configuration :
|
||||
|
||||
```json
|
||||
{
|
||||
"[python]": {
|
||||
"editor.formatOnSave": true,
|
||||
"editor.defaultFormatter": "charliermarsh.ruff"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Sublime Text
|
||||
|
||||
Vous devez installer ce plugin : https://packagecontrol.io/packages/LSP-ruff.
|
||||
Suivez ensuite les instructions données dans la description du plugin.
|
||||
|
||||
Dans la configuration de votre projet, ajoutez ceci:
|
||||
|
||||
```json
|
||||
{
|
||||
"settings": {
|
||||
"lsp_format_on_save": true,
|
||||
"LSP": {
|
||||
"LSP-ruff": {
|
||||
"enabled": 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 ruff comme ceci :
|
||||
|
||||
```json
|
||||
{
|
||||
"pep8_ignore": [
|
||||
"E203",
|
||||
"E266",
|
||||
"E501",
|
||||
"W503"
|
||||
]
|
||||
}
|
||||
```
|
Reference in New Issue
Block a user