Scripts de construction de la documentation

Les scripts stockés dans la branche mkdocs/scripts permettent de construire une image docker pour plusieurs versions, pour un type de documentation.

Versions de la documentation

Chaque version de Maarch Courrier à sa version de la documentation correspondante. Chaque version est stockée dans une branche différente dans le projet Gitlab.

La liste des versions incluses dans l'image construite est définie dans le fichier versions.json :

[
  {
    "version": "preview",
    "title": "26.0",
    "aliases": [
      "preview"
    ]
  },
  {
    "version": "24", // Nom du dossier construit. Apparaîtra dans l'URL
    "title": "24.8", // Nom de la version affiché à l'utilisateur dans le switch de version
    "aliases": [
      "latest" // Alias affiché à l'utilisateur (1)
    ],
    "branch": "mkdocs/24" // Nom de la branche Gitlab (2)
  },
  {
    "version": "2301",
    "title": "2301.4",
    "aliases": [],
    "branch": "mkdocs/2301"
  },
  ...
]

1. La version avec l'alias latest aura un lien symbolique latest vers cette version. Ici, La version 24.8.1 sera accessible via http://localhost:9090/24/ et http://localhost/latest/
2. Si la branche n'est pas précisé, cette version ne sera pas incluse dans l'image générée

Types de la documentation

La documentation peut être construite pour plusieurs types différents, ce qui permet d'obtenir plusieurs déclinaisons de la même documentation : documentation interne Maarch, documentation publique, etc.

Chaque type de documentation correspond à un fichier mkdocs.yml différent. Exemple :

• mkdocs.yml correspond à la documentation interne
• mkdocs-public.yml correspond à la documentation publique

Pour choisir le type de documentation au moment du build, il faut configurer la variable d'environnement MKDOC_CONFIG_VERSION (par défaut mkdocs.yml)

Si le fichier défini par MKDOC_CONFIG_VERSION n'existe dans la branche d'une version, cette version ne sera pas incluse dans l'image construite.

En local, il suffit d'ajouter l'option --config-file à la commande de build :

python3 -m mkdocs build --config-file mkdocs-public.yml

Construction de l'image en local

1. Construits tous la documentation et l'image docker

    docker build -t local/maarch-courrier-documentation:TAG_NAME \
    --build-arg MKDOC_CONFIG_VERSION=$MKDOC_CONFIG_VERSION \
    --build-arg BUILDKIT_INLINE_CACHE=1 .
   

   TAG_NAME est le nom de la version de la documentation, public ou interne.
   La variable MKDOC_CONFIG_VERSION permet de selection quelle version de la documentation sera construite.
   mkdocs-public.yml → Pour la publique
   mkdocs.yml → Pour l'interne

2. Lance docker

    docker run -p 9090:80 local/maarch-courrier-documentation:public
   

   Accessible sur http://localhost:9090/