mirror of
https://github.com/ae-utbm/sith.git
synced 2024-11-25 18:44:23 +00:00
documentation: remove CONTRIBUTING and migrate its content in the doc
This commit is contained in:
parent
782a763046
commit
0616597bf2
GPG Key ID:
E7245548C53F904B
106
CONTRIBUTING.md
106
CONTRIBUTING.md
@ -1,106 +0,0 @@
|
|||||||
*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`
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@ -22,12 +22,31 @@ Bienvenue sur la documentation du Sith de l'AE
|
|||||||
|
|
||||||
start/install
|
start/install
|
||||||
|
|
||||||
|
start/translations
|
||||||
|
|
||||||
|
start/devtools
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 3
|
:maxdepth: 3
|
||||||
:caption: Documentation des apps:
|
:caption: Documentation des apps
|
||||||
|
|
||||||
apps/core
|
apps/core
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
:caption: Divers
|
||||||
|
|
||||||
|
misc/helpers
|
||||||
|
|
||||||
|
Documentations complémentaires
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
* `Apprendre Python <https://openclassrooms.com/fr/courses/235344-apprenez-a-programmer-en-python>`__
|
||||||
|
* `Documentation de Django <https://docs.djangoproject.com/fr/1.11/>`__
|
||||||
|
* `Classy Class-Based Views <http://ccbv.co.uk/projects/Django/1.11/>`__
|
||||||
|
* `Cours sur Git <https://openclassrooms.com/fr/courses/2342361-gerez-votre-code-avec-git-et-github>`__
|
||||||
|
* `Livre sur Git <http://www.git-scm.com/book/fr/v2>`__
|
||||||
|
|
||||||
Documents téléchargeables
|
Documents téléchargeables
|
||||||
-------------------------
|
-------------------------
|
||||||
|
|
||||||
|
|||||||
8
doc/misc/helpers.rst
Normal file
8
doc/misc/helpers.rst
Normal file
@ -0,0 +1,8 @@
|
|||||||
|
Commandes utiles
|
||||||
|
================
|
||||||
|
|
||||||
|
* Appliquer le header de licence sur tout le projet
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
for f in $(find . -name "*.py" ! -path "*migration*" ! -path "./env/*" ! -path "./doc/*"); do cat ./doc/header "$f" > /tmp/temp && mv /tmp/temp "$f"; done
|
||||||
60
doc/start/devtools.rst
Normal file
60
doc/start/devtools.rst
Normal file
@ -0,0 +1,60 @@
|
|||||||
|
Configurer son environnement de développement
|
||||||
|
=============================================
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Configurer Black pour son éditeur
|
||||||
|
---------------------------------
|
||||||
|
|
||||||
|
Tous les détails concernant l'installation de black sont ici : https://black.readthedocs.io/en/stable/editor_integration.html
|
||||||
|
|
||||||
|
Néanmoins, nous tenterons de vous faire ici un résumé pour deux éditeurs de textes populaires que sont VsCode et Sublime Text.
|
||||||
|
|
||||||
|
.. sourcecode:: bash
|
||||||
|
|
||||||
|
# Installation de black
|
||||||
|
pip install black
|
||||||
|
|
||||||
|
VsCode
|
||||||
|
~~~~~~
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
Il faut installer black dans son virtualenv pour cet éditeur
|
||||||
|
|
||||||
|
Black est directement pris en charge par l'extension pour le Python de VsCode, il suffit de rentrer la configuration suivante :
|
||||||
|
|
||||||
|
.. sourcecode:: json
|
||||||
|
|
||||||
|
{
|
||||||
|
"python.formatting.provider": "black",
|
||||||
|
"editor.formatOnSave": true
|
||||||
|
}
|
||||||
|
|
||||||
|
Sublime Text
|
||||||
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Il est tout d'abord nécessaire d'installer ce plugin : https://packagecontrol.io/packages/sublack.
|
||||||
|
|
||||||
|
Il suffit ensuite d'ajouter dans les settings du projet (ou directement dans les settings globales) :
|
||||||
|
|
||||||
|
.. sourcecode:: 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 comme ceci :
|
||||||
|
|
||||||
|
.. sourcecode:: json
|
||||||
|
|
||||||
|
{
|
||||||
|
"pep8_ignore": [
|
||||||
|
"E203",
|
||||||
|
"E266",
|
||||||
|
"E501",
|
||||||
|
"W503"
|
||||||
|
]
|
||||||
|
}
|
||||||
79
doc/start/translations.rst
Normal file
79
doc/start/translations.rst
Normal file
@ -0,0 +1,79 @@
|
|||||||
|
Ajouter une traduction
|
||||||
|
======================
|
||||||
|
|
||||||
|
Le code du site est entièrement écrit en anglais, le texte affiché aux utilisateurs l'est également. La traduction en français se fait ultérieurement avec un fichier de traduction. Voici un petit guide rapide pour apprendre à s'en servir.
|
||||||
|
|
||||||
|
Dans le code du logiciel
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
Imaginons que nous souhaitons afficher "Hello" et le traduire en français. Voici comment signaler que ce mot doit être traduit.
|
||||||
|
|
||||||
|
Si le mot est dans le code Python :
|
||||||
|
|
||||||
|
.. sourcecode:: python
|
||||||
|
|
||||||
|
from django.utils.translation import ugettext_lazy as _
|
||||||
|
|
||||||
|
# ...
|
||||||
|
|
||||||
|
help_text=_("Hello")
|
||||||
|
|
||||||
|
# ...
|
||||||
|
|
||||||
|
Si le mot apparaît dans le template Jinja :
|
||||||
|
|
||||||
|
.. sourcecode:: html+jinja
|
||||||
|
|
||||||
|
{# ... #}
|
||||||
|
|
||||||
|
{% trans %}Hello{% endtrans %}
|
||||||
|
|
||||||
|
{# ... #}
|
||||||
|
|
||||||
|
Générer le fichier django.po
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
La traduction se fait en trois étapes. Il faut d'abord générer un fichier de traductions, l'éditer et enfin le compiler au format binaire pour qu'il soit lu par le serveur.
|
||||||
|
|
||||||
|
.. sourcecode:: bash
|
||||||
|
|
||||||
|
./manage.py makemessages --ignore "env/*" -e py,jinja
|
||||||
|
|
||||||
|
Éditer le fichier django.po
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
.. role:: python(code)
|
||||||
|
:language: python
|
||||||
|
|
||||||
|
.. sourcecode:: python
|
||||||
|
|
||||||
|
# locale/fr/LC_MESSAGES/django.po
|
||||||
|
|
||||||
|
# ...
|
||||||
|
msgid "Hello"
|
||||||
|
msgstr "" # Ligne à modifier
|
||||||
|
|
||||||
|
# ...
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Si les commentaires suivants apparaissent, pensez à les supprimer. Ils peuvent gêner votre traduction.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
#, fuzzy
|
||||||
|
#| msgid "Bonjour"
|
||||||
|
|
||||||
|
|
||||||
|
Générer le fichier django.mo
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
Il s'agit de la dernière étape. Un fichier binaire est généré à partir du fichier django.mo.
|
||||||
|
|
||||||
|
.. sourcecode:: bash
|
||||||
|
|
||||||
|
./manage.py compilemessages
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Pensez à redémarrer le serveur si les traductions ne s'affichent pas
|
||||||
Loading…
Reference in New Issue
Block a user