SP01 : Mise en place de la documentation

Compétences associées : 3.3, 4.1, 6.1

Dans le cadre de mon alternance chez Solutech, Léo Martin, m'a confié ma première mission professionnelle : structurer la documentation de l'équipe. Ce document présente le contexte, les décisions et le déroulement de la mission.

1. Contexte

Solutech n'a jamais vraiment eu de documentation organisée. Quand un technicien doit refaire une opération, il demande à un collègue plutôt que de chercher la doc.

La mission SP-P1, consiste donc à créer une véritable documentation, versionnée et accessible facilement.

2. Objectifs

Quatre résultats attendus, dans l'ordre de priorité :

  1. Écrire vite et propre : un environnement de rédaction adapté au Markdown
  2. Versionner : tracer les modifications et revenir en arrière si besoin
  3. Publier automatiquement : un site web à chaque mise à jour automatiquement (docs as code)
  4. Documenter la mise en place : cf cette page

3. Besoins identifiés

Besoin Implication
Simplicité Un format léger qui permet de mettre en forme simplement
Historique Savoir ce qui a changé, quand et pourquoi, avec possibilité de retour arrière
Publication pas d'export manuel ou de transfert FTP, une mise à jour au push idéalement
Accessibilité La doc doit se lire dans un navigateur, sans compte ni installation

4. Solution technique retenue

Outil Rôle Pourquoi lui
VSCode Éditeur de texte Gratuit, répandu, extensions Markdown très puissantes
Markdown Format de rédaction lisible partout, mise en forme simple
MkDocs + thème readthedocs Générateur de site Produit un site statique depuis les fiches markdown
mkdocs-nav-weight Plugin MkDocs Permet de classer les pages de la navigation directement dans la configuration
Git Gestion de versions Historique complet, retour arrière
GitLab Hébergement du dépôt Centralise le code, intègre la CI/CD nativement, rend l'historique visible
GitLab Pages + CI/CD Publication automatique Un pipeline reconstruit et publie le site à chaque push

Pourquoi cette combinaison

L'ensemble met en pratique le principe de Documentation as Code : la documentation est traitée exactement comme du code source. Elle est versionnée dans Git, relue avant publication, construite et déployée par un pipeline.

Pour Solutech, l'avantage est double : La doc devient un site web toujours à jour avec la dernière version publiée, et, chaque modification laisse une trace.

5. Réalisation

Voici le déroulé de la mission, étape par étape.

5.1 Initialiser le projet MkDocs

Création du projet, configuration du thème readthedocs, ajout du plugin de navigation, mise en place de l'arborescence docs/.

5.2 Versionner sur GitLab

Initialisation du dépôt Git, liaison avec le projet distant coodlab/portfolio-lino-mallevaey.

historique des commits GitLab Historique des commits GitLab

5.3 Automatiser la publication

Écriture du pipeline .gitlab-ci.yml qui installe MkDocs, construit le site et le publie sur GitLab Pages à chaque push sur main.

pipeline GitLab CI avec le job pages en vert Pipeline GitLab CI réussi

5.4 Vérifier la mise en ligne

Contrôle du résultat : le site est consultable publiquement et se met à jour à chaque push.

Site en ligne dans le navigateur Portfolio publié en ligne

6. Preuves de réalisation

Configuration mkdocs.yml

site_name: Lino Mallevaey
use_directory_urls: true
site_description: "Portfolio de compétences E5 — BTS SIO"
site_author: "Lino MALLEVAEY"

theme:
  name: readthedocs
  highlightjs: true

plugins:
  - search
  - mkdocs-nav-weight

nav:
  - Accueil: index.md
  - Mon Profil:
      - Présentation: 01_Profil/index.md
  - Support et Mise à Disposition de Services Informatiques:
      - Présentation: 02_Support/presentation.md
      - Mise en place environnement: 02_Support/mise-en-place-doc.md
  - Synthèse:
      - Tableau de synthèse: 06_Synthese/Tableau-Synthese.md
  - Autre:
      - Exercice Syntaxe: 07_autre/exercice-syntaxe.md

Pipeline de publication .gitlab-ci.yml

image: python:latest

pages:
  stage: deploy
  script:
    - pip install mkdocs
    - pip install mkdocs-nav-weight
    - mkdocs build --verbose --site-dir public
  artifacts:
    paths:
      - public
  only:
    - main
    - master

À chaque push sur main, GitLab exécute le job pages : installation des dépendances, construction du site dans public/, publication sur GitLab Pages.

Le site en ligne