.. _d8.00.00-redaction:

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 :

   -  éditeur de texte,
   -  éditeur d’équations LaTeX:
      `https://www.hostmath.com <https://www.hostmath.com/>`__,
   -  Git,
   -  GitLab,
   -  *merge-requests*.
-  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:

.. code-block:: shell

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

.. code-block:: text

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

.. _d8.00.00-redaction-push:

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.

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 <https://gitlab.pleiade.edf.fr/codeaster/doc/docaster/-/issues/2>`__
sur GitLab.

.. include:: ../../../../../_cache/external_refs.rst