diff --git a/Documentation/README.md b/Documentation/README.md index 7752eb4e068a58bf16deff28600ad9e56c835a4f..7ae1d449a647daa477a491ddc05925f27dec17d3 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -10,12 +10,13 @@ Ce repo contient également un fichier de configuration [MkDocs](https://www.mkd Cloner le projet : ``` -git clone ssh://git@ssh.hesge.ch:10572/in-code-we-trust/documentation.git +git clone https://gitedu.hesge.ch/architecture-web/architecture-et-application-web-2022-2023-tp-rajohnson ``` Créer et activer l'environnement virtuel : ``` +cd Documentation python -m venv .venv source .venv/bin/activate ``` @@ -67,150 +68,4 @@ Si nécessaire, il est possible de changer le port utilisé à l'aide du paramè mkdocs serve -a "127.0.0.1:9876" ``` -L'exemple ci-dessus rend le site accessible en `http://127.0.0.1:9876`. - -### Générer le site - -Il est possible de générer le site avec la commande suivante : - -``` -mkdocs build -``` - -Cette commande produit un dossier `site` contenant la documentation sous forme d'un site web. Il est ensuite possible -d'héberger ce dossier afin de la rendre accessible à tout le monde. - - -## Écrire la documentation - -### Enrichir la documentation - -[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/) met à disposition de nombreuses extensions -offrant de nombreuses fonctionnalités pour enrichir la documentation. N'hésitez pas à y jetter un oeil afin de voir ce -qui est disponible. - - -### Ajouter une page - -Si vous souhaitez ajouter une page, pour par exemple expliquer une nouvelle fonctionnalité, il suffit simplement de -créer un fichier `<my_file>.md` dans le dossier correspondant (ex: `backend/<my_file>.md` pour une fonctionnalité du -serveur). - -Il faut ensuite ajouter le fichier dans la navigation définie dans la configuration de -[mkdocs](https://gitedu.hesge.ch/in-code-we-trust/documentation/-/blob/main/mkdocs.yml). - - -L'ajout se fait de la manière suivante : - -```yml -nav: - # ... - - Backend: - - Introduction: - - backend/index.md - - Gestion des données: - - Modèles: 'backend/models.md' - - Migrations: 'backend/migrations.md' - - Sérialisation: 'backend/serialization.md' - - <Nom de section>: 'backend/<my_file>.md' # Le chemin vers le nouveau fichier - - Fonctionnement: - - REST framework: 'backend/rest_framework.md' - # ... -``` - -*Remplacer respectivement `<Nom de section>` et `<my_file>` avec un nom de section et le nom du fichier de votre page.* - - -## Déploiement de la documentation avec Docker - -Actuellement, le déploiement de la documentation sur le serveur distant s'effectue à l'aide de docker compose. - - -### Prérequis - -Il est impératif que ce serveur puisse accéder au projet git en SSH. - -*Les clefs SSH expireront le 8 juillet 2023.* - - -Le serveur doit pouvoir créer une image docker et lancer un container à partir de cette image. - - -### Marche à suivre - -Se connecter au serveur [wetty](https://silentpc.ciuj-kune.org/wetty). - -- Pour le premier déploiement, exécuter les commandes suivantes : - -``` -git clone ssh://git@ssh.hesge.ch:10572/in-code-we-trust/documentation.git -cd documentation -python -m pip install -r requirements.txt -mkdocs build -``` - -Note: Le fichier `check-container.bash` permet de vérifier qu'un conteneur de notre image est existant. Dans le cas -contraire il va exécuter le fichier `setup-prod.bash` avec le paramètre `-f`, forçant le déploiement de notre -*container*. - -Se rendre ensuite sur la page des Stacks du [portainer](https://silentpc.ciuj-kune.org/portainer/#!/2/docker/stacks) - -1. Cliquer sur le bouton `+ Add stack` -2. Donner un nom à la stack : `icwt` -3. Sélectionner l'option `Upload` -4. Cliquer sur le bouton `Select file` et sélectionner le fichier `docker-compose.yml` -5. En bas de page, cliquer sur le bouton `Deploy the stack` - -La documentation est ensuite accessible [ici](http://silentpc.ciuj-kune.org:2100/). - -### Bind mount - -Le dossier `site/`, généré par la commande `mkdocs build` est monté sur le conteneur docker à l'aide du fichier -`docker-compose.yml`. - -En cas de modification de la documentation il suffit d'effectuer la commande `mkdocs build` pour que le containeur soit -automatiquement mis à jour. - - -### Automatisation - -Les scripts `setup-prod.bash` et `check-container.bash` permettent de mettre à jour automatiquement la documentation. - -Pour cela, il faut impérativement les rendre exécutables : - -``` -chmod +x setup-prod.bash -chmod +x check-container.bash -``` - -Il est possible d'exécuter régulièrement le fichier `setup-prod.bash` à l'aide de crontab : - -``` -crontab -e -0 3 * * * ~/documentation/setup-prod.bash -``` - -*Le fichier sera exécuté automatiquement tous les jours à 3H du matin.* - - -Actuellement, le crontab sur le serveur est définit ainsi : - -``` -PATH=$PATH:/home/incode/.local/bin:/usr/bin -0 * * * * ~/documentation/setup-prod.bash >> ~/crontab_logs/doc_setup.log 2>&1 -7 * * * * ~/documentation/check-container.bash >> ~/crontab_logs/doc_check.log 2>&1 -15 * * * * ~/documentation/setup-prod.bash >> ~/crontab_logs/doc_setup.log 2>&1 -22 * * * * ~/documentation/check-container.bash >> ~/crontab_logs/doc_check.log 2>&1 -30 * * * * ~/documentation/setup-prod.bash >> ~/crontab_logs/doc_setup.log 2>&1 -37 * * * * ~/documentation/check-container.bash >> ~/crontab_logs/doc_check.log 2>&1 -45 * * * * ~/documentation/setup-prod.bash >> ~/crontab_logs/doc_setup.log 2>&1 -52 * * * * ~/documentation/check-container.bash >> ~/crontab_logs/doc_check.log 2>&1 -``` - -- La ligne `PATH=$PATH:/home/incode/.local/bin` nous assure que la commande mkdocs soit trouvée afin d'être correctement -exécutée. - -- Les `>> ~/crontab_logs/<name>.log` permettent de rediriger la sortie des commandes dans un fichier. - -- Les `2>&1` vont rediriger la sortie d'erreur (`stderr`) dans la sortie standard (`stdout`), ce qui permet de garder une -trace des erreurs lors de l'exécution des commandes. +L'exemple ci-dessus rend le site accessible en `http://127.0.0.1:9876`. \ No newline at end of file