## NEMO User guide

This project contains the source files (rst format) allowing to build the [html files for NEMO User's guide](https://sites.nemo-ocean.io/user-guide/)

The NEMO guide is made up of several files written in [ReStructuredText](http://docutils.sourceforge.net/rst.html) (`.rst` extension), a WYSIWYG markup language used in the Python community.

If you want to make some changes and updates, you can edit the rst source files in the `./source` folder.

The User guide is web-based and is automatically generated from rst files, [namelists and gallery](https://forge.nemo-ocean.eu/nemo/doc). 

## Build and browse the local HTML guide

1. Create the user guide conda environment using the provided YAML file by typing 

`$> conda env create -f environment.yml`


2. Build locally the HTML export of the user guide with the build script

`$> ./guide_build.sh`

3. Finally browse the guide by opening `./build/html/index.html`


## 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 `


## Update the online documentation

Once that requested changes are committed to one or all these 3 projects, it is necessary to update their links into this project which in turn will trigger the Continuous Integration rebuilding the html files. 

[This project at the top](https://forge.nemo-ocean.eu/sites/user-guide) is for now available to NEMO Officers only, so that you need to contact your NEMO  Officer to [finalise the update and rebuild the html files](https://forge.nemo-ocean.eu/sites/user-guide/-/blob/main/README.md)