3. Rédaction des documents#

3.1. 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…

3.2. É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

3.3. 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).

3.4. 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 : ./doc_build.sh 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.

3.5. 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.

3.6. 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.