Tutoriel – Initialiser une configuration GitLab-ReadTheDocs#

Information

Auteur : Philippe Dessus, Inspé & LaRAC, Univ. Grenoble Alpes.
Date de création : Février 2019.
Résumé : Ce document décrit comment initialiser et configurer un nouveau projet GitLab-ReadTheDocs. Attention : cela ne peut être fait que si l’utilisateur a suffisamment de droits dans le dépôt GitLab concerné et dans le serveur ReadTheDocs.
Voir aussi : Il est conseillé de lire le Document Introduction à Git avant celui-ci. Merci à Maxime Gaillard et Léo Stévenin, de Naeka, qui ont configuré les serveurs.

Gitlab avec un système d’intégation-livraison#

Cette procédure est utilisable pour créer un nouveau répertoire sur un serveur GitLab bénéficiant d’une intégration/livraison continue.

Sur l’ordinateur local

copier un dossier ayant déjà été mis en ligne, en faisant attention de supprimer le répertoire .git du dossier précédent rm -fr .git
copier les fichiers nécessaires (en faisant bien attention que .gitignore ; .ci-gitlab.cy soient précédeés d’un point, et que .gitignore n’est pas suivi de .txt)
- .gitignore
- .ci-gitlab.cy
- requirements.txt (seulement pour sphinx, pas pour les projets marp, par exemple)
- conf.py (seulement pour sphinx, même remarque)

Sur le serveur GitLab

Créer un nouveau projet dans le groupe qui convient et donner son niveau de visibilité (public). Ne pas cocher “Initialiser le dépôt avec un README“.

Revenir au dossier-source de l’ordinateur

Dans une fenêtre de terminal, taper les commandes suivantes :

cd existing_repo
git init --initial-branch=main
git remote add origin https://gricad-gitlab.univ-grenoble-alpes.fr/<nom_du_repertoire
git add .
git commit -m "Initial commit"
git push -u origin main (donner son id/mot de passe, et les données locales sont poussées sur le serveur GitLab)

Sur le serveur GitLab

Aller dans Paramètres>Intégration et livraison continue>Exécuteurs et cliquer de manière à sélectionner “Activer les exécuteurs partagés pour ce projet“ dans la rubrique “Exécuteurs partagés”.

GitLab-Readthedocs#

Le but de cette procédure est de configurer un nouveau projet sur les serveurs GitLab et ReadTheDocs (dorénavant, RTD), installés sur 2 serveurs différents. Il faut respecter scrupuleusement ces étapes.

Le volet GitLab#

Demander à l’administrateur de vous faire créer un compte sur le serveur GitLab. Vous recevrez un courriel avec un lien vous permettant d’accéder au serveur et de commencer par changer votre mot de passe. Retenez précieusement votre identifiant/mot de passe.
Vous arrivez sur l’interface de Gitlab, dans laquelle vous pouvez : créer un nouveau projet, créer un groupe, explorer les projets existants, lire la documentation de GitLab. Pour commencer, il est plus simple, pour se familiariser avec le processus, d’aller sur le projet sandbox (bac à sable). Cliquez donc sur *Explore public projects">All>Philippe Dessus/Sandbox.
Vous tombez sur l’interface classique de GitLab/GitHub, dans laquelle vous pourrez réaliser les tâches classiques de cet outil (voir Tutoriel – Éditer un fichier avec GitLab) Il est conseillé, si vous ne connaissez pas cet outil, de lire un tutoriel avant de réaliser la moindre action dans le logiciel.

4. Pour commencer, le plus simple est de demander à l’administrateur d’avoir les droits de modification du projet sandbox (il devrait vous les donner par défaut). Si vous ne les avez pas, vous ne pourrez directement le modifier, mais il faudra le forker (i.e., le recopier). Autre conseil, l’interface web de GitLab convient pour les modifications mineures. Pour un travail plus intensif il faudra l’utiliser via Terminal ou logiciel client. Avant de passer à RTD, copiez l’URL complète du projet sandbox http://espe-gitlab-reflexpro.u-ga.fr/pdessus/sandbox.git. L’URL du serveur RTD qui publie la dernière version des documents est http://espe-rtd-reflexpro.u-ga.fr/docs/sandbox2/fr/latest/.

ATTENTION : Ce qui suit ne concerne que les personnes qui créent un nouveau projet. Elles doivent demander à l’administrateur de réaliser les tâches suivantes.

Le volet RTD#

Configuration de RTD#

Il faut maintenant vous créer un compte directement sur le serveur RTD (sans requête à l’administrateur). Allez à l’URL http://espe-rtd-reflexpro.u-ga.fr. Cliquez sur le bouton “Inscription” (en haut à droite), et renseignez les éléments demandés. Vous êtes immédiatement connecté. Retenez-les précieusement.
Vous arriez sur la page “Ready to share your documentation?”. Cliquez sur le bouton “Import a Project“, de la page suivante (“Importer un dépôt”), cliquez sur “Importer manuellement”.
Renseignez le nom du projet : sandbox (ou tout autre nom), collez l’URL du projet sandbox précédemment copiée (étape 4), laissez Git dans “Type de dépôt ». Cliquez sur le bouton “Suivant”.
Vous êtes maintenant dans le projet RTD sélectionné. Cliquez sur le bouton “Admin”, puis, dans l’onglet “Integrations” cliquez sur le bouton “Add integration”. Dans le menu ”Integration Type” choisissez ”GitLab incoming webhook” puis cliquez sur le bouton “Add integration”. Une page “Integration - Gitlab incoming webhook” apparaît. Copiez l’URL mentionnée dans la page <http://espe-rtd-reflexpro.u-ga.fr/api/v2/webhook/sandbox/XX>, où XX est un nombre.

Configuration fine de RTD#

Toujours dans la page “Admin“, cliquez sur “Paramètres avancés” et tapez “requirements.txt” dans le champ “Fichier des prérequis”, puis Enregistrez.

Retour dans la configuration GitLab#

Retournez dans GitLab et à la page principale de votre projet (p. ex. en faisant “Projects”>“Your Projects” et en cliquant sur le projet voulu.
Cliquez ensuite sur “Settings” du bandeau de gauche, puis “Integrations”. Dans la page qui s’ouvre, collez l’URL que vous avez récupérée de RTD (sans oublier le <http://>). Vérifiez que la case Trigger>“Push events” est bien cochée, et décochez “Enable SSL verification”.
Cliquez ensuite sur le bouton “Add webhook”. Il vous est maintenant possible de tester le bon fonctionnement du webhook en cliquant sur le bouton “Test”>“Push events” et l’information “Hook executed successfully” devrait s’afficher en haut de l’écran. Votre chaîne GitLab/RTD est maintenant prête à fonctionner.

Les fichiers nécessaires#

Il y a un ensemble de fichiers nécessaires pour faire fonctionner la compilation Sphinx sous GitLab. En voici la liste :

conf.py est bien sûr indispensable car il contient les options et préférences de Sphinx ;
.gitlab-ci.yml est un fichier qui décrit les “jobs” que les services d’intégration continue de GitLab vont lancer ;
requirements.txt est la liste des programmes (souvent des extensions) dont Sphinx aura besoin pour fonctionner (certains de ces programmes peuvent aussi être décrits et lancés dans gitlab-ci.yml) ;
.gitignore.txt est la liste des répertoires que GitLab va ignorer dans les commits.

Tutoriel – Initialiser une configuration GitLab-ReadTheDocs

Contenu