diff --git a/doc/rst/source/cfgs.rst b/doc/rst/source/cfgs.rst
deleted file mode 120000
index 8cace066235a1d488513b3dddfe8daed174a360d..0000000000000000000000000000000000000000
--- a/doc/rst/source/cfgs.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../cfgs/README.rst
\ No newline at end of file
diff --git a/doc/rst/source/cfgs.rst b/doc/rst/source/cfgs.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9d76be7256a65fb3bba3f364f805853be0e8ff2c
--- /dev/null
+++ b/doc/rst/source/cfgs.rst
@@ -0,0 +1,331 @@
+********************************
+Run the Reference configurations
+********************************
+
+.. todo::
+
+ Lack of illustrations for ref. cfgs, and more generally in the guide.
+
+NEMO is distributed with a set of reference configurations allowing both
+the user to set up his own first applications and
+the developer to test/validate his NEMO developments (using SETTE package).
+
+.. contents::
+ :local:
+ :depth: 1
+
+.. attention::
+
+ Concerning the configurations,
+ the NEMO System Team is only in charge of the so-called reference configurations described below.
+
+.. hint::
+
+ Configurations developed by external research projects or initiatives that
+ make use of NEMO are welcome to be publicized through the website by
+ filling up the form :website:`to add an associated project<projects/add>`.
+
+How to compile an experiment from a reference configuration
+===========================================================
+
+To compile the ORCA2_ICE_PISCES_ reference configuration using :file:`makenemo`,
+one should use the following, by selecting among available architecture file or
+providing a user defined one:
+
+.. code-block:: console
+
+ $ ./makenemo -r 'ORCA2_ICE_PISCES' -m 'my_arch' -j '4'
+
+A new ``EXP00`` folder will be created within the selected reference configurations,
+namely ``./cfgs/ORCA2_ICE_PISCES/EXP00``.
+It will be necessary to uncompress the archives listed in the above table for
+the given reference configuration that includes input & forcing files.
+
+Then it will be possible to launch the execution of the model through a runscript
+(opportunely adapted to the user system).
+
+List of Configurations
+======================
+
+All forcing files listed below in the table are available from |DOI data|_
+
+=================== === === === === === ==================================
+ Configuration Component(s) Archives (input & forcing files)
+------------------- ------------------- ----------------------------------
+ Name O S T P A
+=================== === === === === === ==================================
+ AGRIF_DEMO_ X X X AGRIF_DEMO_v4.0.tar,
+ ORCA2_ICE_v4.0.tar
+ AMM12_ X AMM12_v4.0.tar
+ C1D_PAPA_ X INPUTS_C1D_PAPA_v4.0.tar
+ GYRE_BFM_ X X *none*
+ GYRE_PISCES_ X X X *none*
+ ORCA2_ICE_PISCES_ X X X X ORCA2_ICE_v4.0.tar,
+ INPUTS_PISCES_v4.0.tar
+ ORCA2_OFF_PISCES_ X X ORCA2_OFF_v4.0.tar,
+ INPUTS_PISCES_v4.0.tar
+ ORCA2_OFF_TRC_ X ORCA2_OFF_v4.0.tar
+ ORCA2_SAS_ICE_ X ORCA2_ICE_v4.0.tar,
+ INPUTS_SAS_v4.0.tar
+ SPITZ12_ X X SPITZ12_v4.0.tar
+=================== === === === === === ==================================
+
+.. admonition:: Legend for component combination
+
+ O for OCE, S for SI\ :sup:`3`, T for TOP, P for PISCES and A for AGRIF
+
+AGRIF_DEMO
+----------
+
+``AGRIF_DEMO`` is based on the ``ORCA2_ICE_PISCES`` global configuration at 2° of resolution with
+the inclusion of 3 online nested grids to demonstrate the overall capabilities of AGRIF in
+a realistic context (including the nesting of sea ice models).
+
+The configuration includes a 1:1 grid in the Pacific and two successively nested grids with
+odd and even refinement ratios over the Arctic ocean,
+with the finest grid spanning the whole Svalbard archipelago that is of
+particular interest to test sea ice coupling.
+
+.. image:: _static/AGRIF_DEMO_no_cap.jpg
+ :scale: 66%
+ :align: center
+
+The 1:1 grid can be used alone as a benchmark to check that
+the model solution is not corrupted by grid exchanges.
+Note that since grids interact only at the baroclinic time level,
+numerically exact results can not be achieved in the 1:1 case.
+Perfect reproducibility is obtained only by switching to a fully explicit setup instead of
+a split explicit free surface scheme.
+
+AMM12
+-----
+
+``AMM12`` stands for *Atlantic Margin Model at 12 km* that is
+a regional configuration covering the Northwest European Shelf domain on
+a regular horizontal grid of ~12 km of resolution (see :cite:`ODEA2012`).
+
+.. image:: _static/AMM_domain.png
+ :align: center
+
+This configuration allows to tests several features of NEMO specifically addressed to the shelf seas.
+In particular, ``AMM12`` accounts for vertical s-coordinates system, GLS turbulence scheme,
+tidal lateral boundary conditions using a flather scheme (see more in ``BDY``).
+Boundaries may be completely omitted by setting ``ln_bdy = .false.`` in ``nambdy``.
+
+Sample surface fluxes, river forcing and an initial restart file are included to test a realistic model run
+(``AMM12_v4.0.tar``).
+
+Note that, the Baltic boundary is included within the river input file and is specified as a river source,
+but unlike ordinary river points the Baltic inputs also include salinity and temperature data.
+
+C1D_PAPA
+--------
+
+.. figure:: _static/Papa2015.jpg
+ :height: 225px
+ :align: left
+
+``C1D_PAPA`` is a 1D configuration for the `PAPA station`_ located in
+the northern-eastern Pacific Ocean at 50.1°N, 144.9°W.
+See :gmd:`Reffray et al. (2015) <8/69/2015>` for the description of
+its physical and numerical turbulent-mixing behaviour.
+
+| The water column setup, called NEMO1D, is activated by
+ setting ``ln_c1d = .true.`` in ``namdom`` and
+ has a horizontal domain of 1x1 grid point.
+| This reference configuration uses 75 vertical levels grid (1m at the surface),
+ GLS turbulence scheme with K-epsilon closure and the NCAR bulk formulae.
+
+Data provided with ``INPUTS_C1D_PAPA_v4.2.tar`` file account for:
+
+- :file:`forcing_PAPASTATION_1h_y201[0-1].nc`:
+ ECMWF operational analysis atmospheric forcing rescaled to 1h
+ (with long and short waves flux correction) for years 2010 and 2011
+- :file:`init_PAPASTATION_m06d15.nc`: Initial Conditions from
+ observed data and Levitus 2009 climatology
+- :file:`chlorophyll_PAPASTATION.nc`: surface chlorophyll file from Seawifs data
+
+GYRE_BFM
+--------
+
+``GYRE_BFM`` shares the same physical setup of GYRE_PISCES_,
+but NEMO is coupled with the `BFM`_ biogeochemical model as described in ``./cfgs/GYRE_BFM/README``.
+
+GYRE_PISCES
+-----------
+
+``GYRE_PISCES`` is an idealized configuration representing a Northern hemisphere double gyres system,
+in the Beta-plane approximation with a regular 1° horizontal resolution and 31 vertical levels,
+with PISCES BGC model :cite:`gmd-8-2465-2015`.
+Analytical forcing for heat, freshwater and wind-stress fields are applied.
+
+This configuration acts also as demonstrator of the **user defined setup**
+(``ln_read_cfg = .false.``) and grid setting are handled through
+the ``&namusr_def`` controls in :file:`namelist_cfg`:
+
+.. literalinclude:: ../../../cfgs/GYRE_PISCES/EXPREF/namelist_cfg
+ :language: fortran
+ :lines: 35-41
+
+Note that, the default grid size is 30x20 grid points (with ``nn_GYRE = 1``) and
+vertical levels are set by ``jpkglo``.
+The specific code changes can be inspected in :file:`./src/OCE/USR`.
+
+.. rubric:: Running GYRE as a benchmark
+
+| This simple configuration can be used as a benchmark since it is easy to increase resolution,
+ with the drawback of getting results that have a very limited physical meaning.
+| GYRE grid resolution can be increased at runtime by setting a different value of ``nn_GYRE``
+ (integer multiplier scaling factor), as described in the following table:
+
+=========== ============ ============ ============ ===============
+``nn_GYRE`` ``jpiglo`` ``jpjglo`` ``jpkglo`` Equivalent to
+=========== ============ ============ ============ ===============
+ 1 30 20 31 GYRE 1°
+ 25 750 500 101 ORCA 1/2°
+ 50 1500 1000 101 ORCA 1/4°
+ 150 4500 3000 101 ORCA 1/12°
+ 200 6000 4000 101 ORCA 1/16°
+=========== ============ ============ ============ ===============
+
+| Note that, it is necessary to set ``ln_bench = .true.`` in ``&namusr_def`` to
+ avoid problems in the physics computation and that
+ the model timestep should be adequately rescaled.
+| For example if ``nn_GYRE = 150``, equivalent to an ORCA 1/12° grid,
+ the timestep ``rn_rdt`` should be set to 1200 seconds
+ Differently from previous versions of NEMO, the code uses by default the time-splitting scheme and
+ internally computes the number of sub-steps.
+
+ORCA2_ICE_PISCES
+----------------
+
+``ORCA2_ICE_PISCES`` is a reference configuration for the global ocean with
+a 2°x2° curvilinear horizontal mesh and 31 vertical levels,
+distributed using z-coordinate system and with 10 levels in the top 100m.
+ORCA is the generic name given to global ocean Mercator mesh,
+(i.e. variation of meridian scale factor as cosinus of the latitude),
+with two poles in the northern hemisphere so that
+the ratio of anisotropy is nearly one everywhere
+
+This configuration uses the three components
+
+- |OCE|, the ocean dynamical core
+- |ICE|, the thermodynamic-dynamic sea ice model.
+- |MBG|, passive tracer transport module and PISCES BGC model :cite:`gmd-8-2465-2015`
+
+All components share the same grid.
+The model is forced with CORE-II normal year atmospheric forcing and
+it uses the NCAR bulk formulae.
+
+.. rubric:: Ocean Physics
+
+:horizontal diffusion on momentum:
+ the eddy viscosity coefficient depends on the geographical position.
+ It is taken as 40000 m\ :sup:`2`/s, reduced in the equator regions (2000 m\ :sup:`2`/s)
+ excepted near the western boundaries.
+:isopycnal diffusion on tracers:
+ the diffusion acts along the isopycnal surfaces (neutral surface) with
+ an eddy diffusivity coefficient of 2000 m\ :sup:`2`/s.
+:Eddy induced velocity parametrization:
+ With a coefficient that depends on the growth rate of baroclinic instabilities
+ (it usually varies from 15 m\ :sup:`2`/s to 3000 m\ :sup:`2`/s).
+:lateral boundary conditions:
+ Zero fluxes of heat and salt and no-slip conditions are applied through lateral solid boundaries.
+:bottom boundary condition:
+ Zero fluxes of heat and salt are applied through the ocean bottom.
+ The Beckmann [19XX] simple bottom boundary layer parameterization is applied along
+ continental slopes.
+ A linear friction is applied on momentum.
+:convection:
+ The vertical eddy viscosity and diffusivity coefficients are increased to 1 m\ :sup:`2`/s in
+ case of static instability.
+:time step: is 5400sec (1h30') so that there is 16 time steps in one day.
+
+ORCA2_OFF_PISCES
+----------------
+
+``ORCA2_OFF_PISCES`` shares the same general offline configuration of ``ORCA2_ICE_TRC``,
+but only PISCES model is an active component of TOP.
+
+ORCA2_OFF_TRC
+-------------
+
+| ``ORCA2_OFF_TRC`` is based on the ORCA2 global ocean configuration
+ (see ORCA2_ICE_PISCES_ for general description) along with
+ the tracer passive transport module (TOP),
+ but dynamical fields are pre-calculated and read with specific time frequency.
+| This enables for an offline coupling of TOP components,
+ here specifically inorganic carbon compounds (CFC11, CFC12, SF6, C14) and water age module (age).
+ See :file:`namelist_top_cfg` to inspect the selection of
+ each component with the dedicated logical keys.
+
+Pre-calculated dynamical fields are provided to NEMO using
+the namelist ``&namdta_dyn`` in :file:`namelist_cfg`,
+in this case with a 5 days frequency (120 hours):
+
+.. literalinclude:: ../../namelists/namdta_dyn
+ :language: fortran
+
+Input dynamical fields for this configuration (:file:`ORCA2_OFF_v4.0.tar`) comes from
+a 2000 years long climatological simulation of ORCA2_ICE using ERA40 atmospheric forcing.
+
+| Note that,
+ this configuration default uses linear free surface (``ln_linssh = .true.``) assuming that
+ model mesh is not varying in time and
+ it includes the bottom boundary layer parameterization (``ln_trabbl = .true.``) that
+ requires the provision of BBL coefficients through ``sn_ubl`` and ``sn_vbl`` fields.
+| It is also possible to activate PISCES model (see ``ORCA2_OFF_PISCES``) or
+ a user defined set of tracers and source-sink terms with ``ln_my_trc = .true.``
+ (and adaptation of ``./src/TOP/MY_TRC`` routines).
+
+In addition, the offline module (OFF) allows for the provision of further fields:
+
+1. **River runoff** can be provided to TOP components by setting ``ln_dynrnf = .true.`` and
+ by including an input datastream similarly to the following:
+
+ .. code-block:: fortran
+
+ sn_rnf = 'dyna_grid_T', 120, 'sorunoff' , .true., .true., 'yearly', '', '', ''
+
+2. **VVL dynamical fields**, in the case input data were produced by a dyamical core using
+ variable volume (``ln_linssh = .false.``)
+ it is necessary to provide also diverce and E-P at before timestep by
+ including input datastreams similarly to the following
+
+ .. code-block:: fortran
+
+ sn_div = 'dyna_grid_T', 120, 'e3t' , .true., .true., 'yearly', '', '', ''
+ sn_empb = 'dyna_grid_T', 120, 'sowaflupb', .true., .true., 'yearly', '', '', ''
+
+More details can be found by inspecting the offline data manager in
+the routine :file:`./src/OFF/dtadyn.F90`.
+
+ORCA2_SAS_ICE
+-------------
+
+| ORCA2_SAS_ICE is a demonstrator of the Stand-Alone Surface (SAS) module and
+ it relies on ORCA2 global ocean configuration (see ORCA2_ICE_PISCES_ for general description).
+| The standalone surface module allows surface elements such as sea-ice, iceberg drift, and
+ surface fluxes to be run using prescribed model state fields.
+ It can profitably be used to compare different bulk formulae or
+ adjust the parameters of a given bulk formula.
+
+More informations about SAS can be found in :doc:`NEMO manual <cite>`.
+
+SPITZ12
+-------
+
+``SPITZ12`` is a regional configuration around the Svalbard archipelago
+at 1/12° of horizontal resolution and 75 vertical levels.
+See :gmd:`Rousset et al. (2015) <8/2991/2015>` for more details.
+
+This configuration references to year 2002,
+with atmospheric forcing provided every 2 hours using NCAR bulk formulae,
+while lateral boundary conditions for dynamical fields have 3 days time frequency.
+
+.. rubric:: References
+
+.. bibliography:: cfgs.bib
+ :all:
+ :style: unsrt
+ :labelprefix: C
diff --git a/doc/rst/source/changes.rst b/doc/rst/source/changes.rst
deleted file mode 120000
index a08efa15f5bd30dd1442918d4fb790c7e2e01acb..0000000000000000000000000000000000000000
--- a/doc/rst/source/changes.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../CHANGES.rst
\ No newline at end of file
diff --git a/doc/rst/source/contrib.rst b/doc/rst/source/contrib.rst
deleted file mode 120000
index ac9338fc25985403f6e26c2ed90354f71640953b..0000000000000000000000000000000000000000
--- a/doc/rst/source/contrib.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../CONTRIBUTING.rst
\ No newline at end of file
diff --git a/doc/rst/source/diags.rst b/doc/rst/source/diags.rst
deleted file mode 120000
index 97cd380f6def578f1dac63cdf5fa5252472a9b1d..0000000000000000000000000000000000000000
--- a/doc/rst/source/diags.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../cfgs/SHARED/README.rst
\ No newline at end of file
diff --git a/doc/rst/source/diags.rst b/doc/rst/source/diags.rst
new file mode 100644
index 0000000000000000000000000000000000000000..d940197c6db5ddf130b0913aa2137f939308b56b
--- /dev/null
+++ b/doc/rst/source/diags.rst
@@ -0,0 +1,119 @@
+***********
+Diagnostics
+***********
+
+.. todo::
+
+
+
+.. contents::
+ :local:
+
+Output of diagnostics in NEMO is usually done using XIOS.
+This is an efficient way of writing diagnostics because
+the time averaging, file writing and even some simple arithmetic or regridding is carried out in
+parallel to the NEMO model run.
+This page gives a basic introduction to using XIOS with NEMO.
+Much more information is available from the :xios:`XIOS homepage<>` above and from the NEMO manual.
+
+Use of XIOS for diagnostics is activated using the pre-compiler key ``key_xios``.
+
+Extracting and installing XIOS
+==============================
+
+1. Install the NetCDF4 library.
+ If you want to use single file output you will need to compile the HDF & NetCDF libraries to
+ allow parallel IO.
+2. Download the version of XIOS that you wish to use.
+ The recommended version is now XIOS 2.5:
+
+ .. code-block:: console
+
+ $ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
+
+and follow the instructions in :xios:`XIOS documentation <wiki/documentation>` to compile it.
+If you find problems at this stage, support can be found by subscribing to
+the :xios:`XIOS mailing list <../mailman/listinfo.cgi/xios-users>` and sending a mail message to it.
+
+XIOS Configuration files
+------------------------
+
+XIOS is controlled using XML input files that should be copied to
+your model run directory before running the model.
+Examples of these files can be found in the reference configurations (:file:`./cfgs`).
+The XIOS executable expects to find a file called :file:`iodef.xml` in the model run directory.
+In NEMO we have made the decision to use include statements in the :file:`iodef.xml` file to include:
+
+- :file:`field_def_nemo-oce.xml` (for physics),
+- :file:`field_def_nemo-ice.xml` (for ice),
+- :file:`field_def_nemo-pisces.xml` (for biogeochemistry) and
+- :file:`domain_def.xml` from the :file:`./cfgs/SHARED` directory.
+
+Most users will not need to modify :file:`domain_def.xml` or :file:`field_def_nemo-???.xml` unless
+they want to add new diagnostics to the NEMO code.
+The definition of the output files is organized into separate :file:`file_definition.xml` files which
+are included in the :file:`iodef.xml` file.
+
+Modes
+=====
+
+Detached Mode
+-------------
+
+In detached mode the XIOS executable is executed on separate cores from the NEMO model.
+This is the recommended method for using XIOS for realistic model runs.
+To use this mode set ``using_server`` to ``true`` at the bottom of the :file:`iodef.xml` file:
+
+.. code-block:: xml
+
+ <variable id="using_server" type="boolean">true</variable>
+
+Make sure there is a copy (or link to) your XIOS executable in the working directory and
+in your job submission script allocate processors to XIOS.
+
+Attached Mode
+-------------
+
+In attached mode XIOS runs on each of the cores used by NEMO.
+This method is less efficient than the detached mode but can be more convenient for testing or
+with small configurations.
+To activate this mode simply set ``using_server`` to false in the :file:`iodef.xml` file
+
+.. code-block:: xml
+
+ <variable id="using_server" type="boolean">false</variable>
+
+and don't allocate any cores to XIOS.
+
+.. note::
+
+ Due to the different domain decompositions between XIOS and NEMO,
+ if the total number of cores is larger than the number of grid points in the ``j`` direction then
+ the model run will fail.
+
+Adding new diagnostics
+======================
+
+If you want to add a NEMO diagnostic to the NEMO code you will need to do the following:
+
+1. Add any necessary code to calculate you new diagnostic in NEMO
+2. Send the field to XIOS using ``CALL iom_put( 'field_id', variable )`` where
+ ``field_id`` is a unique id for your new diagnostics and
+ variable is the fortran variable containing the data.
+ This should be called at every model timestep regardless of how often you want to output the field.
+ No time averaging should be done in the model code.
+3. If it is computationally expensive to calculate your new diagnostic
+ you should also use "iom_use" to determine if it is requested in the current model run.
+ For example,
+
+ .. code-block:: fortran
+
+ IF iom_use('field_id') THEN
+ !Some expensive computation
+ !...
+ !...
+ iom_put('field_id', variable)
+ ENDIF
+
+4. Add a variable definition to the :file:`field_def_nemo-???.xml` file.
+5. Add the variable to the :file:`iodef.xml` or :file:`file_definition.xml` file.
diff --git a/doc/rst/source/install.rst b/doc/rst/source/install.rst
deleted file mode 120000
index d93234ae8a1e5f7c4087872bf8fe9529744c2ebb..0000000000000000000000000000000000000000
--- a/doc/rst/source/install.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../INSTALL.rst
\ No newline at end of file
diff --git a/doc/rst/source/readme.rst b/doc/rst/source/readme.rst
deleted file mode 120000
index 428f3fb0da3d4e87fa2b4f1789f75473675c1017..0000000000000000000000000000000000000000
--- a/doc/rst/source/readme.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../README.rst
\ No newline at end of file
diff --git a/doc/rst/source/readme.rst b/doc/rst/source/readme.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7e722505b3d2842f5aab0cfa07acb6acb37d042f
--- /dev/null
+++ b/doc/rst/source/readme.rst
@@ -0,0 +1,130 @@
+**Contents**
+
+.. contents::
+ :local:
+
+
+
+
+.. _`Former web platform forge`: https://forge.ipsl.jussieu.fr/nemo
+.. _`NEMO users' guide`: https://sites.nemo-ocean.io/user-guide
+.. _`Migration Guide`: https://sites.nemo-ocean.io/user-guide/migration.html
+.. _`Change list`: https://sites.nemo-ocean.io/user-guide/changes.html
+.. _`Test case repository`: https://github.com/NEMO-ocean/NEMO-examples
+.. _`How to cite`: https://www.nemo-ocean.eu/bibliography/how-to-cite/
+.. _`NEMO forums`: https://nemo-ocean.discourse.group
+.. _`NEMO newsletter`: https://listes.ipsl.fr/sympa/subscribe/nemo-newsletter
+.. _`NEMO publications`: https://www.nemo-ocean.eu/bibliography/publications/add
+.. _`NEMO projects`: https://www.nemo-ocean.eu/projects/add
+.. _`Special Issue`: https://gmd.copernicus.org/articles/special_issue40.html
+.. _`NEMO System Team wiki`: https://forge.nemo-ocean.eu/developers/home/-/wikis/Home
+.. _`NEMO ocean engine`: https://zenodo.org/record/1464816
+.. _`NEMO Tracers engine` : https://zenodo.org/record/1471700
+.. _`NEMO Sea Ice engine`: https://zenodo.org/record/1471689
+
+
+**Welcome to NEMO home page!**
+
+NEMO (*Nucleus for European Modelling of the Ocean*) is a state-of-the-art modelling
+framework for research activities and forecasting services in ocean and climate sciences,
+developed in a sustainable way by the NEMO European consortium since 2008.
+
+This page intends to help you to get started using the NEMO platform and to introduce you
+to the different levels of information available. It starts here with NEMO release 4.2.0.
+
+Reminder: Our `Former web platform forge`_ (SVN+Trac) contains the previous documentation
+and releases made available from the beginning of the project up to of NEMO 4.0.
+
+Getting started
+===============
+
+Getting your hands on NEMO: the first steps are described in detail in the
+`NEMO users' guide`_ . This explains how to download the code, build the environment,
+create the executable, and perform a first integration.
+
+If you are already using a previous release of NEMO, please refer to the
+`Migration Guide`_ which aims to help you to make the move to 4.2.0.
+
+The above users guides cover in detail what is available from gitlab and supported by NEMO
+System Team. Aside from this web platform, a set of test cases is also available from the
+`Test case repository`_ . These test cases can be useful for students, outreach, and
+exploring specific aspects of NEMO with light configurations. The web page also allows you
+to submit test cases you have developed and want to share with the community. Feel free to
+contribute!
+
+
+Project documentation
+=====================
+
+Reference manuals fully describing NEMO for the three main component
+
+* |OCE| models the ocean {thermo}dynamics and solves the primitive equations (`./src/OCE <./src/OCE>`_)
+
+* |ICE| simulates sea-ice {thermo}dynamics, brine inclusions and subgrid-scale thickness
+ variations (`./src/ICE <./src/ICE>`_)
+
+* |MBG| models the {on,off}line oceanic tracers transport and biogeochemical processes
+ (`./src/TOP <./src/TOP>`_)
+are available from Zenodo:
+
+============ ======================== =====
+ Component Reference Manual DOI
+============ ======================== =====
+ |NEMO-OCE| `NEMO ocean engine`_ .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.6334656.svg
+ :target: https://doi.org/10.5281/zenodo.6334656
+ |NEMO-ICE| `NEMO Sea Ice engine`_ *not yet available*
+ |NEMO-MBG| `NEMO Tracers engine`_ .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471700.svg
+ :target: https://doi.org/10.5281/zenodo.1471700
+============ ======================== =====
+
+These reference manuals are the publications that should be cited in your own
+publications. Please visit `How to cite`_? for details.
+
+New features of 4.2.0 release are described in the `Change list`_ section of the `NEMO users' guide`_
+
+
+Asking questions, and exchanging information
+============================================
+- Register once for all and use the `NEMO forums`_ on discourse to share and discuss with the NEMO community.
+
+- Register once for all and receive by mail the `NEMO newsletter`_ : recommended for all
+ users to receive the major announcements from the project (new releases, open meetings and
+ main informations). Low traffic: about ten messages a year.
+
+
+Contributing to NEMO visibility: projects and publications
+==========================================================
+Please help us justifying the NEMO development efforts by
+
+- Adding your publications using NEMO and its outputs to the `NEMO publications`_ page
+
+- Describing your project using NEMO on the `NEMO projects`_ page
+
+NEMO also has a `Special Issue`_ in the open-access journal
+Geoscientific Model Development (GMD) from the European Geosciences Union
+The main scope is to collect relevant manuscripts covering various topics and
+to provide a single portal to assess the model potential and evolution.
+
+
+
+Contributing to NEMO development
+================================
+
+NEMO strives to be written in a way which allows the easy incorporation of developments.
+You are welcome to contribute to the development of the NEMO Shared reference. NEMO
+development is driven by NEMO Consortium planning and producing NEMO's sustainable
+development in order to keep a reliable evolving framework. Development is organised and
+scheduled through a five years development strategy, Working groups and the activities of
+the development team (named NEMO System Team) in a yearly workplan. More information is
+available on the `NEMO System Team wiki`_
+
+
+Disclaimer
+==========
+
+The NEMO source code is freely available and distributed under
+`CeCILL v2.0 license <./LICENSE>`_ (GNU GPL compatible).
+
+You can use, modify and/or redistribute the software under its terms,
+but users are provided only with a limited warranty and the software's authors and
+the successive licensor's have only limited liability.
diff --git a/doc/rst/source/refs.bib b/doc/rst/source/refs.bib
deleted file mode 120000
index 3bc3f4d529e2049732ae5a71f6adbbb41b540b48..0000000000000000000000000000000000000000
--- a/doc/rst/source/refs.bib
+++ /dev/null
@@ -1 +0,0 @@
-../../../REFERENCES.bib
\ No newline at end of file
diff --git a/doc/rst/source/setup.rst b/doc/rst/source/setup.rst
deleted file mode 120000
index 74a9f81dc6fd45028cf5b2514d80852b2b1ac682..0000000000000000000000000000000000000000
--- a/doc/rst/source/setup.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../src/OCE/USR/README.rst
\ No newline at end of file
diff --git a/doc/rst/source/setup.rst b/doc/rst/source/setup.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1560de3b9d847adf78543a3d7423defc426f81f4
--- /dev/null
+++ b/doc/rst/source/setup.rst
@@ -0,0 +1,283 @@
+******************************
+Setting up a new configuration
+******************************
+
+.. todo::
+
+
+
+.. contents::
+ :local:
+
+Starting from an existing configuration
+=======================================
+
+There are three options to build a new configuration from an existing one.
+
+Option 1: Duplicate an existing configuration
+---------------------------------------------
+
+The NEMO so-called Reference Configurations cover a number of major features for NEMO setup
+(global, regional, 1D, using embedded zoom with AGRIF...)
+
+One can create a new configuration by duplicating one of the reference configurations
+(``ORCA2_ICE_PISCES`` in the following example)
+
+.. code-block:: console
+
+ $ ./makenemo –n 'ORCA2_ICE_PISCES_MINE' -r 'ORCA2_ICE_PISCES' -m 'my_arch'
+
+Option 2: Duplicate with differences
+------------------------------------
+
+Create and compile a new configuration based on a reference configuration
+(``ORCA2_ICE_PISCES`` in the following example) but with different pre-processor options.
+For this either add ``add_key`` or ``del_key`` keys as required; e.g.
+
+.. code-block:: console
+
+ $ ./makenemo –n 'ORCA2_ICE_PISCES_MINE' -r 'ORCA2_ICE_PISCES' -m 'my_arch' del_key 'key_xios' add_key 'key_diahth'
+
+Option 3: Use the SIREN tools to subset an existing model
+---------------------------------------------------------
+
+Define a regional configuration which is a {sub,super}-set of an existing configuration.
+
+This last option employs the SIREN software tools that are included in the standard distribution.
+The software is written in Fortran 95 and available in the :file:`./tools/SIREN` directory.
+SIREN allows you to create your own regional configuration embedded in a wider one.
+
+SIREN is a set of programs to create all the input files you need to
+run a NEMO regional configuration.
+
+:Demo: Set of GLORYS files (GLObal ReanalYSis on the ORCA025 grid),
+ as well as examples of namelists are available `here`_.
+:Doc: :forge:`chrome/site/doc/SIREN/html/index.html`
+:Support: Any questions or comments regarding the use of SIREN should be posted in
+ :forge:`the corresponding forum <discussion/forum/2>`.
+
+.. _here: https://prodn.idris.fr/thredds/catalog/ipsl_public/rron463/catalog.html
+
+Option 4: Use the nesting tools to create embedded zooms or regional configurations from an existing grid
+---------------------------------------------------------------------------------------------------------
+(see :download:`NESTING README <../../../tools/NESTING/README>`).
+
+
+Creating a completely new configuration
+=======================================
+
+From NEMO version 4.0 there are two ways to build configurations from scratch.
+The appropriate method to use depends largely on the target configuration.
+Method 1 is for more complex/realistic global or regional configurations and
+method 2 is intended for simpler, idealised configurations whose
+domains and characteristics can be described in simple geometries and formulae.
+
+Option 1: Create and use a domain configuration file
+----------------------------------------------------
+
+This method is used by each of the reference configurations,
+so that downloading their input files linked to their description can help.
+Although starting from scratch,
+it is advisable to create the directory structure to house your new configuration by
+duplicating the closest reference configuration to your target application.
+For example, if your application requires both ocean ice and passive tracers,
+then use the ``ORCA2_ICE_PISCES`` as template,
+and execute following command to build your ``MY_NEW_CONFIG`` configuration:
+
+.. code-block:: sh
+
+ $ ./makenemo –n 'MY_NEW_CONFIG' -r 'ORCA2_ICE_PISCES' -m 'my_arch'
+
+where ``MY_NEW_CONFIG`` can be substituted with
+a suitably descriptive name for your new configuration.
+
+The purpose of this step is simply to create and populate the appropriate :file:`WORK`,
+:file:`MY_SRC` and :file:`EXP00` subdirectories for your new configuration.
+Other choices for the base reference configuration might be
+
+:GYRE: If your target application is ocean-only
+:AMM12: If your target application is regional with open boundaries
+
+All the domain information for your new configuration will be contained within
+a netcdf file called :file:`domain_cfg.nc` which you will need to create and
+place in the :file:`./cfgs/MY_NEW_CONFIG/EXP00` sub-directory.
+Firstly though, ensure that your configuration is set to use such a file by checking that
+
+.. code-block:: fortran
+
+ ln_read_cfg = .true.
+
+in :file:`./cfgs/MY_NEW_CONFIG/EXP00/namelist_cfg`
+
+Create the :file:`domain_cfg.nc` file which must contain the following fields
+
+.. code-block:: c
+
+ /* configuration name, configuration resolution */
+ int ORCA, ORCA_index
+ /* lateral global domain b.c. */
+ int Iperio, Jperio, NFoldT, NFoldF
+ /* flags for z-coord, z-coord with partial steps and s-coord */
+ int ln_zco, ln_zps, ln_sco
+ /* flag for ice shelf cavities */
+ int ln_isfcav
+ /* geographic position */
+ double glamt, glamu, glamv, glamf
+ /* geographic position */
+ double gphit, gphiu, gphiv, gphif
+ /* Coriolis parameter (if not on the sphere) */
+ double iff, ff_f, ff_t
+ /* horizontal scale factors */
+ double e1t, e1u, e1v, e1f
+ /* horizontal scale factors */
+ double e2t, e2u, e2v, e2f
+ /* U and V surfaces (if grid size reduction in some straits) */
+ double ie1e2u_v, e1e2u, e1e2v
+ /* reference vertical scale factors at T and W points */
+ double e3t_1d, e3w_1d
+ /* vertical scale factors 3D coordinate at T,U,V,F and W points */
+ double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0
+ /* vertical scale factors 3D coordinate at UW and VW points */
+ double e3uw_0, e3vw_0
+ /* last wet T-points, 1st wet T-points (for ice shelf cavities) */
+ int bottom_level, top_level
+
+There are two options for creating a :file:`domain_cfg.nc` file:
+
+- Users can use tools of their own choice to build a :file:`domain_cfg.nc` with all mandatory fields.
+- Users can adapt and apply the supplied tool available in :file:`./tools/DOMAINcfg`.
+ This tool is based on code extracted from NEMO version 3.6 and will allow similar choices for
+ the horizontal and vertical grids that were available internally to that version.
+ See :ref:`tools <DOMAINcfg>` for details.
+
+Option 2: Adapt the usr_def configuration module of NEMO for you own purposes
+-----------------------------------------------------------------------------
+
+This method is intended for configuring easily simple/idealised configurations which
+are often used as demonstrators or for process evaluation and comparison.
+This method can be used whenever the domain geometry has a simple mathematical description and
+the ocean initial state and boundary forcing is described analytically.
+As a start, consider the case of starting a completely new ocean-only test case based on
+the ``LOCK_EXCHANGE`` example.
+
+.. note::
+
+ We probably need an even more basic example than this with only one namelist and
+ minimal changes to the usrdef modules
+
+Firstly, construct the directory structure, starting in the :file:`cfgs` directory:
+
+.. code-block:: console
+
+ $ ./makenemo -n 'MY_NEW_TEST' -t 'LOCK_EXCHANGE' -m 'my_arch'
+
+where the ``-t`` option has been used to locate the new configuration in
+the :file:`tests` subdirectory
+(it is recommended practice to keep full configurations and idealised cases clearly distinguishable).
+This command will create (amongst others) the following files and directories::
+
+ ./tests/MY_NEW_TEST:
+ BLD EXP00 MY_SRC WORK cpp_MY_NEW_TEST.fcm
+
+ ./tests/MY_NEW_TEST/EXP00:
+ context_nemo.xml domain_def_nemo.xml field_def_nemo-oce.xml file_def_nemo-oce.xml iodef.xml
+ namelist_cfg namelist_ref
+
+ ./tests/MY_NEW_TEST/MY_SRC:
+ usrdef_hgr.F90 usrdef_nam.F90 usrdef_zgr.F90 usrdef_istate.F90 usrdef_sbc.F90 zdfini.F90
+
+The key to setting up an idealised configuration lies in
+adapting a small set of short Fortran 90 modules which
+should be dropped into the :file:`MY_SRC` directory.
+Here the ``LOCK_EXCHANGE`` example is using 5 such routines but the full set that is available in
+the :file:`src/OCE/USR` directory is::
+
+ ./src/OCE/USR:
+ usrdef_closea.F90 usrdef_fmask.F90 usrdef_hgr.F90 usrdef_istate.F90
+ usrdef_nam.F90 usrdef_sbc.F90 usrdef_zgr.F90
+
+Before discussing these in more detail it is worth noting the various namelist controls that
+engage the different user-defined aspects.
+These controls are set using two new logical switches or are implied by the settings of existing ones.
+For example, the mandatory requirement for an idealised configuration is to provide routines which
+define the horizontal and vertical domains.
+Templates for these are provided in the :file:`usrdef_hgr.F90` and :file:`usrdef_zgr.F90` modules.
+The application of these modules is activated whenever:
+
+.. code-block:: fortran
+
+ ln_read_cfg = .false.
+
+in any configuration's :file:`namelist_cfg` file.
+This setting also activates the reading of an optional ``&nam_usrdef`` namelist which can be used to
+supply configuration specific settings.
+These need to be declared and read in the :file:`usrdef_nam.F90` module.
+
+Another explicit control is available in the ``&namsbc`` namelist which
+activates the use of analytical forcing.
+With
+
+.. code-block:: fortran
+
+ ln_usr = .true.
+
+Other usrdef modules are activated by less explicit means.
+For example, code in :file:`usrdef_istate.F90` is used to
+define initial temperature and salinity fields if
+
+.. code-block:: fortran
+
+ ln_tsd_init = .false.
+
+in the ``&namtsd`` namelist.
+The remaining modules, namely :file:`usrdef_closea.F90` :file:`usrdef_fmask.F90` are specific to
+ORCA configurations and set local variations of some specific fields for
+the various resolutions of the global models.
+They do not need to be considered here in the context of idealised cases but
+it is worth noting that all configuration specific code has now been isolated in the usrdef modules.
+In the case of these last two modules, they are activated only if an ORCA configuration is detected.
+Currently,
+this requires a specific integer variable named ``ORCA`` to be set in a :file:`domain_cfg.nc` file.
+
+.. note::
+
+ This would be less confusing if the ``cn_cfg`` string is read directly as
+ a character attribue from the :file:`domain_cfg.nc`.
+
+So, in most cases, the set up of idealised model configurations can be completed by
+copying the template routines from :file:`./src/OCE/USR` into
+your new :file:`./cfgs/MY_NEW_TEST/MY_SRC` directory and
+editing the appropriate modules as needed.
+The default set are those used for the GYRE reference configuration.
+The contents of :file:`MY_SRC` directories from other idealised configurations may provide
+more convenient templates if they share common characteristics with your target application.
+
+Whatever the starting point,
+it should not require too many changes or additional lines of code to produce routines in
+:file:`./src/OCE/USR` that define analytically the domain,
+the initial state and the surface boundary conditions for your new configuration.
+
+To summarize, the base set of modules is:
+
+:usrdef_hgr.F90: Define horizontal grid
+:usrdef_zgr.F90: Define vertical grid
+:usrdef_sbc.F90: Provides at each time-step the surface boundary condition,
+ i.e. the momentum, heat and freshwater fluxes
+:usrdef_istate.F90: Defines initialization of the dynamics and tracers
+:usrdef_nam.F90: Configuration-specific namelist processing to
+ set any associated run-time parameters
+
+with two specialised ORCA modules
+(not related to idealised configurations but used to isolate configuration specific code that
+is used in ORCA2 reference configurations and established global configurations using
+the ORCA tripolar grid):
+
+:usrdef_fmask.F90: only used in ORCA configurations for
+ alteration of f-point land/ocean mask in some straits
+:usrdef_closea.F90: only used in ORCA configurations for
+ specific treatments associated with closed seas
+
+From version 4.0, the NEMO release includes a :file:`tests` subdirectory containing available and
+up to date :doc:`test cases <tests>` build by the community.
+These will not be fully supported as are NEMO reference configurations,
+but should provide a source of raw material.
diff --git a/doc/rst/source/tests.bib b/doc/rst/source/tests.bib
deleted file mode 120000
index c999a7213204d25d457414a5bc715a7728211420..0000000000000000000000000000000000000000
--- a/doc/rst/source/tests.bib
+++ /dev/null
@@ -1 +0,0 @@
-../../../tests/test_cases.bib
\ No newline at end of file
diff --git a/doc/rst/source/tests.bib b/doc/rst/source/tests.bib
new file mode 100644
index 0000000000000000000000000000000000000000..7b9856e8bf762dc9f27d41ab9846de1a70c6db00
--- /dev/null
+++ b/doc/rst/source/tests.bib
@@ -0,0 +1,115 @@
+
+@article{ brodeau.barnier.ea_JPO16,
+ title = "Climatologically Significant Effects of Some
+ Approximations in the Bulk Parameterizations of Turbulent
+ Air–Sea Fluxes",
+ pages = "5--28",
+ journal = "Journal of Physical Oceanography",
+ volume = "47",
+ number = "1",
+ author = "Brodeau, Laurent and Barnier, Bernard and Gulev, Sergey K.
+ and Woods, Cian",
+ year = "2016",
+ month = "Dec",
+ publisher = "American Meteorological Society",
+ issn = "1520-0485",
+ doi = "10.1175/jpo-d-16-0169.1"
+}
+
+@techreport{ burchard.bolding_trpt02,
+ title = "GETM, A General Estuarine Transport Model: Scientific
+ Documentation",
+ pages = "",
+ series = "Tech. Rep. EUR 20253 EN",
+ author = "Burchard, Hans and Bolding, Karsten",
+ institution = "European Commission",
+ year = "2002",
+ month = "01"
+}
+
+@article{ haidvogel.beckmann_SESM99,
+ title = "Numerical Ocean Circulation Modeling",
+ journal = "Series on Environmental Science and Management",
+ author = "Haidvogel, Dale B and Beckmann, Aike",
+ year = "1999",
+ month = "Apr",
+ publisher = "IMPERIAL COLLEGE PRESS",
+ issn = "0219-9793",
+ isbn = "9781860943935",
+ doi = "10.1142/p097"
+}
+
+@article{ ilıcak.adcroft.ea_OM12,
+ title = "Spurious dianeutral mixing and the role of momentum
+ closure",
+ pages = "37--58",
+ journal = "Ocean Modelling",
+ volume = "45-46",
+ author = "Ilıcak, Mehmet and Adcroft, Alistair J. and Griffies,
+ Stephen M. and Hallberg, Robert W.",
+ year = "2012",
+ month = "Jan",
+ publisher = "Elsevier BV",
+ issn = "1463-5003",
+ doi = "10.1016/j.ocemod.2011.10.003"
+}
+
+@article{ lipscomb.hunke_MWR04,
+ title = "Modeling Sea Ice Transport Using Incremental Remapping",
+ pages = "1341--1354",
+ journal = "Monthly Weather Review",
+ volume = "132",
+ number = "6",
+ author = "Lipscomb, William H. and Hunke, Elizabeth C.",
+ year = "2004",
+ month = "Jun",
+ publisher = "American Meteorological Society",
+ issn = "1520-0493",
+ doi = "10.1175/1520-0493(2004)132<1341:msitui>2.0.co;2"
+}
+
+@article{ losch_JGR08,
+ title = "Modeling ice shelf cavities in a z coordinate ocean
+ general circulation model",
+ journal = "Journal of Geophysical Research",
+ volume = "113",
+ number = "C8",
+ author = "Losch, M.",
+ year = "2008",
+ month = "Aug",
+ publisher = "American Geophysical Union (AGU)",
+ issn = "0148-0227",
+ doi = "10.1029/2007jc004368"
+}
+
+@article{ mathiot.jenkins.ea_GMD17,
+ title = "Explicit representation and parametrised impacts of under
+ ice shelf seas in the ${z}^{\ast}$ coordinate ocean model
+ NEMO 3.6",
+ pages = "2849--2874",
+ journal = "Geoscientific Model Development",
+ volume = "10",
+ number = "7",
+ author = "Mathiot, Pierre and Jenkins, Adrian and Harris,
+ Christopher and Madec, Gurvan",
+ year = "2017",
+ month = "Jul",
+ publisher = "Copernicus GmbH",
+ issn = "1991-9603",
+ doi = "10.5194/gmd-10-2849-2017"
+}
+
+@article{ schär.smolarkiewicz_JCP96,
+ title = "A Synchronous and Iterative Flux-Correction Formalism for
+ Coupled Transport Equations",
+ pages = "101--120",
+ journal = "Journal of Computational Physics",
+ volume = "128",
+ number = "1",
+ author = "Schär, Christoph and Smolarkiewicz, Piotr K.",
+ year = "1996",
+ month = "Oct",
+ publisher = "Elsevier BV",
+ issn = "0021-9991",
+ doi = "10.1006/jcph.1996.0198"
+}
diff --git a/doc/rst/source/tests.rst b/doc/rst/source/tests.rst
deleted file mode 120000
index 713be7cf8f5dbfddd82e573ece529d92ab4917d0..0000000000000000000000000000000000000000
--- a/doc/rst/source/tests.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../tests/README.rst
\ No newline at end of file
diff --git a/doc/rst/source/tests.rst b/doc/rst/source/tests.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2b946dc1d58d65778830b7f30d5faa7b610d6120
--- /dev/null
+++ b/doc/rst/source/tests.rst
@@ -0,0 +1,272 @@
+**********************
+Explore the test cases
+**********************
+
+.. todo::
+
+ CANAL animated gif is missing
+
+.. contents::
+ :local:
+ :depth: 1
+
+Installation
+============
+
+Download
+--------
+
+| The complete and up-to-date set of test cases is available on
+ :github:`NEMO test cases repository <NEMO-examples>`.
+| Download it directly into the :file:`./tests` root directory with
+
+.. code-block:: console
+
+ $ git clone http://github.com/NEMO-ocean/NEMO-examples
+
+Compilation
+-----------
+
+The compilation of the test cases is very similar to
+the manner the reference configurations are compiled.
+If you are not familiar on how to compile NEMO,
+it is first recomended to read :doc:`the instructions <install>`.
+
+| As the reference configurations are compiled with ``-r`` option,
+ test cases can be compiled by the use of :file:`makenemo` with ``-a`` option.
+| Here an example to compile a copy named WAD2 of the wetting and drying test case (WAD):
+
+.. code-block:: console
+
+ $ ./makenemo -n 'WAD2' -a 'WAD' -m 'my_arch' -j '4'
+
+Run and analysis
+----------------
+
+There no requirement of specific input file for the test_cases presented here.
+The XIOS xml input files and namelist are already setup correctly.
+For detailed description and Jupyter notebook, the reader is directed on
+the :github:`NEMO test cases repository <NEMO-examples>`
+
+The description below is a brief advertisement of some test cases.
+
+List of test cases
+==================
+
+ICE_AGRIF
+---------
+
+.. figure:: _static/ICE_AGRIF_UDIAG_43days_UM5.gif
+ :width: 200px
+ :align: left
+
+ ..
+
+| This test case illustrates the advection of an ice patch across
+ an East/West and North/South periodic channel over a slab ocean (i.e. one ocean layer),
+ and with an AGRIF zoom (1:3) in the center.
+| The purpose of this configuration is to
+ test the advection of the ice patch in and across the AGRIF boundary.
+ One can either impose ice velocities or ice-atm.
+ Stresses and let rheology define velocities (see :file:`README` for details)
+
+VORTEX
+------
+
+.. figure:: _static/VORTEX_anim.gif
+ :width: 200px
+ :align: right
+
+ ..
+
+This test case illustrates the propagation of an anticyclonic eddy over a Beta plan and a flat bottom.
+It is implemented here with an online refined subdomain (1:3) out of which the vortex propagates.
+It serves as a benchmark for quantitative estimates of nesting errors as in :cite:`DEBREU2012`,
+:cite:`PENVEN2006` or :cite:`SPALL1991`.
+
+The animation (sea level anomaly in meters) illustrates with
+two 1:2 successively nested grids how the vortex smoothly propagates out of the refined grids.
+
+ISOMIP
+------
+
+.. figure:: _static/ISOMIP_moc.png
+ :width: 200px
+ :align: left
+
+ ..
+
+| The purpose of this test case is to evaluate the impact of various schemes and new development with
+ the iceshelf cavities circulation and melt.
+ This configuration served as initial assesment of the ice shelf module in :cite:`LOSCH2008` and
+ :cite:`MATHIOT2017`.
+ The default setup is the one described |ISOMIP|_.
+| The figure (meridional overturning circulation) illustrates
+ the circulation generated after 10000 days by the ice shelf melting (ice pump).
+
+.. |ISOMIP| replace:: here
+
+LOCK_EXCHANGE
+-------------
+
+.. figure:: _static/LOCK-FCT4_flux_ubs.gif
+ :width: 200px
+ :align: right
+
+ ..
+
+| The LOCK EXCHANGE experiment is a classical fluid dynamics experiment that has been adapted
+ by :cite:`HAIDVOGEL1999` for testing advection schemes in ocean circulation models.
+ It has been used by several authors including :cite:`BURCHARD2002` and :cite:`ILICAK2012`.
+ The LOCK EXCHANGE experiment can in particular illustrate
+ the impact of different choices of numerical schemes and/or subgrid closures on
+ spurious interior mixing.
+| Here the animation of the LOCK_EXCHANGE test case using
+ the advection scheme FCT4 (forth order) for tracer and ubs for dynamics.
+
+OVERFLOW
+--------
+
+.. figure:: _static/OVF-sco_FCT4_flux_cen-ahm1000.gif
+ :width: 200px
+ :align: left
+
+ ..
+
+| The OVERFLOW experiment illustrates the impact of different choices of numerical schemes and/or
+ subgrid closures on spurious interior mixing close to bottom topography.
+ The OVERFLOW experiment is adapted from the non-rotating overflow configuration described in
+ :cite:`HAIDVOGEL1999` and further used by :cite:`ILICAK2012`.
+ Here we can assess the behaviour of the second-order tracer advection scheme FCT2 and
+ forth-order FCT4, z-coordinate and sigma coordinate (...).
+| Here the animation of the OVERFLOW test case in sigma coordinate with
+ the forth-order advection scheme FCT4.
+
+WAD
+---
+
+.. figure:: _static/wad_testcase_7.gif
+ :width: 200px
+ :align: right
+
+ ..
+
+| A set of simple closed basin geometries for testing the Wetting and drying capabilities.
+ Examples range from a closed channel with EW linear bottom slope to
+ a parabolic EW channel with a Gaussian ridge.
+| Here the animation of the test case 7.
+ This test case is a simple linear slope with a mid-depth shelf with
+ an open boundary forced with a sinusoidally varying ssh.
+ This test case has been introduced to emulate a typical coastal application with
+ a tidally forced open boundary with an adverse SSH gradient that,
+ when released, creates a surge up the slope.
+ The parameters are chosen such that
+ the surge rises above sea-level before falling back and oscillating towards an equilibrium position.
+
+CANAL
+-----
+
+.. figure:: _static/CANAL_image.gif
+ :width: 200px
+ :align: left
+
+ ..
+
+East-west periodic canal of variable size with several initial states and
+associated geostrophic currents (zonal jets or vortex).
+
+ICE_ADV2D
+---------
+
+| This test case illustrates the advection of an ice patch across
+ an East/West and North/South periodic channel over a slab ocean (i.e. one ocean layer).
+ The configuration is similar to ICE_AGRIF, except for the AGRIF zoom.
+| The purpose of this configuration is to test the advection schemes available in the sea-ice code
+ (for now, Prather and Ultimate-Macho from 1st to 5th order),
+ especially the occurence of overshoots in ice thickness
+
+ICE_ADV1D
+---------
+
+| This experiment is the classical :cite:`SCHAR1996` test case ,
+ which has been used in :cite:`LIPSCOMB2004`, and in which very specific shapes of ice concentration,
+ thickness and volume converge toward the center of a basin.
+ Convergence is unidirectional (in x) while fields are homogeneous in y.
+| The purpose of this configuration is to
+ test the caracteristics of advection schemes available in the sea-ice code
+ (for now, Prather and Ultimate-Macho from 1st to 5th order),
+ especially the constitency between concentration, thickness and volume,
+ and the preservation of initial shapes.
+
+.. rubric:: References
+
+.. bibliography:: tests.bib
+ :all:
+ :style: unsrt
+ :labelprefix: T
+
+ICE_RHEO
+--------
+|
+
+BENCH
+-----
+| Benchmark configuration. Allow to run any configuration (including ORCA type or BDY) with idealized grid
+ and initial state so it does not need any input file other than the namelists.
+ As usual, all configuration changes can be done through the namelist.
+ We provide 3 example of namelist_cfg to mimic ORCA1, OR025 or ORCA12 configurations.
+ By default do not produce any output file. An extensive description of BENCH will be abailable in
+ Irrmann et al. 2021.
+
+CPL_OASIS
+---------
+| This test case checks the OASIS interface in OCE/SBC, allowing to set up
+ a coupled configuration through OASIS. See CPL_OASIS/README.md for more information.
+
+DIA_GPU
+---------
+| This is a demonstrator of diagnostic DIAHSB ported to GPU using CUDA Fortran.
+ Memory communications between host and device are asynchronous given the device has that capability.
+ This experiment is target for ORCA2_ICE_PISCES
+
+TSUNAMI
+---------
+| just use dynspg_ts to simulate the propagation of an ssh anomaly (cosinus) in a box configuration
+ with flat bottom and jpk=2.
+
+DONUT
+-----
+| Donut shaped configuration to test MPI decomposition with bdy.
+
+C1D_ASICS
+---------
+|
+
+DOME
+----
+|
+
+ICB
+----
+| ICB is a very idealized configuration used to test and debug the icb module.
+ The configuration is box with a shallow shelf (40m) on the east and west part of the domain
+ with a deep central trough (> 100m).
+ ICB are generating using the test capability of the icb model along a E-W line (this can easily be tuned).
+
+STATION_ASF
+-----------
+| this demonstration test case can be used to perform a sanity test of the SBCBLK interface of
+ NEMO. It will test all the bulk-parameterization algorithms using an idealized
+ forcing that includes a wide range of *SSX / surface atmospheric state*
+ conditions to detect potential error / inconsistencies. Both a short report and
+ boolean output: *passed* or *failed* is provided as an output.
+
+SWG
+---
+| Square bassin blown with an analytical wind. Vertical structure allows only one mode
+ associated with reduced gravity to develop. This configuration is based on Adcroft & Marshall 1998.
+ Also run with RK3 time stepping.
+
+ADIAB_WAVE
+----------
+| The purpose of this test case is to validate the implementation of the Generalized Lagrangian Mean equations for the coupling of NEMO with waves. This test case was first proposed by Ardhuin et al. (2008) and was successively detailed by Bennis et al (2011).
diff --git a/doc/rst/source/tools.rst b/doc/rst/source/tools.rst
deleted file mode 120000
index 8547472c4740fdd0da52521231949d4b046a40c1..0000000000000000000000000000000000000000
--- a/doc/rst/source/tools.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../tools/README.rst
\ No newline at end of file
diff --git a/doc/rst/source/tools.rst b/doc/rst/source/tools.rst
new file mode 100644
index 0000000000000000000000000000000000000000..703a0d688306381c8ee22287f4f2e705924589a2
--- /dev/null
+++ b/doc/rst/source/tools.rst
@@ -0,0 +1,141 @@
+*****
+Tools
+*****
+
+.. todo::
+
+ The 'Tools' chapter needs to be enriched
+
+.. contents::
+ :local:
+ :depth: 1
+
+A set of tools is provided with NEMO to setup user own configuration and (pre|post)process data.
+
+How to compile a tool
+=====================
+
+The tool can be compiled using the maketools script in the tools directory as follows:
+
+.. code-block:: console
+
+ $ ./maketools -m 'my_arch' -n '<TOOL_NAME>'
+
+where ``my_arch`` can be selected among available architecture files or providing a user defined one.
+
+List of tools
+=============
+
+BDY_TOOLS
+---------
+
+It contains the utility *bdy_reorder* used to reorder old BDY data files used with
+previous versions of the model (before 3.4) to make them compatible with NEMO 3.4.
+
+DMP_TOOLS
+---------
+
+Used to create a netcdf file called :file:`resto.nc` containing
+restoration coefficients for use with the :file:`tra_dmp` module in NEMO
+(see :download:`DMP_TOOLS README <../../../tools/DMP_TOOLS/README>`).
+
+DOMAINcfg
+---------
+A toolbox allowing the creation of regional configurations from curvilinear grid
+(see :download:`DOMAINcfg README <../../../tools/DOMAINcfg/README.rst>`).
+
+GRIDGEN
+-------
+This tool allows the creation of a domain configuration file (``domain_cfg.nc``) containing
+the ocean domain information required to define an ocean configuration from scratch.
+(see :download:`GRIDGEN documentation <../../../tools/GRIDGEN/doc_cfg_tools.pdf>`).
+
+MISCELLANEOUS
+-------------
+
+The tool allows to create alternative configurations to the community without
+having to rely on system team sponsorship and support.
+
+MPP_PREP
+--------
+
+This tool provides the user with information to choose the best domain decomposition.
+The tool computes the number of water processors for all possible decompositions,
+up to a maximum number of processors
+(see :download:`MPP_PREP documentation <../../../tools/MPP_PREP/mpp_nc.pdf>` and
+:download:`MPP_PREP archive <../../../tools/MPP_PREP/mpp_prep-1.0.tar.gz>`).
+
+NESTING
+-------
+
+AGRIF nesting tool allows for the seamless two-way coupling of nested sub-models within
+the NEMO framework as long as these are defined on subsets of the original root grid.
+It allows to create the grid coordinates, the surface forcing and the initial conditions required by
+each sub-model when running a NEMO/AGRIF embedded mode
+(see :download:`NESTING README <../../../tools/NESTING/README>`).
+
+OBSTOOLS
+--------
+
+A series of Fortran utilities which are helpful in handling observation files and
+the feedback file output from the NEMO observation operator.
+Further info are available in the :doc:`Nemo manual <cite>`.
+
+REBUILD_NEMO
+------------
+
+REBUILD_NEMO is a tool to rebuild NEMO output files from multiple processors
+(mesh_mask, restart or XIOS output files) into one file
+(see :download:`REBUILD_NEMO README <../../../tools/REBUILD_NEMO/README.rst>`).
+
+REBUILD
+-------
+
+It contains the old version of REBUILD_NEMO tool based on the IOIPSL code.
+
+SCOORD_GEN
+----------
+
+Offline tool to generate a vertical coordinates input file for use with S coordinates.
+This has been carried out by copying the model code to an offline tool and then
+modifying it to suppress the use of 3D arrays (to reduce memory usage).
+The tool has been created in preparation for the removal of the vertical grid definition from
+the code.
+The output file should contain all variables that are necessary to restart the model.
+
+SECTIONS_DIADCT
+---------------
+
+When the Transport across sections diagnostic is activated (``key_diadct``),
+this tool is used to build the binary file containing the pathways between
+the extremities of each section.
+Further info are available in the :doc:`Nemo manual <cite>`.
+
+SIREN
+-----
+
+SIREN is a configuration management tool to set up regional configurations with NEMO
+(see :download:`SIREN README <../../../tools/SIREN/README>`).
+
+WEIGHTS
+-------
+
+This directory contains software for generating and manipulating interpolation weights for use with
+the Interpolation On the Fly (IOF) option in NEMO v3 onwards
+(see :download:`WEIGHTS README <../../../tools/WEIGHTS/README>`).
+
+TOYATM
+------
+
+This directory contains a simplified model that send/receive atmospheric fields to/from NEMO, for use in the CPL_OASIS sed to test case of the NEMO-OASIS coupling interface.
+This toy requires OASIS3-MCT to be installed and properly defined in the arch file.
+(see :download:`CPL_OASIS README <../../../tests/CPL_OASIS/README.md>`).
+
+ABL_TOOLS
+---------
+
+3 steps to generate atmospheric forcings from ECMWF products for ABL1d model with NEMO:
+- main_uvg_hpg (optional): geostrophic wind or horizontal pressure gradient computation on ECMWF eta-levels (to force ABL dynamics)
+- main_vinterp: vertical interpolation from ECWMF vertical eta-levels to ABL Z-levels
+- main_hdrown: 3D-fields horizontal drowning (extrapolation over land totally inspired from SOSIE by L. Brodeau)
+(more details available in Lemarie et al. 2020 GMD)
diff --git a/doc/rst/source/tracers.rst b/doc/rst/source/tracers.rst
deleted file mode 120000
index 9660d44122a140bc516d8d58bcd1c62630e653ec..0000000000000000000000000000000000000000
--- a/doc/rst/source/tracers.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../src/TOP/README.rst
\ No newline at end of file
diff --git a/doc/rst/source/tracers.rst b/doc/rst/source/tracers.rst
new file mode 100644
index 0000000000000000000000000000000000000000..65b1ac39dcb338fcb7e90b90dbbd9774ca838da6
--- /dev/null
+++ b/doc/rst/source/tracers.rst
@@ -0,0 +1,392 @@
+***************
+Oceanic tracers
+***************
+
+.. todo::
+
+
+
+.. contents::
+ :local:
+
+TOP (Tracers in the Ocean Paradigm) is the NEMO hardwired interface toward
+biogeochemical models and provide the physical constraints/boundaries for oceanic tracers.
+It consists of a modular framework to handle multiple ocean tracers,
+including also a variety of built-in modules.
+
+This component of the NEMO framework allows one to exploit available modules (see below) and
+further develop a range of applications, spanning from the implementation of a dye passive tracer to
+evaluate dispersion processes (by means of MY_TRC), track water masses age (AGE module),
+assess the ocean interior penetration of persistent chemical compounds
+(e.g., gases like CFC or even PCBs), up to the full set of equations involving
+marine biogeochemical cycles.
+
+Structure
+=========
+
+TOP interface has the following location in the source code :file:`./src/TOP` and
+the following modules are available:
+
+:file:`TRP`
+ Interface to NEMO physical core for computing tracers transport
+
+:file:`CFC`
+ Inert carbon tracers (CFC11,CFC12,SF6)
+
+:file:`C14`
+ Radiocarbon passive tracer
+
+:file:`AGE`
+ Water age tracking
+
+:file:`MY_TRC`
+ Template for creation of new modules and external BGC models coupling
+
+:file:`PISCES`
+ Built in BGC model. See :cite:`gmd-8-2465-2015` for a throughout description.
+
+The usage of TOP is activated
+*i)* by including in the configuration definition the component ``TOP`` and
+*ii)* by adding the macro ``key_top`` in the configuration CPP file
+(see for more details :forge:`"Learn more about the model" <wiki/Users>`).
+
+As an example, the user can refer to already available configurations in the code,
+``GYRE_PISCES`` being the NEMO biogeochemical demonstrator and
+``GYRE_BFM`` to see the required configuration elements to couple with an external biogeochemical model
+(see also Section 4) .
+
+Note that, since version 4.0,
+TOP interface core functionalities are activated by means of logical keys and
+all submodules preprocessing macros from previous versions were removed.
+
+Here below the list of preprocessing keys that applies to the TOP interface (beside ``key_top``):
+
+``key_xios``
+ use XIOS I/O
+
+``key_agrif``
+ enable AGRIF coupling
+
+``key_trdtrc`` & ``key_trdmxl_trc``
+ trend computation for tracers
+
+Synthetic Workflow
+==================
+
+A synthetic description of the TOP interface workflow is given below to
+summarize the steps involved in the computation of biogeochemical and physical trends and
+their time integration and outputs,
+by reporting also the principal Fortran subroutine herein involved.
+
+Model initialization (:file:`./src/OCE/nemogcm.F90`)
+----------------------------------------------------
+
+Call to ``trc_init`` subroutine (:file:`./src/TOP/trcini.F90`) to initialize TOP.
+
+.. literalinclude:: ../../../src/TOP/trcini.F90
+ :language: fortran
+ :lines: 41-86
+ :emphasize-lines: 21,30-32,38-40
+ :caption: ``trc_init`` subroutine
+
+Time marching procedure (:file:`./src/OCE/step.F90`)
+----------------------------------------------------
+
+Call to ``trc_stp`` subroutine (:file:`./src/TOP/trcstp.F90`) to compute/update passive tracers.
+
+.. literalinclude:: ../../../src/TOP/trcstp.F90
+ :language: fortran
+ :lines: 46-125
+ :emphasize-lines: 42,55-57
+ :caption: ``trc_stp`` subroutine
+
+BGC trends computation for each submodule (:file:`./src/TOP/trcsms.F90`)
+------------------------------------------------------------------------
+
+.. literalinclude:: ../../../src/TOP/trcsms.F90
+ :language: fortran
+ :lines: 21
+ :caption: :file:`trcsms` snippet
+
+Physical trends computation (:file:`./src/TOP/TRP/trctrp.F90`)
+--------------------------------------------------------------
+
+.. literalinclude:: ../../../src/TOP/TRP/trctrp.F90
+ :language: fortran
+ :lines: 46-95
+ :emphasize-lines: 17,21,29,33-35
+ :caption: ``trc_trp`` subroutine
+
+Namelists walkthrough
+=====================
+
+:file:`namelist_top`
+--------------------
+
+Here below are listed the features/options of the TOP interface accessible through
+the :file:`namelist_top_ref` and modifiable by means of :file:`namelist_top_cfg`
+(as for NEMO physical ones).
+
+Note that ``##`` is used to refer to a number in an array field.
+
+.. literalinclude:: ../../namelists/namtrc_run
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_dta
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_adv
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_ldf
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_rad
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_snk
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_dmp
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_ice
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_trd
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_bc
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_bdy
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namage
+ :language: fortran
+
+Two main types of data structure are used within TOP interface
+to initialize tracer properties (1) and
+to provide related initial and boundary conditions (2).
+
+1. TOP tracers initialization: ``sn_tracer`` (``&namtrc``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Beside providing name and metadata for tracers,
+here are also defined the use of initial (``sn_tracer%llinit``) and
+boundary (``sn_tracer%llsbc, sn_tracer%llcbc, sn_tracer%llobc``) conditions.
+
+In the following, an example of the full structure definition is given for
+two idealized tracers both with initial conditions given,
+while the first has only surface boundary forcing and
+the second both surface and coastal forcings:
+
+.. code-block:: fortran
+
+ ! ! name ! title of the field ! units ! initial data ! sbc ! cbc ! obc !
+ sn_tracer(1) = 'TRC1' , 'Tracer 1 Concentration ', ' - ' , .true. , .true., .false., .true.
+ sn_tracer(2) = 'TRC2 ' , 'Tracer 2 Concentration ', ' - ' , .true. , .true., .true. , .false.
+
+As tracers in BGC models are increasingly growing,
+the same structure can be written also in a more compact and readable way:
+
+.. code-block:: fortran
+
+ ! ! name ! title of the field ! units ! initial data !
+ sn_tracer(1) = 'TRC1' , 'Tracer 1 Concentration ', ' - ' , .true.
+ sn_tracer(2) = 'TRC2 ' , 'Tracer 2 Concentration ', ' - ' , .true.
+ ! sbc
+ sn_tracer(1)%llsbc = .true.
+ sn_tracer(2)%llsbc = .true.
+ ! cbc
+ sn_tracer(2)%llcbc = .true.
+
+The data structure is internally initialized by code with dummy names and
+all initialization/forcing logical fields set to ``.false.`` .
+
+2. Structures to read input initial and boundary conditions: ``&namtrc_dta`` (``sn_trcdta``), ``&namtrc_bc`` (``sn_trcsbc`` / ``sn_trccbc`` / ``sn_trcobc``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The overall data structure (Fortran type) is based on the general one defined for NEMO core in the SBC component
+(see details in ``SBC`` Chapter of :doc:`Reference Manual <cite>` on Input Data specification).
+
+Input fields are prescribed within ``&namtrc_dta`` (with ``sn_trcdta`` structure),
+while Boundary Conditions are applied to the model by means of ``&namtrc_bc``,
+with dedicated structure fields for surface (``sn_trcsbc``), riverine (``sn_trccbc``), and
+lateral open (``sn_trcobc``) boundaries.
+
+The following example illustrates the data structure in the case of initial condition for
+a single tracer contained in the file named :file:`tracer_1_data.nc`
+(``.nc`` is implicitly assumed in namelist filename),
+with a doubled initial value, and located in the :file:`usr/work/model/inputdata` folder:
+
+.. code-block:: fortran
+
+ ! ! file name ! frequency (hours) ! variable ! time interp. ! clim ! 'yearly'/ ! weights ! rotation ! land/sea mask !
+ ! ! ! (if <0 months) ! name ! (logical) ! (T/F) ! 'monthly' ! filename ! pairing ! filename !
+ sn_trcdta(1) = 'tracer_1_data' , -12 , 'TRC1' , .false. , .true. , 'yearly' , '' , '' , ''
+ rf_trfac(1) = 2.0
+ cn_dir = 'usr/work/model/inputdata/'
+
+Note that, the Lateral Open Boundaries conditions are applied on
+the segments defined for the physical core of NEMO
+(see ``BDY`` description in the :doc:`Reference Manual <cite>`).
+
+:file:`namelist_trc`
+--------------------
+
+Here below the description of :file:`namelist_trc_ref` used to handle Carbon tracers modules,
+namely CFC and C14.
+
+.. literalinclude:: ../../../cfgs/SHARED/namelist_trc_ref
+ :language: fortran
+ :lines: 7,17,26,34
+ :caption: :file:`namelist_trc_ref` snippet
+
+``MY_TRC`` interface for coupling external BGC models
+=====================================================
+
+The generalized interface is pivoted on MY_TRC module that contains template files to
+build the coupling between
+NEMO and any external BGC model.
+
+The call to MY_TRC is activated by setting ``ln_my_trc = .true.`` (in ``&namtrc``)
+
+The following 6 fortran files are available in MY_TRC with the specific purposes here described.
+
+:file:`par_my_trc.F90`
+ This module allows to define additional arrays and public variables to
+ be used within the MY_TRC interface
+
+:file:`trcini_my_trc.F90`
+ Here are initialized user defined namelists and
+ the call to the external BGC model initialization procedures to populate general tracer array
+ (``trn`` and ``trb``).
+ Here are also likely to be defined support arrays related to system metrics that
+ could be needed by the BGC model.
+
+:file:`trcnam_my_trc.F90`
+ This routine is called at the beginning of ``trcini_my_trc`` and
+ should contain the initialization of additional namelists for the BGC model or user-defined code.
+
+:file:`trcsms_my_trc.F90`
+ The routine performs the call to Boundary Conditions and its main purpose is to
+ contain the Source-Minus-Sinks terms due to the biogeochemical processes of the external model.
+ Be aware that lateral boundary conditions are applied in trcnxt routine.
+
+ .. warning::
+ The routines to compute the light penetration along the water column and
+ the tracer vertical sinking should be defined/called in here,
+ as generalized modules are still missing in the code.
+
+:file:`trcice_my_trc.F90`
+ Here it is possible to prescribe the tracers concentrations in the sea-ice that
+ will be used as boundary conditions when ice melting occurs (``nn_ice_tr = 1`` in ``&namtrc_ice``).
+ See e.g. the correspondent PISCES subroutine.
+
+:file:`trcwri_my_trc.F90`
+ This routine performs the output of the model tracers (only those defined in ``&namtrc``) using
+ IOM module (see chapter “Output and Diagnostics†in the :doc:`Reference Manual <cite>`).
+ It is possible to place here the output of additional variables produced by the model,
+ if not done elsewhere in the code, using the call to ``iom_put``.
+
+Coupling an external BGC model using NEMO framework
+===================================================
+
+The coupling with an external BGC model through the NEMO compilation framework can be achieved in
+different ways according to the degree of coding complexity of the Biogeochemical model, like e.g.,
+the whole code is made only by one file or
+it has multiple modules and interfaces spread across several subfolders.
+
+Beside the 6 core files of MY_TRC module, let’s assume an external BGC model named *MYBGC* and
+constituted by a rather essential coding structure, likely few Fortran files.
+The new coupled configuration name is *NEMO_MYBGC*.
+
+The best solution is to have all files (the modified ``MY_TRC`` routines and the BGC model ones)
+placed in a unique folder with root ``MYBGCPATH`` and
+to use the makenemo external readdressing of ``MY_SRC`` folder.
+
+The coupled configuration listed in :file:`work_cfgs.txt` will look like
+
+::
+
+ NEMO_MYBGC OCE TOP
+
+and the related ``cpp_MYBGC.fcm`` content will be
+
+.. code-block:: perl
+
+ bld::tool::fppkeys key_xios key_top
+
+the compilation with :file:`makenemo` will be executed through the following syntax
+
+.. code-block:: console
+
+ $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>'
+
+The makenemo feature ``-e`` was introduced to
+readdress at compilation time the standard MY_SRC folder (usually found in NEMO configurations) with
+a user defined external one.
+
+The compilation of more articulated BGC model code & infrastructure,
+like in the case of BFM (|BFM man|_), requires some additional features.
+
+As before, let’s assume a coupled configuration name *NEMO_MYBGC*,
+but in this case MYBGC model root becomes :file:`MYBGC` path that
+contains 4 different subfolders for biogeochemistry,
+named :file:`initialization`, :file:`pelagic`, and :file:`benthic`,
+and a separate one named :file:`nemo_coupling` including the modified `MY_SRC` routines.
+The latter folder containing the modified NEMO coupling interface will be still linked using
+the makenemo ``-e`` option.
+
+In order to include the BGC model subfolders in the compilation of NEMO code,
+it will be necessary to extend the configuration :file:`cpp_NEMO_MYBGC.fcm` file to include the specific paths of :file:`MYBGC` folders, as in the following example
+
+.. code-block:: perl
+
+ bld::tool::fppkeys key_xios key_top
+
+ src::MYBGC::initialization <MYBGCPATH>/initialization
+ src::MYBGC::pelagic <MYBGCPATH>/pelagic
+ src::MYBGC::benthic <MYBGCPATH>/benthic
+
+ bld::pp::MYBGC 1
+ bld::tool::fppflags::MYBGC %FPPFLAGS
+ bld::tool::fppkeys %bld::tool::fppkeys MYBGC_MACROS
+
+where *MYBGC_MACROS* is the space delimited list of macros used in *MYBGC* model for
+selecting/excluding specific parts of the code.
+The BGC model code will be preprocessed in the configuration :file:`BLD` folder as for NEMO,
+but with an independent path, like :file:`NEMO_MYBGC/BLD/MYBGC/<subforlders>`.
+
+The compilation will be performed similarly to in the previous case with the following
+
+.. code-block:: console
+
+ $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>/nemo_coupling'
+
+.. note::
+ The additional lines specific for the BGC model source and build paths can be written into
+ a separate file, e.g. named :file:`MYBGC.fcm`,
+ and then simply included in the :file:`cpp_NEMO_MYBGC.fcm` as follow
+
+ .. code-block:: perl
+
+ bld::tool::fppkeys key_xios key_top
+ inc <MYBGCPATH>/MYBGC.fcm
+
+ This will enable a more portable compilation structure for all MYBGC related configurations.
+
+.. warning::
+ The coupling interface contained in :file:`nemo_coupling` cannot be added using the FCM syntax,
+ as the same files already exists in NEMO and they are overridden only with
+ the readdressing of MY_SRC contents to avoid compilation conflicts due to duplicate routines.
+
+All modifications illustrated above, can be easily implemented using shell or python scripting
+to edit the NEMO configuration :file:`CPP.fcm` file and
+to create the BGC model specific FCM compilation file with code paths.
+
+.. |BFM man| replace:: BFM-NEMO coupling manual
diff --git a/doc/rst/source/unpub/crs.rst b/doc/rst/source/unpub/crs.rst
deleted file mode 120000
index afcd1994fe6a61fe00029d01df37b120a9b29c5e..0000000000000000000000000000000000000000
--- a/doc/rst/source/unpub/crs.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../../src/OCE/CRS/README.rst
\ No newline at end of file
diff --git a/doc/rst/source/unpub/crs.rst b/doc/rst/source/unpub/crs.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8633dbeb339fd6d61d4f191a6d453c7936d430f8
--- /dev/null
+++ b/doc/rst/source/unpub/crs.rst
@@ -0,0 +1,153 @@
+**********************************
+On line biogeochemistry coarsening
+**********************************
+
+.. todo::
+
+
+
+.. contents::
+ :local:
+
+Presentation
+============
+
+A capacity of coarsening physics to force a BGC model coupled to NEMO has been developed.
+This capacity allow to run 'online' a BGC model coupled to OCE-SI3 with a lower resolution,
+to reduce the CPU cost of the BGC model, while preserving the effective resolution of the dynamics.
+
+A presentation is available [attachment:crs_wiki_1.1.pdf​ here], where the methodology is presented.
+
+What is available and working for now in this version
+=====================================================
+
+[To be completed]
+
+Description of the successful validation tests
+==============================================
+
+[To be completed]
+
+What is not working yet with on line coarsening of biogeochemistry
+==================================================================
+
+[To be completed]
+
+''should include precise explanation on MPI decomposition problems too''
+
+How to set up and use on line biogeochemistry
+=============================================
+
+Extract the on line biogeochemistry branch
+------------------------------------------
+
+To get the appropriate source code with the on line coarsening of biogeochemistry feature:
+
+.. code-block:: console
+
+ $ svn co https://forge.ipsl.jussieu.fr/nemo/browser/NEMO/branches/2018/dev_r5003_MERCATOR6_CRS
+
+
+How to activate coarsening?
+---------------------------
+
+To activate the coarsening, ``key_crs`` should be added to list of CPP keys.
+This key will only activate the coarsening of dynamics.
+
+Some parameters are available in the namelist_cfg:
+
+.. code-block:: fortran
+
+ ! passive tracer coarsened online simulations
+ !-----------------------------------------------------------------------
+ nn_factx = 3 ! Reduction factor of x-direction
+ nn_facty = 3 ! Reduction factor of y-direction
+ nn_msh_crs = 0 ! create (=1) a mesh file or not (=0)
+ nn_crs_kz = 3 ! 0, volume-weighted MEAN of KZ
+ ! 1, MAX of KZ
+ ! 2, MIN of KZ
+ ! 3, 10^(MEAN(LOG(KZ))
+ ! 4, MEDIANE of KZ
+ ln_crs_wn = .false. ! wn coarsened (T) or computed using horizontal divergence ( F )
+ ! !
+ ln_crs_top = .true. !coarsening online for the bio
+ /
+
+- Only ``nn_factx = 3`` is available and the coarsening only works for grids with a T-pivot point for
+ the north-fold lateral boundary condition (ORCA025, ORCA12, ORCA36, ...).
+- ``nn_msh_crs = 1`` will activate the generation of the coarsened grid meshmask.
+- ``nn_crs_kz`` is the operator to coarsen the vertical mixing coefficient.
+- ``ln_crs_wn``
+
+ - when ``key_vvl`` is activated, this logical has no effect;
+ the coarsened vertical velocities are computed using horizontal divergence.
+ - when ``key_vvl`` is not activated,
+
+ - coarsened vertical velocities are computed using horizontal divergence (``ln_crs_wn = .false.``)
+ - or coarsened vertical velocities are computed with an average operator (``ln_crs_wn = .true.``)
+- ``ln_crs_top = .true.``: should be activated to run BCG model in coarsened space;
+ so only works when ``key_top`` is in the cpp list and eventually ``key_pisces`` or ``key_my_trc``.
+
+Choice of operator to coarsene KZ
+---------------------------------
+
+A sensiblity test has been done with an Age tracer to compare the different operators.
+The 3 and 4 options seems to provide the best results.
+
+Some results can be found [xxx here]
+
+Example of xml files to output coarsened variables with XIOS
+------------------------------------------------------------
+
+In the [attachment:iodef.xml iodef.xml] file, a "nemo" context is defined and
+some variable defined in [attachment:file_def.xml file_def.xml] are writted on the ocean-dynamic grid.
+To write variables on the coarsened grid, and in particular the passive tracers,
+a "nemo_crs" context should be defined in [attachment:iodef.xml iodef.xml] and
+the associated variable are listed in [attachment:file_crs_def.xml file_crs_def.xml ].
+
+Passive tracers tracers initial conditions
+------------------------------------------
+
+When initial conditions are provided in NetCDF files, the field might be:
+
+- on the coarsened grid
+- or they can be on another grid and
+ interpolated `on-the-fly <http://forge.ipsl.jussieu.fr/nemo/wiki/Users/SetupNewConfiguration/Weight-creator>`_.
+ Example of namelist for PISCES :
+
+ .. code-block:: fortran
+
+ !-----------------------------------------------------------------------
+ &namtrc_dta ! Initialisation from data input file
+ !-----------------------------------------------------------------------
+ !
+ sn_trcdta(1) = 'DIC_REG1' , -12 , 'DIC' , .false. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(2) = 'ALK_REG1' , -12 , 'ALK' , .false. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(3) = 'O2_REG1' , -1 , 'O2' , .true. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(5) = 'PO4_REG1' , -1 , 'PO4' , .true. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(7) = 'Si_REG1' , -1 , 'Si' , .true. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(10) = 'DOC_REG1' , -12 , 'DOC' , .false. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(14) = 'Fe_REG1' , -12 , 'Fe' , .false. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(23) = 'NO3_REG1' , -1 , 'NO3' , .true. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ rn_trfac(1) = 1.0e-06 ! multiplicative factor
+ rn_trfac(2) = 1.0e-06 ! - - - -
+ rn_trfac(3) = 44.6e-06 ! - - - -
+ rn_trfac(5) = 122.0e-06 ! - - - -
+ rn_trfac(7) = 1.0e-06 ! - - - -
+ rn_trfac(10) = 1.0e-06 ! - - - -
+ rn_trfac(14) = 1.0e-06 ! - - - -
+ rn_trfac(23) = 7.6e-06 ! - - - -
+
+ cn_dir = './' ! root directory for the location of the data files
+
+PISCES forcing files
+--------------------
+
+They might be on the coarsened grid.
+
+Perspectives
+============
+
+For the future, a few options are on the table to implement coarsening for biogeochemistry in 4.0 and
+future releases.
+Those will be discussed in Autumn 2018
diff --git a/doc/rst/source/unpub/doc.rst b/doc/rst/source/unpub/doc.rst
deleted file mode 120000
index 428f3fb0da3d4e87fa2b4f1789f75473675c1017..0000000000000000000000000000000000000000
--- a/doc/rst/source/unpub/doc.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../README.rst
\ No newline at end of file
diff --git a/doc/rst/source/unpub/doc.rst b/doc/rst/source/unpub/doc.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7e722505b3d2842f5aab0cfa07acb6acb37d042f
--- /dev/null
+++ b/doc/rst/source/unpub/doc.rst
@@ -0,0 +1,130 @@
+**Contents**
+
+.. contents::
+ :local:
+
+
+
+
+.. _`Former web platform forge`: https://forge.ipsl.jussieu.fr/nemo
+.. _`NEMO users' guide`: https://sites.nemo-ocean.io/user-guide
+.. _`Migration Guide`: https://sites.nemo-ocean.io/user-guide/migration.html
+.. _`Change list`: https://sites.nemo-ocean.io/user-guide/changes.html
+.. _`Test case repository`: https://github.com/NEMO-ocean/NEMO-examples
+.. _`How to cite`: https://www.nemo-ocean.eu/bibliography/how-to-cite/
+.. _`NEMO forums`: https://nemo-ocean.discourse.group
+.. _`NEMO newsletter`: https://listes.ipsl.fr/sympa/subscribe/nemo-newsletter
+.. _`NEMO publications`: https://www.nemo-ocean.eu/bibliography/publications/add
+.. _`NEMO projects`: https://www.nemo-ocean.eu/projects/add
+.. _`Special Issue`: https://gmd.copernicus.org/articles/special_issue40.html
+.. _`NEMO System Team wiki`: https://forge.nemo-ocean.eu/developers/home/-/wikis/Home
+.. _`NEMO ocean engine`: https://zenodo.org/record/1464816
+.. _`NEMO Tracers engine` : https://zenodo.org/record/1471700
+.. _`NEMO Sea Ice engine`: https://zenodo.org/record/1471689
+
+
+**Welcome to NEMO home page!**
+
+NEMO (*Nucleus for European Modelling of the Ocean*) is a state-of-the-art modelling
+framework for research activities and forecasting services in ocean and climate sciences,
+developed in a sustainable way by the NEMO European consortium since 2008.
+
+This page intends to help you to get started using the NEMO platform and to introduce you
+to the different levels of information available. It starts here with NEMO release 4.2.0.
+
+Reminder: Our `Former web platform forge`_ (SVN+Trac) contains the previous documentation
+and releases made available from the beginning of the project up to of NEMO 4.0.
+
+Getting started
+===============
+
+Getting your hands on NEMO: the first steps are described in detail in the
+`NEMO users' guide`_ . This explains how to download the code, build the environment,
+create the executable, and perform a first integration.
+
+If you are already using a previous release of NEMO, please refer to the
+`Migration Guide`_ which aims to help you to make the move to 4.2.0.
+
+The above users guides cover in detail what is available from gitlab and supported by NEMO
+System Team. Aside from this web platform, a set of test cases is also available from the
+`Test case repository`_ . These test cases can be useful for students, outreach, and
+exploring specific aspects of NEMO with light configurations. The web page also allows you
+to submit test cases you have developed and want to share with the community. Feel free to
+contribute!
+
+
+Project documentation
+=====================
+
+Reference manuals fully describing NEMO for the three main component
+
+* |OCE| models the ocean {thermo}dynamics and solves the primitive equations (`./src/OCE <./src/OCE>`_)
+
+* |ICE| simulates sea-ice {thermo}dynamics, brine inclusions and subgrid-scale thickness
+ variations (`./src/ICE <./src/ICE>`_)
+
+* |MBG| models the {on,off}line oceanic tracers transport and biogeochemical processes
+ (`./src/TOP <./src/TOP>`_)
+are available from Zenodo:
+
+============ ======================== =====
+ Component Reference Manual DOI
+============ ======================== =====
+ |NEMO-OCE| `NEMO ocean engine`_ .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.6334656.svg
+ :target: https://doi.org/10.5281/zenodo.6334656
+ |NEMO-ICE| `NEMO Sea Ice engine`_ *not yet available*
+ |NEMO-MBG| `NEMO Tracers engine`_ .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471700.svg
+ :target: https://doi.org/10.5281/zenodo.1471700
+============ ======================== =====
+
+These reference manuals are the publications that should be cited in your own
+publications. Please visit `How to cite`_? for details.
+
+New features of 4.2.0 release are described in the `Change list`_ section of the `NEMO users' guide`_
+
+
+Asking questions, and exchanging information
+============================================
+- Register once for all and use the `NEMO forums`_ on discourse to share and discuss with the NEMO community.
+
+- Register once for all and receive by mail the `NEMO newsletter`_ : recommended for all
+ users to receive the major announcements from the project (new releases, open meetings and
+ main informations). Low traffic: about ten messages a year.
+
+
+Contributing to NEMO visibility: projects and publications
+==========================================================
+Please help us justifying the NEMO development efforts by
+
+- Adding your publications using NEMO and its outputs to the `NEMO publications`_ page
+
+- Describing your project using NEMO on the `NEMO projects`_ page
+
+NEMO also has a `Special Issue`_ in the open-access journal
+Geoscientific Model Development (GMD) from the European Geosciences Union
+The main scope is to collect relevant manuscripts covering various topics and
+to provide a single portal to assess the model potential and evolution.
+
+
+
+Contributing to NEMO development
+================================
+
+NEMO strives to be written in a way which allows the easy incorporation of developments.
+You are welcome to contribute to the development of the NEMO Shared reference. NEMO
+development is driven by NEMO Consortium planning and producing NEMO's sustainable
+development in order to keep a reliable evolving framework. Development is organised and
+scheduled through a five years development strategy, Working groups and the activities of
+the development team (named NEMO System Team) in a yearly workplan. More information is
+available on the `NEMO System Team wiki`_
+
+
+Disclaimer
+==========
+
+The NEMO source code is freely available and distributed under
+`CeCILL v2.0 license <./LICENSE>`_ (GNU GPL compatible).
+
+You can use, modify and/or redistribute the software under its terms,
+but users are provided only with a limited warranty and the software's authors and
+the successive licensor's have only limited liability.
diff --git a/doc/rst/source/unpub/src.rst b/doc/rst/source/unpub/src.rst
deleted file mode 120000
index 683e1231d688ec36297546a00c9068da332237d8..0000000000000000000000000000000000000000
--- a/doc/rst/source/unpub/src.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../../src/README.rst
\ No newline at end of file
diff --git a/doc/rst/source/unpub/src.rst b/doc/rst/source/unpub/src.rst
new file mode 100644
index 0000000000000000000000000000000000000000..4ea8114d03b3688ffee7fdda1f82a76942756356
--- /dev/null
+++ b/doc/rst/source/unpub/src.rst
@@ -0,0 +1,15 @@
+*******
+Sources
+*******
+
+.. todo::
+
+
+
+:file:`ICE`: |NEMO-ICE|
+
+:file:`NST`: AGRIF for embedded zooms
+
+:file:`OCE`: |NEMO-OCE|
+
+:file:`TOP`: |NEMO-MBG|
diff --git a/doc/rst/source/zooms.bib b/doc/rst/source/zooms.bib
deleted file mode 120000
index 509a0a72f3cf8a9a41f328dd752d79023fc4cf8e..0000000000000000000000000000000000000000
--- a/doc/rst/source/zooms.bib
+++ /dev/null
@@ -1 +0,0 @@
-../../../src/NST/zooms.bib
\ No newline at end of file
diff --git a/doc/rst/source/zooms.bib b/doc/rst/source/zooms.bib
new file mode 100644
index 0000000000000000000000000000000000000000..2071f4e1fe7ee1dab155c5d98d5fca7f0a5503d9
--- /dev/null
+++ b/doc/rst/source/zooms.bib
@@ -0,0 +1,46 @@
+
+@article{ debreu.marchesiello.ea_OM12,
+ title = "Two-way nesting in split-explicit ocean models:
+ Algorithms, implementation and validation",
+ pages = "1--21",
+ journal = "Ocean Modelling",
+ volume = "49-50",
+ author = "Debreu, Laurent and Marchesiello, Patrick and Penven,
+ Pierrick and Cambon, Gildas",
+ year = "2012",
+ month = "Jun",
+ publisher = "Elsevier BV",
+ issn = "1463-5003",
+ doi = "10.1016/j.ocemod.2012.03.003"
+}
+
+@article{ penven.debreu.ea_OM06,
+ title = "Evaluation and application of the ROMS 1-way embedding
+ procedure to the central california upwelling system",
+ pages = "157--187",
+ journal = "Ocean Modelling",
+ volume = "12",
+ number = "1-2",
+ author = "Penven, Pierrick and Debreu, Laurent and Marchesiello,
+ Patrick and McWilliams, James C.",
+ year = "2006",
+ month = "Jan",
+ publisher = "Elsevier BV",
+ issn = "1463-5003",
+ doi = "10.1016/j.ocemod.2005.05.002"
+}
+
+@article{ spall.holland_JPO91,
+ title = "A Nested Primitive Equation Model for Oceanic
+ Applications",
+ pages = "205--220",
+ journal = "Journal of Physical Oceanography",
+ volume = "21",
+ number = "2",
+ author = "Spall, Michael A. and Holland, William R.",
+ year = "1991",
+ month = "Feb",
+ publisher = "American Meteorological Society",
+ issn = "1520-0485",
+ doi = "10.1175/1520-0485(1991)021<0205:anpemf>2.0.co;2"
+}
diff --git a/doc/rst/source/zooms.rst b/doc/rst/source/zooms.rst
deleted file mode 120000
index 31d8e4ef0ed0232c1fcdb4b3b1eebc48fe3cfe14..0000000000000000000000000000000000000000
--- a/doc/rst/source/zooms.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../src/NST/README.rst
\ No newline at end of file
diff --git a/doc/rst/source/zooms.rst b/doc/rst/source/zooms.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2d5469dfb2c7c738ca4d2d23453525e8dfb493bd
--- /dev/null
+++ b/doc/rst/source/zooms.rst
@@ -0,0 +1,106 @@
+**************
+Embedded zooms
+**************
+
+.. todo::
+
+
+
+.. contents::
+ :local:
+
+Overview
+========
+
+AGRIF (Adaptive Grid Refinement In Fortran) is a library that
+allows the seamless space and time refinement over rectangular regions in NEMO.
+Refinement factors can be odd or even (usually lower than 5 to maintain stability).
+Interaction between grid is "two-ways" in the sense that
+the parent grid feeds the child grid open boundaries and
+the child grid provides volume averages of prognostic variables once
+a given number of time step is completed.
+These pages provide guidelines how to use AGRIF in NEMO.
+For a more technical description of the library itself, please refer to AGRIF_.
+
+Compilation
+===========
+
+Activating AGRIF requires to append the cpp key ``key_agrif`` at compilation time:
+
+.. code-block:: sh
+
+ ./makenemo [...] add_key 'key_agrif'
+
+Although this is transparent to users,
+the way the code is processed during compilation is different from the standard case:
+a preprocessing stage (the so called ``conv`` program) translates the actual code so that
+saved arrays may be switched in memory space from one domain to an other.
+
+Definition of the grid hierarchy
+================================
+
+An additional text file :file:`AGRIF_FixedGrids.in` is required at run time.
+This is where the grid hierarchy is defined.
+An example of such a file, here taken from the ``ICEDYN`` test case, is given below
+
+.. literalinclude:: ../../../tests/ICE_AGRIF/EXPREF/AGRIF_FixedGrids.in
+
+The first line indicates the number of zooms (1).
+The second line contains the starting and ending indices in both directions on the root grid
+(``imin=34 imax=63 jmin=34 jmax=63``) followed by the space and time refinement factors (3 3 3).
+The last line is the number of child grid nested in the refined region (0).
+A more complex example with telescoping grids can be found below and
+in the :file:`AGRIF_DEMO` reference configuration directory.
+
+.. todo::
+
+ Add some plots here with grid staggering and positioning?
+
+When creating the nested domain, one must keep in mind that
+the child domain is shifted toward north-east and
+depends on the number of ghost cells as illustrated by
+the *attempted* drawing below for ``nbghostcells=1`` and ``nbghostcells=3``.
+The grid refinement is 3 and ``nxfin`` is the number of child grid points in i-direction.
+
+.. image:: _static/agrif_grid_position.jpg
+
+Note that rectangular regions must be defined so that they are connected to a single parent grid.
+Hence, defining overlapping grids with the same refinement ratio will not work properly,
+boundary data exchange and update being only performed between root and child grids.
+Use of east-west periodic or north-fold boundary conditions is not allowed in child grids either.
+Defining for instance a circumpolar zoom in a global model is therefore not possible.
+
+Preprocessing
+=============
+
+Knowing the refinement factors and area,
+a ``NESTING`` pre-processing tool may help to create needed input files
+(mesh file, restart, climatological and forcing files).
+The key is to ensure volume matching near the child grid interface,
+a step done by invoking the :file:`Agrif_create_bathy.exe` program.
+You may use the namelists provided in the :file:`NESTING` directory as a guide.
+These correspond to the namelists used to create ``AGRIF_DEMO`` inputs.
+
+Namelist options
+================
+
+Each child grid expects to read its own namelist so that different numerical choices can be made
+(these should be stored in the form :file:`1_namelist_cfg`, :file:`2_namelist_cfg`, etc...
+according to their rank in the grid hierarchy).
+Consistent time steps and number of steps with the chosen time refinement have to be provided.
+Specific to AGRIF is the following block:
+
+.. literalinclude:: ../../namelists/namagrif
+ :language: fortran
+
+where sponge layer coefficients have to be chosen according to the child grid mesh size.
+The sponge area is hard coded in NEMO and applies on the following grid points:
+2 x refinement factor (from ``i=1+nbghostcells+1`` to ``i=1+nbghostcells+sponge_area``)
+
+.. rubric:: References
+
+.. bibliography:: zooms.bib
+ :all:
+ :style: unsrt
+ :labelprefix: A
+ :keyprefix: a-