NEMO manuals

This repository collects NEMO documentation manuals in LaTeX format.

• NEMO physical core components
• TOP interface for passive tracers
• SI3 sea ice model

To generate the manual(s) PDF it is necessary to install the LateX typesetting system and the python package pygments.

Cloning with submodules

This repository uses the namelists and gallery documentation projects as git submodules.

So when cloning this repository it is necessary to clone also the related submodules, using the following command

git clone --recurse-submodules <reponame>

If the repository was cloned in a standard way, it is possible to checkout submodules using

git submodule update --init

Building the doumentation

Automatic build

A pipeline is setup to run automatically whenever a push occurs on a branch. On average it takes about 6 minutes to run. The automatically generated PDF will be titled with the branch name instead of a version number to reflect its development status. The branch name is passed using the $CI_COMMIT_REF_NAME environment variable created by the runner when it checks out the git branch in the virtual execution environment.

The pipeline method is mainly intended to check the validity of changes made to the LaTeX files but it is useful for infrequent contributors who would otherwise struggle to maintain a suitable LaTeX build environment on their own platforms.

The compiled PDF versions of the manuals are available for a short period (15 minutes) after a successful pipeline completion. At this stage, they are pipeline artifacts and there are several ways to access them. Probably the easiest is to go directly to the CI/CD pipeline tab (from the left sidebar) where all the pipelines executed will be listed (https://forge.nemo-ocean.eu/nemo/doc/manuals/-/pipelines) . On the right of each successfil pipeline there is a download button to Download the artifacts.

Manual build

Regular contributors to the reference manuals are likely to maintain LaTex build environments on their local resources. The manual_build.sh script can be used to generate the PDF version of manual(s) in a local environment as follows:

./manual_build.sh [-c] [-p] [-r version ] manual_name

manual_name : Chose one model manual among NEMO, SI3, TOP, or all (if not provided, it will compile NEMO)

Optional commands :

-c Clean up previous builds of the manual(s)

-p Produce manual with figures and disable draft watermark

-r Specify the release version number of the manual(s) instead of the branch name

Known troubles

./manual_build.sh must be called several times in a row (up to 4 times) to avoid all the errors messages and get the proper pdf..

If you get an error due to the missing location of FontAwesome, it is necessary to set the local path of LaTeX fonts in the file latex/global/packages.tex at \defaultfontfeatures. Be carefull not to commit this modification to the remote code.