d8.00.00 Présentation du système documentaire#

Résumé :

Ce document présente le système documentaire. Il s’agit d’un document à destination des personnes qui doivent rédiger, modifier des documents.

On modifie les documents comme du code source. Cela implique de se familiariser un minimum avec Git, GitLab, un éditeur de texte et l’écriture d’équations au format LaTeX (cf. Rédaction des documents).

Construction des pages html de la documentation#

Utilitaire de construction#

Script couteau suisse : ./doc_build.sh

+ command line: ./doc_build.sh --help
usage: ./doc_build.sh [options] command

  This script provides a simple access to the most common tasks on the documentation.

command:
  html                build html pages
  changed (default)   only build html pages for changed documents since --from (see below)
  open                open the index page with your default browser
  clean               remove the existing build directory
  clean-builder       remove the builder directory
  distclean           clean + clean-builder
  sync                update repository (and also intranet documents if available, *EDF* only)
  create docid        create a new document

options for 'html', 'changed', 'open', 'clean', 'distclean':
  --builddir=DIR      alternative build directory (default: _build)
  --builder=BUILDER   one of 'sif', 'venv' or 'native'.
      By default it uses the last builder used the previous time.
      Can be set using the BUILDER environment variable.

options for 'html', 'changed':
  --twice             build twice (to update reference links)
  --pattern=PATTERN   pattern use as a filter to select docs, start with 're:' for regexp
  -j, --jobs          number of jobs in parallel (default: all available cores)
  --baseurl=URL       define the final base url of the pages
  --nosymlinks        do not use symlinks (increase disk usage)
  --iframe            insert menu using an iframe (server required)
  --stop-on-failure   stop after one build failed
  --lang=LANG         select language for automatically generated pages (default: fr)
  --rtd               use a preselected pattern for RTD
  -n, --nobuild       only prepare docs structure, do not build docs
  -v                  more verbosity (can be repeated)
  -q                  less verbosy, just warnings on stderr

options for 'changed':
  --from COMMIT       use to build the changed docs since this commit (default: HEAD)

Construire la documentation#

  • Consulter le fichier README

  • Construire tout : ./doc_build.sh html

  • Filtrer : ./doc_build.sh --pattern=r5.03 html

  • Construire uniquement les documents modifiés (git status) :

    ./doc_build.sh

    ./doc_build.sh changed

    ./doc_build.sh changed --from origin/main

Remarques

La mise à jour des liens interdocuments nécessite de lancer 2 fois la construction (voir l’option --twice).

Beaucoup de warnings lors de la première passe à cause de ces liens.

La construction étant incrémentale, quand on ajoute un paragraphe, l’ensemble n’est pas forcément reconstruit. La numérotation est parfois absente. Il suffit de reconstruire le document après avoir supprimé le cache (faire ./doc_build.sh clean, puis reconstruire).

Autres options#

  • Mettre à jour (ou initialiser) les docs en accès restreint : ./doc_build.sh sync

    Il est conseillé de toujours repartir de la branche main avant tout modification.

    Voir Stockage des identifiants Git.

  • Supprimer le répertoire de construction : ./doc_build.sh clean

  • Parcourir la doc construite localement : ./doc_build.sh open

  • Autres fonctions: ./doc_build.sh --help

Rédaction des documents#

Enrichir la documentation#

  • Mettre à jour la branche main et le dépôt intranet :

    ./doc_build.sh sync

    Si on travaille sur une branche différente, le script demande si on veut basculer sur main. En cas de doute, répondre non et basculer manuellement plus tard.

  • Créer une branche:

    git checkout -b mc-demo

  • Éditer les documents…

Éditer un document#

  • Pas d’application dédiée.

  • La documentation se modifie comme du code source :

  • Localisation des documents :

    • source/manuals/man_r/r5/r5.03.01/index.rst

    • source/manuals/man_r/r5/r5.03.01/images/

    • …

    • source/intranet/man_u/u2/u2.04.10/index.rst

Créer un nouveau document#

Avant d’ajouter un nouveau document, il faut demander aux mainteneurs la clé du nouveau document (sous la forme x0.00.00).

On fait ensuite:

./doc_build.sh create d8.99.99

IMPORTANT: Pour les utilisateurs ayant accès au dépôt intranet, le script demande s’il s’agit d’un document à accès restreint.

+ document created: source/manuals/man_d/d8/d8.99.99

La page principale du document, index.rst, est créée dans le dossier adéquat, ainsi qu’une page nommée page.rst (à renommer selon l’utilisation).

Soumettre les modifications#

On modifie la documentation comme du code source dans le dépôt Git.

  • Créer une branche comme indiqué ci-dessus : git checkout -b ...

  • Controler l’état des modifications : git status

  • Enregistrer les modifications dans une révision git commit [-m "message de commit"]

  • Pousser la branche : git push

  • Ouvrir une merge-request dans le dépôt `gitlab-codeaster/doc/docaster`_ pour intégrer les modifications de la branche.

Note

Les mêmes étapes doivent être faites dans le dépôt intranet en cas de modifications des documents à accès restreint.

En cas de modifications dans les deux dépôts, il est conseillé d’utiliser le même nom de branche pour le merge-request pour construire un ensemble cohérent.

Période de transition#

  • L’ancienne application est stoppée.

  • La documentation de la v16 est publiée en PDF.

  • Les derniers documents modifiés ont été intégrés en RST au dépôt Git.

  • Les impacts suite aux développements en v17 doivent être rédigés dans le dépôt `gitlab-codeaster/doc/docaster`_, soumis via un merge-request par fiche (+ intranet).

  • Si un document existe déjà en ODT, il est possible ponctuellement de le convertir en RST.

  • La documentation est disponible sur internet, hors documents intranet bien sûr, en suivant ce lien `docaster internet`_.

Améliorations en cours#

Il y a encore quelques corrections génériques qui peuvent être scriptées.

Les erreurs devront être corrigées au fur et à mesure des modifications.

Note

Quand on construit un document, il faut corriger toutes les erreurs (messages ERROR ou CRITICAL) et tous les avertissements (messages WARNING). Les références vers les autres documents peuvent ne pas être résolues lors de la première construction. Relancer une fois (ou utiliser l’option --twice), il ne doit plus en rester.

Pour les erreurs de mise en forme, compléter issue #2 sur GitLab.

Annexes#

Stockage des identifiants Git#

Lors de ./doc_build.sh sync, il y a plusieurs connexions au dépôt distant. Il est confortable de stocker les identifiants pour ne pas avoir à les saisir plusieurs fois.

  • Pour stocker les identifiants:

    git config --global credential.helper store

  • Les identifiants sont stockés dans ~/.git-credentials

  • Voir la section git-credential-store dans le GitBook pour le format de ce fichier.