2. Construction of html documentation pages#

2.1. Construction utility#

Swiss Army knife script: « . /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 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', 'changed', 'open', 'clean', 'distclean':
  --builddir= DIR alternative build directory (default: _build)
  --builder= BUILDER one of 'sif' (default), 'venv' or 'native'.
      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. Building documentation#

  • Consult the file « README »

  • Build everything:

    . /doc_build.sh html

  • Filter:

    . /doc_build.sh --pattern=r5.03 html

  • Build only modified documents (git status):

    ``. /doc_build.sh « 

    ``. /doc_build.sh changed

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

notes

Updating interdocument links requires running the construction (see the --twice option).

A lot of warnings during the first pass because of these links.

Since the construction is incremental, when you add a paragraph, the whole is not necessarily rebuilt. Numbering is sometimes absent. Simply rebuild the document after deleting the cache (do « . /doc_build.sh clean, then rebuild).

2.3. Other options#

  • Update (or initialize) the docs with restricted access:

    . /doc_build.sh sync

    It is advisable to always start from the main branch before making any changes.

    See Git credential storage.

  • Delete the construction directory:

    . /doc_build.sh clean

  • Browse the locally built doc:

    . /doc_build.sh open

  • Other functions:

    . /doc_build.sh --help