documentation: remove CONTRIBUTING and migrate its content in the doc

This commit is contained in:
Antoine Bartuccio 2019-08-12 10:59:21 +02:00
parent 782a763046
commit 0616597bf2
Signed by: klmp200
GPG Key ID: E7245548C53F904B
5 changed files with 167 additions and 107 deletions

View File

@ -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`

View File

@ -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
View 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
View 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"
]
}

View 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