Documentation d'équipe sous Mkdocs logo

Prérequis

  • Python3
  • pip3
  • mkdocs
  • thème bootswatch pour mkdocs

Installation

1 - Installer python3 et pip (si nécessaire)

Sous Debian :

sudo apt-get install python3 python3-pip

Sous CentOS7 :

sudo yum install -y python36 python36-libs python36-devel python36-pip

2 - Installer mkdocs et le thème bootswatch (ou autre thème souhaité)

Une fois pip3 disponible, sous Debian comme sous CentOS7 :

sudo pip3 install mkdocs
sudo pip3 install mkdocs-bootswatch

3 - Par défaut sous mkdocs, il n'y a pas de coloration syntaxique. Il est possible d'en obtenir une via une extension de markdown, contenue dans le paquet Pygments :

sudo pip3 install pygments

Préparation du répertoire de travail

1 - Créer un répertoire documentation qui contiendra tous les documents nécessaires à la documentation et s'y déplacer.

2 - Créer un sous-répertoire docs qui contiendra uniquement les fichiers markdown qui vont constituer la documentation et s'y déplacer.

3 - Créer tous les fichiers que l'on souhaite ajouter sous la forme <menu>-<item>.md. Par exemple, la page GitLab CI du menu CI se trouve dans le fichier documentation/docs/ci-gitlabci.md

Les pages sont écrites en markdown classique, comme dans les documentations GitHub ou GitLab par exemple. Une bonne ressource pour écrire du markdown se trouve ici.

4 - Créer un fichier index.md qui va constituer la page "d'accueil de la documentation".

5 - Remonter dans le répertoire documentation. Y créer un fichier mkdocs.yml qui va regrouper tous les items.

Exemple minimal de fichier mkdocs.yml :

#Titre du site
site_name: Documentation

#Page "d'accueil"
nav:
  - Accueil: index.md

6 - Il est possible "d'étoffer" le site en ajoutant des menus et des pages à ces menus, en complétant le fichier mkdocs.yml. "C'est" également dans ce fichier que "l'on" peut rajouter les différentes extensions et thèmes. Les thèmes existants pour Mkdocs sont disponibles ici.

Exemple :

#Titre du site
site_name: Documentation

#Onglets de navigation, dans les menus
nav:
     - Accueil: index.md
     - Menu 1:
       - Première Page: premiere-page.md
       - Sous-Menu 1:
         - Deuxième Page: deuxieme-page.md
     - Menu 2:
       - Troisième Page: troisieme-page.md

#Extension pour la coloration syntaxique
markdown_extensions:
   - codehilite

#Thème pour l'affichage.
theme: flatly

Le fichier mkdocs.yml utilisé dans notre cas se trouve ici.

Compilation

Pour pouvoir être visualisée, la documentation doit d'abord être compilée.

1 - Créer le fichier de compilation compile.sh, qui va créer un dossier site-html-generated contenant tous les éléments nécessaires à la visualisation en ligne. Éditer le fichier documentation/compile.sh

#!/bin/bash
mkdocs build -d ./site-html-generated

2 - Exécuter ce script depuis la racine du dépôt Git (documentation)

./compile.sh

Utilisation

Utilisation simple

Une fois la documentation compilée, il suffit d'ouvrir index.html situé dans le répertoire site-html-generated fraîchement créé.

Notez que quand vous ouvrez la documentation en local, la navigation est difficile puisque Firefox ou Chrome préfèrent montrer le contenu des dossiers plutôt que d'ouvrir les fichiers index.html directement.

Une solution est de mettre la documentation sur un serveur, ou d'utiliser un serveur web local, par exemple via docker:

docker run -dit --rm -p 80:80 -v /<absolute_path>/documentation/site-html-generated:/usr/share/nginx/html nginx:stable-alpine

L'accès à la documentation se fait alors via: http://localhost.

Ajout de documentation

1 - Ajouter un fichier dans le dossier docs, selon la nomenclature définie précédemment, contenant un nouvel item.

2 - Éditer le fichier mkdocs.yml en rajoutant l'item créé et le menu si nécessaire.

3 - Relancer la compilation et rouvrir index.html (ou le serveur selon la solution choisie).

Utilisation dans une chaîne CI/CD

Afin d'actualiser la documentation en temps réel, il est possible de créer une chaîne d'intégration et de déploiement continus.

1 - Créer un dépôt où le code sera envoyé dès qu'il sera modifié.

Exemple : un dépôt GitLab

2 - Créer une chaîne d'intégration, avec tous les fichiers de configuration nécessaires.

Exemple : utilisation de Jenkins

  • Création d'un fichier Dockerfile pour pouvoir lancer la construction de l'image
  • Création d'un fichier Jenkinsfile pour intégrer les nouveautés du dépôt et construire les images
  • Installation de MkDocs sur la machine où est installé Jenkins
  • Configuration du pipeline Jenkins

3 - Mettre en place un déploiement continu, avec un accès internet simplifié.

Exemple : utilisation de Ouroboros et Træfik

4 - Mettre en place un Docker Compose pour simplifier le lancement et la configuration du conteneur déployé.

Exemple : un fichier docker-compose.yml