Tutoriel – Éditer un fichier avec GitLab#

Information

Auteur : Philippe Dessus, Inspé & LaRAC, Univ. Grenoble Alpes.
Date de création : Février 2019.
Résumé : Ce document décrit comment éditer un document de texte avec GitLab, avec les différentes interfaces (édition de fichiers uniques ou multiples).

Introduction#

GitLab, associé à ReadTheDocs, permet de créer une chaîne éditoriale de documents collaboratifs. GitLab stocke, dans des dépôts, les fichiers, qui sont éditables collaborativement, et chaque commit déclenche ReadTheDocs qui produit les fichiers lisibles (PDF, epub, HTML).

Comme ce sont deux logiciels libres et gratuits, il est possible de les installer sur des serveurs pour se créer sa propre documentation (attention, c’est une installation complexe et il vaut mieux recourir à des informaticiens).

Flux de travail général#

Commençons par une brève description du flux de travail d’une équipe d’enseignants travaillant à des cours avec GitLab/ReadTheDocs (ce qui suit est inspiré de Massey, H. (2013), GitHub, academia, and collaborative writing).

Créer un répertoire dans lequel va figurer une hiérarchie de documents de cours ;
Cloner (ou télécharger) un ensemble de documents ;
Réaliser les modifications nécessaires (commit) ;
Synchroniser ces modifications avec celles du serveur (notamment, si elles sont réalisées en local) (push)
Si l’on n’a pas les droits pour modifier directement les fichiers initiaux, créer une branche et demander à l’administrateur du site de considérer les ajouts (pull request) ; cette requête apparaît aussi comme un “problème” (issue) et peut donc être référée par un numéro, pour des discussions futures.

Présentation générale de l’interface GitLab#

Commençons par la présentation de l’interface de GitLab, le serveur de production collaborative de fichiers. Il est conseillé d’avoir un minimum de connaissances à propos de Sphinx avant de se lancer dans l’édition de pages sous GitLab, et donc consulter le Document syntaxe_rest et syntaxe_sphinx. Pour éditer une page, il faut avoir obtenu l’accès à un dépôt par son administrateur et entrer l’URL qu’il vous a donné. Si vous avez une vue un peu différente de celle-ci, cliquez sur Projet>Détails (bandeau de gauche, voir numéro 6 de la Figure 1 ci-dessous).

On arrive sur une page comme celle de la Figure 1 ci-dessous. Les élements importants sont expliqués ci-dessous (figurant sur l’image dans des nombres cerclés).

L’URL du dépôt (l’endroit où sont stockés les documents).
La branche (master) et le projet (sandbox) du dépôt.
Cliquer sur ce signe amène à pouvoir créer de nouveaux éléments (pages, fichiers, branches, etc.).
Signale la dernière activité sur le dépôt.
Liste tous les fichiers du dépôt avec leur dernier commit (la dernière fois où ils ont été modifiés). Cliquer sur un nom amène l’affichage de la page de la Figure 2.

Figure 1. Copie d’écran de la page d’accueil d’un dépôt GitLab.

Voici maintenantles principaux éléments de la Figure 2 ci-dessous (repérés sur la Fig. 2 par un numéro correspondant à ceux ci-dessous) :

Le titre du fichier ;
Ce bouton affiche le document-source (en reStructuredText) ;
Ce bouton affiche le document rendu en HTML (rendu approximatif, la syntaxe Sphinx n’est pas rendue) ;
Ce bouton permet de copier l’ensemble du document (source) ;
Ce bouton affiche le document-source dans une nouvelle page ;
Ce bouton affiche le document-source dans une nouvelle page pour qu’on puisse l’éditer (un fichier à la fois, à préférer pour des éditions ponctuelles) ;
Ce bouton affiche le document-source dans un éditeur web permettant l’édition multiples de fichiers (à préférer pour des éditions multiples de documents dans un même dépôt).
Ce bouton affiche une fenêtre demandant un nouveau fichier, qui remplacera le fichier en cours ;
Ce bouton supprime purement et simplement le fichier en cours.

