.. _d8.00.00-construction:

Construction of html documentation pages
===============================================

Construction utility
--------------------------

Swiss Army knife script: ". /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 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)


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

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 :ref:`d8.00.00-credentials`.
- Delete the construction directory:
   ``. /doc_build.sh clean``
- Browse the locally built doc:
   ``. /doc_build.sh open``
- Other functions:
   ``. /doc_build.sh --help``