Documentation

Comment nous faisons pour générer la documentation de notre projet.

Nous utilisons les outils suivants pour générer la documentation de notre projet:

Gitlab Pages
Gitlab CI / CD
Writerside

Writerside est un outil de génération de documentation statique. Il permet de générer des pages web et pdf à partir de fichiers markdown. Son avantage est de fournir un IDE avec tous les outils pour écrire de la documentation. Comme correcteur orthographique, génération de table des matières, linter markdown, etc. Et il est optimisé pour le travail collaboratif. Via l'utilisation de GIT

Comment nous déployons notre documentation

Écrire sur writerside

Nous devons d'abord générer une instance dans writerside

Une fois l'instance générée, nous pouvons créer tous nos fichiers markdown et écrire notre documentation. Nous devons nous assurer que toutes les images et ressources éxterne sont bien accessible, par writerside.

Construction de la documentation

Une fois que nous avons fini d'écrire notre documentation, nous devons construire notre documentation. Pour cela, nous devons pusher notre documentation sur notre repository gitlab.

git add .
git commit -m "Ajout de la documentation exemple"
git push origin doc-infra-ci-example

Et ensuite, nous avons dû créer une pipeline de ci pour builder notre documentation.

## Variables pour instancier notre documentation
variables:
  INSTANCE: 'Writerside/htiam'
  DOCKER_VERSION: '243.22562'
  ALGOLIA_APP_NAME: 'V6MS25BRYB'
  ALGOLIA_INDEX_NAME: 'how-to-manage-and-install'
  CONFIG_JSON_PRODUCT: 'HTIAM'
  CONFIG_JSON_VERSION: '1.0'
  PDF: "PDF.xml"

stages:
  - build
  - build_pdf
  - test
  - deploy


build:
  stage: build
  image: registry.jetbrains.team/p/writerside/builder/writerside-builder:$DOCKER_VERSION
  
  ## Script pour builder notre documentation
  script:
    
    - set -e
    # On exporte la variable DISPLAY pour que le runner gitlab puisse lancer des applications graphiques
    - export DISPLAY=:99
    - Xvfb :99 &
    - PROJECT_ID=$(echo $INSTANCE | cut -d'/' -f2 | tr '[:lower:]' '[:upper:]')
    - ARTIFACT="webHelp${PROJECT_ID}2-all.zip"
    # On lance l'IDE de writerside pour builder notre documentation dans un artifact
    - /opt/builder/bin/idea.sh helpbuilderinspect -source-dir . -product $INSTANCE --runner gitlab -output-dir public
    - echo "Testing existence of $ARTIFACT..."
    - ls -la public
    - test -e public/$ARTIFACT
  artifacts:
    paths:
      - public/$ARTIFACT
      - public/report.json
      - public/$ALGOLIA_ARTIFACT
    expire_in: 1 week

# Build the PDF
build_pdf:
  stage: build_pdf
  image: registry.jetbrains.team/p/writerside/builder/writerside-builder:$DOCKER_VERSION
  script:
    - set -e
    - export DISPLAY=:99
    - Xvfb :99 &
    - PROJECT_ID=$(echo $INSTANCE | cut -d'/' -f2 | tr '[:lower:]' '[:upper:]')
    - PDF_FILE="pdfSource${PROJECT_ID}.pdf"
    - HTML_FILE="pdfSource${PROJECT_ID}.html"
    - /opt/builder/bin/idea.sh helpbuilderinspect -source-dir ./Writerside -product $INSTANCE --runner gitlab -output-dir public -pdf $PDF
    - echo "Testing existence of $PDF_FILE and $HTML_FILE"
    - test -e public/$PDF_FILE
    - test -e public/$HTML_FILE
  artifacts:
    paths:
      - public/$PDF_FILE
      - public/$HTML_FILE
    expire_in: 1 week

# Check writerside 
test:
  stage: test
  image: openjdk:18-jdk-alpine
  before_script:
    - apk add curl
  script:
    - cd public
    - curl -o wrs-checker.jar -L https://packages.jetbrains.team/maven/p/writerside/maven/com/jetbrains/writerside/writerside-ci-checker/1.0/writerside-ci-checker-1.0.jar
    - java -jar wrs-checker.jar report.json $INSTANCE
  dependencies:
    - build

# Deploy the pages 
pages:
  stage: deploy
  image: ubuntu:noble
  before_script:
    - apt update && apt install unzip
# On récupère l'artifact de la documentation et on le dézippe dans les pages
  script:
    - PROJECT_ID=$(echo $INSTANCE | cut -d'/' -f2 | tr '[:lower:]' '[:upper:]')
    - ARTIFACT="webHelp${PROJECT_ID}2-all.zip"
    - echo "Using artifact $ARTIFACT"
    - cd public
    - unzip -O UTF-8 $ARTIFACT
  dependencies:
    - build
  artifacts:
    paths:
      - public
    expire_in: 1 week
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Mise en services des gitlab pages

Tous d'abord, nous avons du créer une wildcard dns sur cloudflare pour permettre à gitlab de générer les pages.

Ensuite nous avons du reconfigurer notre reverse proxy afin qu'ils puissent servir les pages générées par gitlab.

pages.innovalia.cc,
*.pages.innovalia.cc:443 {
    reverse_proxy http://gitlab:19001 {
    }  # Redirige le trafic vers GitLab
    tls {
        dns cloudflare {env.CF_API_TOKEN}
    }
    # Redirection du trafic HTTP vers HTTPS
    #redir https://{host}{uri} permanent
}

Nous avons choisi le port 19001 pour servir les pages générées par gitlab.

Une fois toute la configuration réseau faite, nous devions aussi faire des modifications sur le gitlab pour activer les pages. Il était nécéssaire d'activé les pages dans les gitlab-rails:

pages_nginx['enable'] = true
        pages_nginx['listen_port'] = 19001 
        pages_nginx['listen_https'] = false
        pages_nginx['redirect_http_to_https'] = true

Après avoir rebuild le tout nous devons arriver sur une pages gitlab lorsque nous allons sur https://pages.innovalia.cc

Build via la CI

Donc si nous lançons la ci nous pouvons récupérer deux artifacts. Un pdf et un zip contenant les pages web. Et une pages web avec notre documentation qui est accessible via https://pa4.pages.innovalia.cc/documentation/how-to-install-and-manage/

Voici un exemple de l'exécution de la ci :

Résultat des artifacts:

Pages web accessible via https://pa4.pages.innovalia.cc/documentation/how-to-install-and-manage/:

Last modified: 13 July 2025