Figure 2. Copie d’écran de la page d’un fichier.

Vous connaissez maintenant l’essentiel de l’interface de GitLab pour créer ou modifier des fichiers. Voyons maintenant comment se passer l’édition d’un fichier.

Éditer un document#

Il y a deux manières d’éditer un fichier texte via l’interface de GitLab, l’une, fichier par fichier (bouton 6 Fig. 2), l’autre, plusieurs fichiers à la fois (bouton 7 Fig. 2). Décrivons ces deux interfaces et leurs possibilités.

Attention : Modification et type de fichier

Tous les fichiers d’un dépôt n’ont pas le même statut.

Il est formellement interdit de modifier le fichier requirements.txt.
Il est déconseillé de modifier le fichier conf.py, à moins de savoir exactement quel paramètre changer et de faire attention à ne rien modifier d’autre, car ce fichier est utilisé pour produire le document final.
Notez aussi que tout fichier reStructuredText doit avoir le suffixe .rst.

L’interface d’édition simple#

Figure 3. Copie d’écran du mode édition simple d’un fichier.

Vous vous trouvez ici en terrain connu : une interface très simple d’édition de texte, avec les fonctions suivantes (repérées sur la Fig. 3 par un numéro correspondant à ceux ci-dessous) :

Le nom du fichier, directement modifiable.
Le bouton “Soft wrap“ permet de reformater le texte pour qu’il s’affiche entièrement dans la fenêtre, sans demander de défilement horizontal s’il la dépasse. Il est conseillé de cliquer dessus avant toute édition.
Ce bouton permet de rechercher du texte dans le champ.
Le bouton “Preview“
La zone d’édition du texte.
Une fois le texte édité, cliquer sur “Commit changes“ pour l’envoyer au serveur ReadTheDocs, après avoir renseigné éventuellement le champ 7. et le nom de branche 8. Attention, cela demande environ 2-3 minutes pour que les changements soient pris en compte. L’administrateur doit vous avoir fourni l’URL de la page ReadTheDocs correspondante.
Ce champ permet de renseigner le type de modifications réalisées dans ce commit.
Ce champ permet de spécifier la branche utilisée. Dans la grande majorité des cas, il faut laisser “master”, mais une organisation spécifique du dépôt peut imposer une autre branche.

L’interface d’édition multiple#

Cette interface est un peu plus complexe et permet l’édition de plusieurs fichiers du même dépôt avec le même commit, ce qui fait gagner du temps (humain et machine). Les fonctions suivantes sont possibles (repérées sur la Fig. 4 par un numéro correspondant à ceux ci-dessous)

Figure 4. Copie d’écran du mode édition multiple d’un fichier.

Cliquer sur ce signe amène à pouvoir créer de nouveaux éléments (pages, fichiers, branches, etc.).
Cliquer dans un fichier texte de cette zone amène son édition dans un nouvel onglet (les images ou PDF du dépôt ne sont pas éditables dans cette interface).
Ce bouton est actionné par défaut : il signale le mode édition de texte ;
Ce bouton permet la mise en évidence des changements faits dans le fichier depuis le dernier commit ;
Ce bouton permet de gérer plus précisément le commit (commentaires, branche) ;
Ce bouton permet de revenir à l’interface “détails“ du dépôt.
Ce bouton permet de lancer le commit, à cliquer une fois que toutes les modifications voulues ont été faites sur tous les fichiers. Cliquer dessus amènera le mode décrit en 5. ci-dessus. En général, cliquer sur le bouton vert Stage & Commit suffira, après avoir éventuellement renseigné le message du commit, indiquant les principales modifications.

Éditer un document en local#

