Compilation de la documentation

Le système de build utilise Npm. Il faut donc commencer par installer l’environnement pour pouvoir obtenir tous les paquets nécéssaires à la compilation.

---

Sous linux (exemple de Debian)

Voici les opérations à exécuter pour compiler le projet sous linux.

• Ouvrir une console et tapper la commande suivante:

sudo apt-get install npm

• Se rendre ensuite à la base du projet:

cd <path/to/project>

• et executer la commande suivante:

npm install

Une fois faite, le projet contiendra tout ce qu’il faut pour pouvoir construire le site. Lorsque le système de documentation rajoute des dépendances comme par exemple des nouveaux plugins, il faudra de nouveau exécuter la commande:

npm install

Lorsqu les paquets existants doivent être mis à jour, il suffit d’exécuter la commande suivante:

npm update

---

Sous Windows

Voici les opérations à exécuter pour compiler le projet sous Windows.

• Télécharger la dernière version de npm et l’installer. Attention, à la fin de l’installation il est possible que le système demande de mettre npm dans le Path. Dans ce cas, répondre oui.
• Télécharger git. La plupart des sources liées aux paquets npm se trouvent sur git. Il est donc nécéssaire de l’installer. comme pour npm, il faut mettre git dans le Path lorsque l’installeur le demande.
• Le projet utilise node-gyp. La machine doit avoir Python 3.xx installé et le Visual Studio Build Tools.

Une fois ces programmes installés, les paquets nécéssaire à la documentation peuvent être mis en place.

• Ouvrir Powershell en mode administrateur en tappant powershell dans le menu démarrer puis en faisant Click droit > Ouvrir en tant qu'admin.
• Aller dans le projet de documentation avec la commande suivante :

cd <path/to/project>

• et executer la commande suivante

npm install

Une fois faite, le projet contiendra tout ce qu’il faut pour pouvoir construire le site. Lorsque le système de documentation rajoute des dépendances comme par exemple des nouveaux plugins, il faudra de nouveau executer la commande

npm install

Pour simplement mettre à jour les paquets existant, il suffit d’executer la commande

npm update

---

Compiler la documentation

Pour compiler le programme, il suffit simplement de faire dans un terminal pointé vers le dossier de base du projet (la où est situé index.js)

node index.js

Et voila! Toutes les pages html, les styles et les resources sont maintenant disponibles dans le dossier build du projet. Dès que la documentation doit être reconstruite, il suffit de taper cette commande.

---

Serveur local

Pour avoir un serveur local qui va permettre de faire l’aperçu des pages telles qu’elles ont été compilées, il suffit d’installer une fois sur la machine le packaque http-server sur le système. Même en supprimant le dossier du projet, ce programme sera toujours disponible car il est installé en global avec npm.

• Ouvrir un terminal et tapper la commande suivante

npm install -g http-server

Cette commande va rendre disponible en console un petit serveur qui pourra être lancé depuis absolument n’importe quel dossier.

Pour démarrer un serveur en local qui va montrer exactement le résultat du site tel qu’il sera déployé en ligne,

• En console se déplacer jusqu’au dossier build du projet. Il est important de se mettre dans le dossier build pour que les images fonctionnent en local

cd <path/to/project>/build

• Executez la commande pour démarrer le serveur

http-server

Si tout se passe bien, les lignes suivantes vont s’afficher :

Starting up http-server, serving ./
Available on:
  http://127.0.0.1:8081
  http://192.168.0.61:8081
  http://123.43.21.1:8081
  http://123.43.21.1:8081
Hit CTRL-C to stop the server

Ce qui veut dire que le serveur est accessible depuis n’importe quel browser internet aux adresses fournies. Pour couper le serveur, faites Ctrl + C

---

Terminal intégré dans Visual studio code

Afin de ne pas s’embétter avec les terminaux externe, il est possible d’avoir directement des terminaux intégrés sur Visual code studio en faisant View > Integrated Terminal.

L’intérêt des terminaux intégrés est qu’ils se mettent directement sur le bon repertoire, et sont dans la même fenêtre donc faciles d’accès.

La fenêtre de terminaux permet d’en ouvrir plusieurs, d’en enlever, etc…

Attention! Sous windows par défaut le terminal n’est pas powershell mais Cmd qui ne permet pas de travailler et de tapper les commandes. Pour forcer powershell, il faut faire les manipulations suivantes :

• Editer les users settings dans File > Preferences > Settings en rajoutant la ligne suivante

{
    "terminal.integrated.shell.windows": "C:\\Windows\\sysnative\\WindowsPowerShell\\v1.0\\powershell.exe"
}

Ensuite pour travailler, en temps normal, la configuration optimale utilisée est :

• Un terminal pour executer node index.js
• Un terminal qui tourne pour le http-serve