Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/Makefile
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/Makefile	(revision 11396)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/Makefile	(revision 13463)
@@ -1,3 +1,3 @@
-# Minimal makefile for Sphinx documentation
+# Makefile for Sphinx documentation
 #
 
@@ -5,21 +5,155 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = NEMO
-SOURCEDIR     = source
+PAPER         =
 BUILDDIR      = build
 
-# Put it first so that "make" without argument is like "make help".
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml drafthtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  drafthtml  to make an autoupdate HTML export while editing (todo list included)"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
-.PHONY: help Makefile
+clean:
+	-rm -rf $(BUILDDIR)/*
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+html:
+	$(SPHINXBUILD)   -b html          $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-# Watch source directory and rebuild the documentation when a change is detected
-# Browse to 127.0.0.1:8000/NEMO_guide.html
-htmllive:
-	sphinx-autobuild $(SPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/htmllive
+dirhtml:
+	$(SPHINXBUILD)   -b dirhtml       $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+drafthtml:
+	sphinx-autobuild -b html -t draft $(ALLSPHINXOPTS) $(BUILDDIR)/drafthtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/drafthtml."
+
+singlehtml:
+	$(SPHINXBUILD)   -b singlehtml    $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD)   -b pickle        $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD)   -b json          $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD)   -b htmlhelp      $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD)   -b qthelp        $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/NEMO.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/NEMO.qhc"
+
+devhelp:
+	$(SPHINXBUILD)   -b devhelp       $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/NEMO"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/NEMO"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD)   -b epub          $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD)   -b latex         $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD)   -b latex         $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD)   -b text          $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD)   -b man           $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD)   -b texinfo       $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD)   -b texinfo       $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD)   -b gettext      $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD)   -b changes       $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD)   -b linkcheck     $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD)   -b doctest       $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/README.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/README.rst	(revision 11396)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/README.rst	(revision 13463)
@@ -3,5 +3,7 @@
 **********************
 
-| The NEMO guide is made up of several files written in `ReStructuredText <http://docutils.sourceforge.net/rst.html>`_ (`.rst` extension), a WYSIWYG markup language used in the Python community, and scattered all over the NEMO sources.
+| The NEMO guide is made up of several files written in
+  `ReStructuredText <http://docutils.sourceforge.net/rst.html>`_ (`.rst` extension),
+  a WYSIWYG markup language used in the Python community, and scattered all over the NEMO sources.
 | You can view them one by one in plain text from `./source` folder, or export all to a user-friendly guide under `./build` (only HTML format at the moment, PDF expected later).
 
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/NEMO_guide.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/NEMO_guide.rst	(revision 11396)
+++ 	(revision )
@@ -1,70 +1,0 @@
-#################
-Quick Start Guide
-#################
-
-..
-	For headings markup, this convention is recommended from Python’s Style Guide
-	# with overline, for parts
-	* with overline, for chapters
-	=, for sections
-	-, for subsections
-	^, for subsubsections
-	", for paragraphs
-
-	'global.rst' contains a list of common directives (roles, substitutions and URL links)
-	It is loaded for each file thanks to 'rst_epilog' setting in 'conf.py'
-
-.. toctree::
-   :hidden:
-   :caption: Getting started
-
-   install
-   configurations
-   test_cases
-
-.. toctree::
-   :hidden:
-   :caption: Setup your configuration
-
-   setup
-   diagnostics
-   tools
-
-.. toctree::
-   :hidden:
-   :caption: Advanced use
-
-   zooms
-   coupling
-   data_assimilation
-   tracers
-
-.. toctree::
-   :hidden:
-   :caption: Miscellaneous
-
-   contributing
-   release_notes
-   Glossary<definitions>
-
-.. include:: readme.rst
-
-.. Next headings markup acording to readme.rst
-
-References
-==========
-
-.. bibliography:: references.bib
-   :all:
-   :style: unsrt
-   :labelprefix: R
-
-Disclaimer
-==========
-
-The NEMO source code is freely available and distributed under CeCILL license
-(GNU GPL compatible - see ``./LICENSE``).
-
-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.
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/_static/style.css
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/_static/style.css	(revision 11396)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/_static/style.css	(revision 13463)
@@ -1,5 +1,5 @@
-.rstblue               { color: blue    ; }
-.rstgrey , .rstgreysup { color: grey    ; }
-.rstgreen              { color: seagreen; }
+.blue            { color: blue    ; }
+.grey , .greysup { color: grey    ; }
+.green           { color: seagreen; }
 
 .logo { filter: invert(1) !important; }
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/acro.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/acro.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/acro.rst	(revision 13463)
@@ -0,0 +1,39 @@
+********
+Acronyms
+********
+
+.. todo::
+
+
+
+.. glossary::
+
+   `AGRIF`_
+      *Adaptive Grid Refinement In Fortran*,
+      package for the integration of full adaptive mesh refinement features within
+      an existing multidimensional finite difference model
+
+   SI\ :sup:`3`\
+      *Sea Ice Integrated Initiative*,
+      unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework
+
+   `OASIS`_
+      *Ocean Atmosphere Sea Ice Soil*,
+      coupling software to synchronise numerical codes representing different components of the climate system
+
+   PISCES
+      *Pelagic Interactions Scheme for Carbon and Ecosystem Studies*,
+      biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients
+
+   TAM
+      *Tangent linear and Adjoint Model*,
+      tools to analyse and control the NEMO dynamical core for a wide range of applications such as
+      sensitivity analysis, parameter estimation, vectors computation or data assimilation.
+
+   TOP
+      *Tracers in Ocean Paradigm*,
+      on/off-line oceanic tracers transport and biogeochemistry models
+
+   `XIOS`_
+      *XML Input Output Server*,
+      library dedicated to input/output management of climate code
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/cfgs.bib
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/cfgs.bib	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/cfgs.bib	(revision 13463)
@@ -0,0 +1,25 @@
+@article{ODEA2012,
+author = {E J O’Dea and A K Arnold and K P Edwards and R Furner and P Hyder and M J Martin and J R Siddorn and D Storkey and J While and J T Holt and H Liu},
+title = {An operational ocean forecast system incorporating NEMO and SST data assimilation for the tidally driven European North-West shelf},
+journal = {Journal of Operational Oceanography},
+volume = {5},
+number = {1},
+pages = {3-17},
+year  = {2012},
+publisher = {Taylor & Francis},
+doi = {10.1080/1755876X.2012.11020128},
+URL = {https://doi.org/10.1080/1755876X.2012.11020128},
+eprint = {https://doi.org/10.1080/1755876X.2012.11020128}
+}
+
+@Article{gmd-8-2465-2015,
+AUTHOR = {Aumont, O. and Eth\'e, C. and Tagliabue, A. and Bopp, L. and Gehlen, M.},
+TITLE = {PISCES-v2: an ocean biogeochemical model for carbon and ecosystem studies},
+JOURNAL = {Geoscientific Model Development},
+VOLUME = {8},
+YEAR = {2015},
+NUMBER = {8},
+PAGES = {2465--2513},
+URL = {https://www.geosci-model-dev.net/8/2465/2015/},
+DOI = {10.5194/gmd-8-2465-2015}
+}
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/cfgs.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/cfgs.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/cfgs.rst	(revision 13463)
@@ -0,0 +1,1 @@
+link ../../../cfgs/README.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/changes.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/changes.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/changes.rst	(revision 13463)
@@ -0,0 +1,1 @@
+link ../../../CHANGES.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/cite.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/cite.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/cite.rst	(revision 13463)
@@ -0,0 +1,47 @@
+***********
+How to cite
+***********
+
+.. todo::
+
+
+
+|NEMO-OCE|
+   :title:`NEMO ocean engine`,
+   NEMO System Team,
+   Scientific Notes of Climate Modelling Center, 27,
+   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL),
+   :doi:`10.5281/zenodo.1464816`
+
+.. literalinclude:: ref.bib
+   :language: bibtex
+   :lines:    1-9
+   :caption:  BibTeX source for NEMO manual
+
+|NEMO-ICE|
+   :title:`Sea Ice modelling Integrated Initiative (SI`\ :sup:`3`\ :title:`) --
+   The NEMO sea ice engine`,
+   NEMO Sea Ice Working Group,
+   Scientific Notes of Climate Modelling Center, 31,
+   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL),
+   :doi:`10.5281/zenodo.1464816`
+
+
+.. literalinclude:: ref.bib
+   :language: bibtex
+   :lines:    13-21
+   :caption:  BibTeX source for SI\ :sup:`3` manual
+
+|NEMO-TOP|
+   :title:`Tracer in Ocean Paradigm (TOP) -- The NEMO passive tracer engine`,
+   NEMO TOP Working Group,
+   Scientific Notes of Climate Modelling Center, 28,
+   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL),
+   :doi:`10.5281/zenodo.1464816`
+
+
+
+.. literalinclude:: ref.bib
+   :language: bibtex
+   :lines:    25-33
+   :caption:  BibTeX source for TOP manual
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/coarsening.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/coarsening.rst	(revision 11396)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../src/OCE/CRS/README.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/conf.py
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/conf.py	(revision 11396)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/conf.py	(revision 13463)
@@ -1,48 +1,96 @@
 # -*- coding: utf-8 -*-
 #
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
-
-# -- Project information -----------------------------------------------------
-
-project = 'NEMO'
-author = 'NEMO System Team'
-
-# The short X.Y version
-version = 'trk'
-# The full version, including alpha/beta/rc tags
-release = 'trunk'
-
-
-# -- General configuration ---------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex']
+# NEMO documentation build configuration file, created by
+# sphinx-quickstart on Tue Oct 15 20:13:55 2019.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex',
+              'sphinx.ext.todo'    , 'sphinx.ext.autosectionlabel']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
 # The master toctree document.
-master_doc = 'NEMO_guide'
+master_doc = 'guide'
+
+# General information about the project.
+project = u'NEMO'
+copyright = u'2019, NEMO Consortium'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = 'trk'
+# The full version, including alpha/beta/rc tags.
+release = 'trunk'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = ['global.rst', 'coarsening.rst']
+exclude_patterns = ['global.rst', 'readme.rst']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-
-# -- Options for HTML output -------------------------------------------------
+pygments_style = 'emacs'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
 html_theme = 'sphinx_rtd_theme'
 
@@ -50,6 +98,24 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
-#
-html_theme_options = {}
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = '_static/ORCA.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -58,37 +124,124 @@
 html_static_path = ['_static']
 
-html_favicon = '_static/ORCA.ico'
-
-
-# -- Options for LaTeX output ------------------------------------------------
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'NEMOdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
 
 latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
+# (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-    (master_doc, 'NEMO_guide.tex', 'NEMO Quick Start Guide',
-     'NEMO System Team', 'howto'),
+  ('guide', 'guide.tex', u'NEMO Quick Start Guide',
+   u'NEMO Consortium', 'howto'),
 ]
 
-
-# -- Customisation -----------------------------------------------------------
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('guide', 'nemo', u'NEMO Documentation',
+     [u'NEMO System Team'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('guide', 'NEMO', u'NEMO Documentation',
+   u'NEMO System Team', 'NEMO', 'Community Ocean Model',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# -- Customisation -------------------------------------------------------------
 
 # Timestamping
@@ -99,10 +252,12 @@
 # Link aliases
 extlinks = {
-	'doi'    : ('https://doi.org/%s'                       , None),
-	'forge'  : ('https://forge.ipsl.jussieu.fr/nemo/%s'    , None),
-	'github' : ('https://github.com/%s'                    , None),
-	'xios'   : ('https://forge.ipsl.jussieu.fr/ioserver/%s', None),
-	'website': ('https://www.nemo-ocean.eu/%s'             , None),
-	'zenodo' : ('https://zenodo.org/publication/%s'        , None)
+   'doi'    : ('https://doi.org/%s'                                                    , 'doi:'),
+   'manhtml': ('https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/manual/html/%s', None  ),
+   'forge'  : ('https://forge.ipsl.jussieu.fr/nemo/%s'                                 , None  ),
+   'gmd'    : ('https://www.geosci-model-dev.net/%s'                                   , None  ),
+   'github' : ('https://github.com/NEMO-ocean/%s'                                      , None  ),
+   'xios'   : ('https://forge.ipsl.jussieu.fr/ioserver/%s'                             , None  ),
+   'website': ('https://www.nemo-ocean.eu/%s'                                          , None  ),
+   'zenodo' : ('https://zenodo.org/publication/%s'                                     , None  )
 }
 
@@ -112,4 +267,14 @@
 # SVN revision
 import subprocess
-revision = subprocess.check_output("svnversion").decode("utf-8")
-rst_prolog = '.. |revision| replace:: %s' % revision
+rev = subprocess.check_output("svnversion").decode("utf-8")
+rst_prolog = '.. |revision| replace:: %s' % rev
+
+# 'draft' build tag: DRAFT watermark and TODO list
+if tags.has('draft'):
+   todo_include_todos = True
+   todo_emit_warnings = True
+else:
+   exclude_patterns = ['global.rst', 'readme.rst', 'todos.rst', 'unpub*']
+
+# Default language to highlight set to fortran
+highlight_language = 'fortran'
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/configurations.bib
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/configurations.bib	(revision 11396)
+++ 	(revision )
@@ -1,25 +1,0 @@
-@article{ODEA2012,
-author = {E J O’Dea and A K Arnold and K P Edwards and R Furner and P Hyder and M J Martin and J R Siddorn and D Storkey and J While and J T Holt and H Liu},
-title = {An operational ocean forecast system incorporating NEMO and SST data assimilation for the tidally driven European North-West shelf},
-journal = {Journal of Operational Oceanography},
-volume = {5},
-number = {1},
-pages = {3-17},
-year  = {2012},
-publisher = {Taylor & Francis},
-doi = {10.1080/1755876X.2012.11020128},
-URL = {https://doi.org/10.1080/1755876X.2012.11020128},
-eprint = {https://doi.org/10.1080/1755876X.2012.11020128}
-}
-
-@Article{gmd-8-2465-2015,
-AUTHOR = {Aumont, O. and Eth\'e, C. and Tagliabue, A. and Bopp, L. and Gehlen, M.},
-TITLE = {PISCES-v2: an ocean biogeochemical model for carbon and ecosystem studies},
-JOURNAL = {Geoscientific Model Development},
-VOLUME = {8},
-YEAR = {2015},
-NUMBER = {8},
-PAGES = {2465--2513},
-URL = {https://www.geosci-model-dev.net/8/2465/2015/},
-DOI = {10.5194/gmd-8-2465-2015}
-}
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/configurations.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/configurations.rst	(revision 11396)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../cfgs/README.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/contrib.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/contrib.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/contrib.rst	(revision 13463)
@@ -0,0 +1,1 @@
+link ../../../CONTRIBUTING.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/contributing.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/contributing.rst	(revision 11396)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../CONTRIBUTING.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/coupling.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/coupling.rst	(revision 11396)
+++ 	(revision )
@@ -1,12 +1,0 @@
-********
-Coupling
-********
-
-NEMO currently exploits OASIS-3-MCT (versions 1 to 4) to implement a generalised coupled interface
-(`Coupled Formulation <http://forge.ipsl.jussieu.fr/nemo/doxygen/node50.html?doc=NEMO>`_).
-It can be used to interface with most of the European atmospheric GCM (ARPEGE, ECHAM, ECMWF, Ha- dAM, HadGAM, LMDz), as well as to regional atmospheric models (WRF, COSMO, Meso-NH, AROME).
-To implement the coupling of two independent NEMO components, ocean on one hand and sea-ice plus other surface processes on the other hand
-(`Standalone Surface Module - SAS <http://forge.ipsl.jussieu.fr/nemo/doxygen/node46.html?doc=NEMO>`_).
-
-To enable the OASIS interface the required compilation key is ``key_oasis3``. You must also add ``key_oasis3_v1v2`` if you use OASIS-3-MCT version 1 and 2.
-The parameters to set are in sections ``namsbc_cpl`` and in case of using of SAS also in section ``namsbc_sas``.
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/cplg.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/cplg.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/cplg.rst	(revision 13463)
@@ -0,0 +1,21 @@
+********
+Coupling
+********
+
+.. todo::
+
+   The ‘Coupling’ chapter needs to be enriched
+
+NEMO currently exploits OASIS-3-MCT (versions 1 to 4) to implement a generalised coupled interface
+(:manhtml:`Coupled Formulation <node50.html>`).
+It can be used to interface with most of the European atmospheric GCM
+(ARPEGE, ECHAM, ECMWF, Ha- dAM, HadGAM, LMDz), as well as to regional atmospheric models
+(WRF, COSMO, Meso-NH, AROME).
+To implement the coupling of two independent NEMO components,
+ocean on one hand and sea-ice plus other surface processes on the other hand
+(:manhtml:`Standalone Surface Module - SAS <node46.html>`).
+
+To enable the OASIS interface the required compilation key is ``key_oasis3``.
+You must also add ``key_oasis3_v1v2`` if you use OASIS-3-MCT version 1 and 2.
+The parameters to set are in sections ``&namsbc_cpl`` and
+in case of using of SAS also in section ``&namsbc_sas``.
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/da.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/da.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/da.rst	(revision 13463)
@@ -0,0 +1,68 @@
+*****************
+Data assimilation
+*****************
+
+.. todo::
+
+
+
+.. contents::
+   :local:
+
+The assimilation interface to NEMO is split into three modules.
+
+- ``OBS`` for the observation operator
+- ``ASM`` for the application of increments and model bias correction
+  (based on the assimilation increments).
+- ``TAM`` the tangent linear and adjoint model.
+
+Please see :doc:`NEMO manual <cite>` for more details including
+information about the input file formats and the namelist settings.
+
+Observation and model comparison (``OBS``)
+==========================================
+
+The observation and model comparison code (OBS) reads in observation files
+(profile temperature and salinity, sea surface temperature, sea level anomaly, sea ice concentration,
+and velocity) and calculates an interpolated model equivalent value at
+the observation location and nearest model timestep.
+The resulting data are saved in a feedback file (or files).
+The code was originally developed for use with the NEMOVAR data assimilation code, but
+can be used for validation or verification of model or any other data assimilation system.
+This is all controlled by the namelist.
+To build with the OBS code active ``key_diaobs`` must be set.
+
+More details in :manhtml:`"Observation and Model Comparison (OBS)" chapter <node83.html>`.
+
+Standalone observation operator (``SAO``)
+-----------------------------------------
+
+The OBS code can also be run after a model run using saved NEMO model data.
+This is accomplished using the standalone observation operator (SAO)
+(previously known the offline observation operator).
+
+To build the SAO use :file:`makenemo`.
+This means compiling NEMO once (in the normal way) for the chosen configuration.
+Then include ``SAO`` at the end of the relevant line in :file:`cfg.txt` file.
+Then recompile with the replacement main program in :file:`./src/SAO`.
+This is a special version of :file:`nemogcm.F90` (which doesn't run the model,
+but reads in the model fields, and observations and runs the OBS code.
+See :manhtml:`"Standalone observation operator (SAO)" section <node88.html>`.
+
+Apply assimilation increments (``ASM``)
+=======================================
+
+The ASM code adds the functionality to apply increments to the model variables:
+temperature, salinity, sea surface height, velocity and sea ice concentration.
+These are read into the model from a NetCDF file which
+may be produced by separate data assimilation code.
+The code can also output model background fields which are used as an input to data assimilation code.
+This is all controlled by the namelist ``&nam_asminc``.
+To build the ASM code ``key asminc`` must be set.
+
+More details in :manhtml:`"Apply Assimilation Increments (ASM)" chapter <node89.html>`.
+
+Tangent linear and adjoint (``TAM``)
+====================================
+
+This is the tangent linear and adjoint code of NEMO which is useful to 4D VAR assimilation.
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/data_assimilation.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/data_assimilation.rst	(revision 11396)
+++ 	(revision )
@@ -1,60 +1,0 @@
-*****************
-Data assimilation
-*****************
-
-.. contents::
-   :local:
-
-The assimilation interface to NEMO is split into three modules.
-- OBS for the observation operator
-- ASM for the application of increments and model bias correction (based on the assimilation increments).
-- TAM the tangent linear and adjoint model.
-
-Please see the `NEMO manual`_ for more details including information about the input file formats and
-the namelist settings.
-
-Observation and model comparison (OBS)
-======================================
-
-The observation and model comparison code (OBS) reads in observation files (profile temperature and salinity,
-sea surface temperature, sea level anomaly, sea ice concentration, and velocity) and
-calculates an interpolated model equivalent value at the observation location and nearest model timestep.
-The resulting data are saved in a feedback file (or files).
-The code was originally developed for use with the NEMOVAR data assimilation code, but
-can be used for validation or verification of model or any other data assimilation system.
-This is all controlled by the namelist.
-To build with the OBS code active ``key_diaobs`` must be set. 
-
-More details in the `NEMO manual`_ chapter 12.
-
-Standalone observation operator (SAO)
--------------------------------------
-
-The OBS code can also be run after a model run using saved NEMO model data.
-This is accomplished using the standalone observation operator (SAO)
-(previously known the offline observation operator).
-
-To build the SAO use makenemo.
-This means compiling NEMO once (in the normal way) for the chosen configuration.
-Then include ``SAO`` at the end of the relevant line in ``cfg.txt`` file.
-Then recompile with the replacement main program in ``./src/SAO``.
-This is a special version of ``nemogcm.F90`` (which doesn't run the model, but reads in the model fields, and
-observations and runs the OBS code.
-See section 12.4 of the `NEMO manual`_.
-
-Apply assimilation increments (ASM)
-===================================
-
-The ASM code adds the functionality to apply increments to the model variables:
-temperature, salinity, sea surface height, velocity and sea ice concentration.
-These are read into the model from a NetCDF file which may be produced by separate data assimilation code.
-The code can also output model background fields which are used as an input to data assimilation code.
-This is all controlled by the namelist nam_asminc.
-To build the ASM code ``key asminc`` must be set.
-
-More details in the `NEMO manual`_ chapter 13.
-
-Tangent linear and adjoint (TAM)
-================================
-
-This is the tangent linear and adjoint code of NEMO which is useful to 4D VAR assimilation.
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/definitions.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/definitions.rst	(revision 11396)
+++ 	(revision )
@@ -1,33 +1,0 @@
-***********
-Definitions
-***********
-
-`AGRIF`_
-	*Adaptive Grid Refinement In Fortran*, 
-	package for the integration of full adaptive mesh refinement features within 
-	an existing multidimensional finite difference model
-
-SI\ :sup:`3`\ 
-	*Sea Ice Integrated Initiative*, 
-	unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework
-
-`OASIS`_
-	*Ocean Atmosphere Sea Ice Soil*, 
-	coupling software to synchronise numerical codes representing different components of the climate system
-
-PISCES
-	*Pelagic Interactions Scheme for Carbon and Ecosystem Studies*, 
-	biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients
-
-TAM
-	*Tangent linear and Adjoint Model*, 
-	tools to analyse and control the NEMO dynamical core for a wide range of applications such as
-	sensitivity analysis, parameter estimation, vectors computation or data assimilation.
-
-TOP
-	*Tracers in Ocean Paradigm*, 
-	on/off-line oceanic tracers transport and biogeochemistry models
-
-`XIOS`_
-	*XML Input Output Server*, 
-	library dedicated to input/output management of climate code
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/diagnostics.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/diagnostics.rst	(revision 11396)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../cfgs/SHARED/README.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/diags.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/diags.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/diags.rst	(revision 13463)
@@ -0,0 +1,1 @@
+link ../../../cfgs/SHARED/README.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/docutils.conf
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/docutils.conf	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/docutils.conf	(revision 13463)
@@ -0,0 +1,2 @@
+[restructuredtext parser]
+syntax_highlight = short
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/global.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/global.rst	(revision 11396)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/global.rst	(revision 13463)
@@ -1,39 +1,79 @@
-.. Roles (custom styles related to CSS classes in 'source/_static/style.css')
+.. Roles
 
-.. role:: rstblue
-.. role:: rstgreen
-.. role:: rstgrey
-.. role:: rstgreysup(sup)
-.. role:: underline 
-   :class: underline
+.. custom styles related to CSS classes in './_static/style.css'
+
+.. role:: blue
+.. role:: green
+.. role:: grey
+.. role:: greysup(sup)
+
+.. inline code snippets
+
+.. role:: python(code)
+   :language: python
+   :class: highlight
+
+.. role:: fortran(code)
+   :language: fortran
+   :class: highlight
+
+.. role:: console(code)
+   :language: console
+   :class: highlight
 
 .. Substitutions
 
-.. |OPA| replace:: :rstblue:`NEMO-OPA`
-.. |SI3| replace:: :rstgrey:`NEMO-SI`\ :rstgreysup:`3`
-.. |TOP| replace:: :rstgreen:`NEMO-TOP/PISCES`
+.. |NEMO-OCE| replace::  :blue:`NEMO-OCE (Ocean dynamics)`
+.. |OCE|      replace::  :blue:`NEMO-OCE`
+.. |NEMO-ICE| replace::  :grey:`NEMO-SI`\ :greysup:`3`  :grey:`(Sea Ice)`
+.. |ICE|      replace::  :grey:`NEMO-SI`\ :greysup:`3`
+.. |NEMO-MBG| replace:: :green:`NEMO-TOP/PISCES (Tracers)`
+.. |MBG|      replace:: :green:`NEMO-TOP/PISCES`
 
-.. Institutes
+.. External links
 
-.. _CMCC:           https://www.cmcc.it 
-.. _CNRS:           https://www.cnrs.fr
-.. _Mercator Ocean: https://www.mercator-ocean.fr
-.. _Met Office:     https://www.metoffice.gov.uk
-.. _MOI:            https://www.mercator-ocean.fr
-.. _NERC:           https://nerc.ukri.org
+   .. Consortium institutes
 
-.. Models / Softwares
+.. _CMCC:       https://www.cmcc.it
+.. _CNRS:       https://www.cnrs.fr
+.. _Met Office: https://www.metoffice.gov.uk
+.. _MOI:        https://www.mercator-ocean.fr
+.. _NERC:       https://nerc.ukri.org
+
+   .. Models / Libraries / Dependencies
 
 .. _AGRIF:  http://agrif.imag.fr
-.. _FCM:    https://metomi.github.io/fcm/doc/
+.. _BFM:    http://www.bfm-community.eu
+.. _FCM:    https://metomi.github.io/fcm
 .. _IOIPSL: https://forge.ipsl.jussieu.fr/igcmg/browser/IOIPSL
+.. _NEMO:   https://www.nemo-ocean.eu
 .. _OASIS:  https://portal.enes.org/oasis
+.. _XIOS:   https://forge.ipsl.jussieu.fr/ioserver
 
-.. NEMO
+   .. Misc.
 
-.. _NEMO:          https://www.nemo-ocean.eu
-.. _NEMO strategy: https://doi.org/10.5281/zenodo.1471663
-.. _NEMO guide:    :samp: https://doi.org/10.5281/zenodo.1475325
-.. _NEMO manual:   https://doi.org/10.5281/zenodo.1464816
-.. _SI3 manual:    :samp: https://doi.org/10.5281/zenodo.1471689
-.. _TOP manual:    :samp: https://doi.org/10.5281/zenodo.1471700
+.. _EGU: http://www.egu.eu
+.. _Special Issue: https://www.geosci-model-dev.net/special_issue40.html
+.. _BFM man: https://cmcc-foundation.github.io/www.bfm-community.eu/files/bfm-nemo-manual_r1.0_201508.pdf
+.. _RST man: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+.. _PAPA station: http://www.pmel.noaa.gov/OCS/Papa/index-Papa.shtml
+.. _ISOMIP: http://staff.acecrc.org.au/~bkgalton/ISOMIP/test_cavities.pdf
+
+.. DOI
+
+   .. Publications (`:samp:` to deactivate link for unpublished documents)
+
+.. _DOI man OCE:          https://doi.org/10.5281/zenodo.1464816
+.. _DOI man ICE:   :samp: https://doi.org/10.5281/zenodo.1471689
+.. _DOI man MBG:   :samp: https://doi.org/10.5281/zenodo.1471700
+.. _DOI qsg:       :samp: https://doi.org/10.5281/zenodo.1475325
+.. _DOI dev  stgy:        https://doi.org/10.5281/zenodo.1471663
+.. _DOI data:             https://doi.org/10.5281/zenodo.1472245
+
+   .. Badges (same labels as previously, substitution to link images)
+
+.. |DOI man OCE| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1464816.svg
+.. |DOI man ICE| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471689.svg
+.. |DOI man MBG| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471700.svg
+.. |DOI qsg|     image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1475325.svg
+.. |DOI data|    image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1472245.svg
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/guide.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/guide.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/guide.rst	(revision 13463)
@@ -0,0 +1,75 @@
+#################
+Quick Start Guide
+#################
+
+.. For headings markup, this convention is recommended from Python’s Style Guide
+   # with overline, for parts
+   * with overline, for chapters
+   =, for sections
+   -, for subsections
+   ^, for subsubsections
+   ", for paragraphs
+
+   'global.rst' contains a list of roles, substitutions and URL links for the guide.
+   It is loaded for each file with the 'rst_epilog' setting in 'conf.py'
+
+.. toctree::
+   :hidden:
+.. todos::
+
+.. Only displayed with 'make drafthtml'
+
+.. toctree::
+   :hidden:
+   :caption: Unpublished READMEs
+   :glob:
+   :titlesonly:
+
+   unpub/*
+
+.. Only displayed with 'make drafthtml'
+
+.. toctree::
+   :hidden:
+   :caption: Getting started
+
+   install
+   cfgs
+   tests
+
+.. toctree::
+   :hidden:
+   :caption: Setup your configuration
+
+   setup
+   diags
+   tools
+
+.. toctree::
+   :hidden:
+   :caption: Advanced use
+
+   zooms
+   cplg
+   da
+   tracers
+
+.. toctree::
+   :hidden:
+   :caption: Miscellaneous
+
+   cite
+   contrib
+   changes
+   acro
+
+:Release:  |release|
+
+.. only:: draft
+
+   .. Only on draft
+
+   :*Date*:     |today|
+   :*SVN rev*:  |revision|
+
+.. include:: readme.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/ref.bib
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/ref.bib	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/ref.bib	(revision 13463)
@@ -0,0 +1,1 @@
+link ../../../REFERENCES.bib
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/references.bib
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/references.bib	(revision 11396)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../REFERENCES.bib
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/release_notes.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/release_notes.rst	(revision 11396)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../RELEASE_NOTES.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/setup.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/setup.rst	(revision 11396)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/setup.rst	(revision 13463)
@@ -1,249 +1,1 @@
-******************************
-Setting up a new configuration
-******************************
-
-.. contents::
-
-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 embeded 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:: sh
-
-	makenemo –n 'ORCA2_ICE_PISCES_MINE' -r 'ORCA2_ICE_PISCES'
-
-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:: sh
-
-	makenemo –n 'ORCA2_ICE_PISCES_MINE' -r 'ORCA2_ICE_PISCES' del_key 'key_iomput' add_key 'key_diahth'
-
-Option 3: Use the SIREN tools to subset an existing model
----------------------------------------------------------
-
-Define a regional configuration which is a sub- or 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 ``./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.
-As a basic demonstrator, a set of GLORYS files (GLObal ReanalYSis on the ORCA025 grid),
-as well as examples of namelists are available `here`_.
-
-`SIREN documentation`_
-
-Any questions or comments regarding the use of SIREN should be posted in `the corresponding forum`_.
-
-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'
-
-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 ``WORK``, ``MY_SRC`` and
-``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 ``domain_cfg.nc`` which you will need to create and
-place in the ``./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	``./cfgs/MY_NEW_CONFIG/EXP00/namelist_cfg``
-
-Create the domain_cfg.nc file which must contain the following fields
-
-.. code-block:: c++
-
-	int    ORCA, ORCA_index                  /* configuration name, configuration resolution                 */
-	int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                          */
-	int    jperio                            /* lateral global domain b.c.                                   */
-	int    ln_zco, ln_zps, ln_sco            /* flags for z-coord, z-coord with partial steps and s-coord    */
-	int    ln_isfcav                         /* flag  for ice shelf cavities                                 */
-	double glamt, glamu, glamv, glamf        /* geographic position                                          */
-	double gphit, gphiu, gphiv, gphif        /* geographic position                                          */
-	double iff, ff_f, ff_t                   /* Coriolis parameter (if not on the sphere)                    */
-	double e1t, e1u, e1v, e1f                /* horizontal scale factors                                     */
-	double e2t, e2u, e2v, e2f                /* horizontal scale factors                                     */
-	double ie1e2u_v, e1e2u, e1e2v            /* U and V surfaces (if grid size reduction in some straits)    */
-	double e3t_1d, e3w_1d                    /* reference vertical scale factors at T and W points           */
-	double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 /* vertical scale factors 3D coordinate at T,U,V,F and W points */
-	double e3uw_0, e3vw_0                    /* vertical scale factors 3D coordinate at UW and VW points     */
-	int    bottom_level, top_level           /* last wet T-points, 1st wet T-points (for ice shelf cavities) */
-
-There are two options for creating a domain_cfg.nc file:
-
-- Users can use tools of their own choice to build a ``domain_cfg.nc`` with all mandatory fields.
-- Users can adapt and apply the supplied tool available in ``./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 ``./tools/DOMAINcfg/README`` 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 ``cfgs`` directory:
-
-.. code-block:: sh
-
-	./makenemo -n 'MY_NEW_TEST' -t 'LOCK_EXCHANGE'
-
-where the ``-t`` option has been used to locate the new configuration in the ``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	  MY_SRC cpp_MY_NEW_TEST.fcm
-	EXP00   WORK
-	#
-	./tests/MY_NEW_TEST/EXP00:
-	context_nemo.xml       domain_def_nemo.xml
-	field_def_nemo-opa.xml file_def_nemo-opa.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 ``MY_SRC`` directory.
-Here the ``LOCK_EXCHANGE`` example is using 5 such routines but the full set that is available in
-the ``src/OCE/USR`` directory is::
-
-	./src/OCE/USR:
-	usrdef_closea.F90 usrdef_istate.F90 usrdef_zgr.F90
-	usrdef_fmask.F90  usrdef_nam.F90
-	usrdef_hgr.F90    usrdef_sbc.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 ``usrdef_hgr.F90`` and ``usrdef_zgr.F90`` modules.
-The application of these modules is activated whenever:
-
-.. code-block:: fortran
-
-	ln_read_cfg = .false.
-
-in any configuration's ``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 ``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 ``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::
-
-	usrdef_closea.F90 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 ``domain_cfg.nc`` file.
-.. [Note: this would be less confusing if the cn_cfg string is read directly as a character attribue from
-the ``domain_cfg.nc`` ]
-
-So, in most cases, the set up of idealised model configurations can be completed by
-copying the template routines from ``./src/OCE/USR`` into
-your new ``./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 ``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 ``./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 ``tests`` subdirectory containing available and
-up to date test cases build by the community.
-These will not be fully supported as are NEMO reference configurations, but should provide a source of raw material.
-
-.. _here:                     http://prodn.idris.fr/thredds/catalog/ipsl_public/rron463/catalog.html?dataset=DatasetScanipsl_public/rron463/INPUT_SIREN.tar
-.. _the corresponding forum:  http://forge.ipsl.jussieu.fr/nemo/discussion/forum/2
-.. _SIREN documentation:      http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html
+link ../../../src/OCE/USR/README.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/test_cases.bib
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/test_cases.bib	(revision 11396)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../tests/test_cases.bib
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/test_cases.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/test_cases.rst	(revision 11396)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../tests/README.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/tests.bib
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/tests.bib	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/tests.bib	(revision 13463)
@@ -0,0 +1,1 @@
+link ../../../tests/test_cases.bib
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/tests.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/tests.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/tests.rst	(revision 13463)
@@ -0,0 +1,1 @@
+link ../../../tests/README.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/todos.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/todos.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/todos.rst	(revision 13463)
@@ -0,0 +1,5 @@
+*********************
+List of editing tasks
+*********************
+
+.. todolist::
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/unpub/crs.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/unpub/crs.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/unpub/crs.rst	(revision 13463)
@@ -0,0 +1,1 @@
+link ../../../../src/OCE/CRS/README.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/unpub/doc.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/unpub/doc.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/unpub/doc.rst	(revision 13463)
@@ -0,0 +1,1 @@
+link ../../../README.rst
Index: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/unpub/src.rst
===================================================================
--- NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/unpub/src.rst	(revision 13463)
+++ NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/rst/source/unpub/src.rst	(revision 13463)
@@ -0,0 +1,1 @@
+link ../../../../src/README.rst