Il est également possible d’éditer vos documents en local, sur un logiciel traitement de textes standard, en passant par un client Git (p. ex., GitHub desktop <https://desktop.github.com>) qui va scruter les modifications depuis le dernier commit et télécharger/téléverser les fichiers changés en local ou en ligne automatiquement.

Liens entre Gitlab et Docker#

Il est possible de configurer (voir Doc. Installer Sphinx et configurer un projet), d’un côté, un conteneur Docker pour réaliser toutes les modifications souhaitées sur les fichiers, en local et d’en vérifier le rendu en HTML ou LaTeX, sans solliciter le serveur GitLab. Une fois toutes les modifications réalisées, il est aisé d’utiliser un client GitLab pour reporter toutes les modifications sur le serveur pour une diffusion publique.

Liste de tâches pour un transfert de repo Sphinx sous GitLab#

S’assurer que le fichier .bib soit conforme. Une ouverture du fichier avec un outil de gestion bibliographique bibtex (comme BibDesk), et un export en BibTex fera pointer et corriger les erreurs les plus indétectables.
Avoir un répertoire local dans lequel tous les fichiers .md, le fichier de références .bib, et les fichiers utiles pour le GitLab (.gitignore, requirements.txt, .gitlab-ci.yml) soient présents. Il est préférable de supprimer, si vous les avez compilés auparavant, les éventuels répertoires public, src, _static, latex ou epub puisqu’ils seront compilés dans le gitlab.
Créer un nouveau repo GitLab create a blank project, puis indiquez le groupe approprié (dans notre cas, inspe-sciedu). Déclarez-le Public et ne demandez pas la création d’un fichier READ.ME.
Allez dans le répertoire local à téléverser dans le GitLab
Supprimez les éventuelles traces d’un précédent dépôt Git (ce qui arrive en cas de recopie de dossier), par la commande terminal rm -fr .git.
Tapez ensuite la liste de commandes suivantes (attention, l’URL est à changer en fonction du repo) :

git init git remote add origin https://gricad-gitlab.univ-grenoble-alpes.fr/inspe-sciedu/qcm.git git add . git commit -m “Initial commit” git push origin HEAD:master

Si vous utilisez également un client GitHub/GitLab pour pousser vos modifications sur le serveur, il est conseillé de créer immédiatement un repo sur ce client : Add local repository, pointez sur le répertoire local nouvellement créé, faire Add repository, puis publish branch.
Il est souvent difficile de créer des fichier “invisibles” (commençant par un .) de votre ordinateur. Dans ce cas, créez les fichiers gitignore.txt et gitlab-ci.yml en local, puis modifiez-les sur le serveur en ajoutant le point préfixe en les éditant et faisant ensuite un commit. Ainsi ils pourront être pris en compte par le serveur.
N’oubliez pas de sélectionner un “runner partagé“ dans les Paramètres>Intégration et livraison continue du nouveau repo.
Tout est maintenant en place, vous pouvez lancer une compilation en faisant un nouveau commit (éditer un fichier, p. ex.) en ajoutant [sphinx-build] au début de la ligne du message de commit. La compilation se lance (il faut parfois attendre un moment si le runner n’est pas disponible).
Allez vérifier dans Intégration et livraison continue>Pipelines que la compilation se déroule bien. La progression s’affiche en temps réel et Réussi s’affiche si elle s’est déroulée correctement.
Cliquez sur le bouton Réussi, puis sur Pages pour afficher la dernière moûture de la compilation.

Composition d’un répertoire de repo#

Le répertoire doit comprendre les fichiers suivants :

un fichier index qui répertorie les différents fichiers à compiler ;
un fichier (éventuel) de références bibliographiques .bib, qui sera appelé par les différents fichiers précédents ;
les fichiers nécessaires à la compilation dans GitLab :
- conf.py,
- requirements.txt,
- .gitlab-ci.yml
- .gitignore.txt

Possibles problèmes#

La création d’un fichier .bib de références est assez délicate. Ne pas hésiter à utiliser un logiciel de gestion de références .bibTeX (comme BibDesk). Attention aussi, en cas de problèmes, à supprimer tout le répertoire /latex pour que la compilation recommence de 0.