Skip to content

Format de documentation

Ma documentation est réalisée avec MkDocs qui est un générateur de site statique open source conçu pour simplifier la création de documentation propre et professionnelle à partir de fichiers au format Markdown.

La force que je trouve au markdown est sa facilité et sa lisibilité. Le markdown est très simple à apprendre et à utiliser et il se concentre sur le contenu.

Pour lui donner un côté plus esthétique, j'ai utilisé la librairie Material for MkDocs qui offre une expérience utilisateur moderne et intuitive pour la création de documentation. Il se base sur le framework Material Design de Google, ce qui lui confère un aspect visuel élégant et cohérent.

Intégration avec GitLab CI/CD

Le GitLab de l'école dispose d'un système CI/CD qui permet le déploiement automatique du site web de la documentation. À chaque modification du dépôt GitLab, un pipeline CI/CD se déclenche, générant et publiant automatiquement les mises à jour du site de documentation. Ainsi, la documentation reste constamment à jour et accessible en ligne.

Configuration du pipeline CI/CD

Voici le fichier .gitlab-ci.yml utilisé pour configurer le pipeline CI/CD : 

image: python:3.12.2-bookworm

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

before_script:
  - 'python3 -m venv venv'
  - 'source venv/bin/activate'
  - 'pip install --upgrade pip'
  - 'pip install -r requirements.txt'

cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - '.cache/pip'

build:
  stage: build
  variables:
    ENABLE_PDF_EXPORT: 1
  script:
    - 'mkdocs build --verbose --site-dir build'
    - 'cp build/pdf/document.pdf ./documentation.pdf'
  artifacts:
    when: on_success
    paths:
      - 'documentation.pdf'

pages:
  stage: deploy
  variables:
    ENABLE_PDF_EXPORT: 0
  script:
    - 'source ./venv/bin/activate'
    - 'mkdocs build --verbose --site-dir ./public'
  artifacts:
    when: on_success
    paths:
      - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

Explication des étapes du fichier pipeline CI/CD:

  1. image: Spécifie l'image Docker à utiliser. Ici, c'est python:3.12.2-bookworm, qui inclut Python 3.12.2.

  2. variables: Définis les variables d'environnement utilisées pendant le pipeline, comme le répertoire de cache pip.

  3. before_script: Contiens les commandes exécutées avant les étapes de script principales. Ici, il crée un environnement virtuel Python, l'active, met à jour pip, et installe les dépendances définies dans requirements.txt.

  4. cache: Définis les chemins de cache pour pip afin de réduire le temps d'installation des dépendances lors de builds futurs.

  5. build:

  6. stage: Définit le nom de l'étape, ici "build".
  7. variables: Active l'exportation PDF en définissant ENABLE_PDF_EXPORT à 1.
  8. script: Contiens les commandes pour construire le site avec mkdocs et copier le PDF généré.

  9. artifacts: Définit les fichiers à conserver après le succès de l'étape, ici documentation.pdf.

  10. pages:

  11. stage: Définis le nom de l'étape, ici "deploy".
  12. variables: Désactive l'exportation PDF en définissant ENABLE_PDF_EXPORT à 0.
  13. script: Contiens les commandes pour activer l'environnement virtuel et construire le site pour la publication.
  14. artifacts: Définit les fichiers à conserver après le succès de l'étape, ici le répertoire public.
  15. rules: Spécifie que cette étape ne s'exécute que pour les commits sur la branche par défaut du projet.

Plugins utilisé

Pour améliorer la fonctionnalité et l'apparence de la documentation, j'ai utilisé les plug-in suivants :

with-pdf

Le plug-in with-pdf permet de générer un fichier PDF de la documentation lors de la construction du site. Cela est utile pour les utilisateurs qui préfèrent ou ont besoin d'une version imprimée ou hors-ligne de la documentation.

table-of-figures

Le plug-in table-of-figures ajoute automatiquement une table des figures à la documentation. Cela permet de référencer facilement les différentes figures et images incluses dans le contenu, améliorant ainsi la navigation et l'accessibilité de la documentation.

glightbox

Le plug-in glightbox fournit une visionneuse d'images légère et réactive pour afficher les images dans un style de galerie. Cela améliore l'expérience utilisateur en permettant de visualiser les images en pleine taille sans quitter la page de documentation.

Ressources utiles