## NEMO manuals

This repository collects NEMO documentation manuals in LaTeX format.

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

## 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 [ TODO: add description of LaTeX packages required to build manuals ]. 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 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

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.