2. Construction des pages html de la documentation#

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

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

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