.. _d8.00.00-construction:

Construction des pages html de la documentation
===============================================

Utilitaire de construction
--------------------------

Script couteau suisse : ``./doc_build.sh``

.. code-block:: text

    + 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 :ref:`d8.00.00-credentials`.
-  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``