Import last revision from nemo/nemo

Makefile

+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# 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:
+	@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)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD)   -b html          $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+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."

README.rst

+**********************
+NEMO Quick Start Guide
+**********************
+
+| The NEMO guide is made up of several files written in
+  `ReStructuredText <http://docutils.sourceforge.net/rst.html>`_ (`.rst` extension),
+  a WYSIWYG markup language used in the Python community, 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).
+
+Build and export the guide in HTML
+==================================
+
+1.  Install Sphinx documentation generator, its BibTeX extension and "Read The Docs" theme thanks to `pip` packages tool
+
+    .. code-block:: console
+
+        $ pip install sphinx sphinxcontrib.bibtex sphinx_rtd_theme
+
+2.  Build the HTML export with `make` in `./build/html`
+
+    .. code-block:: console
+
+        $ make html
+
+3.  Finally browse the guide by opening `./build/html/NEMO_guide.html`
+
+
+Edit the sources and check the output in real time
+==================================================
+
+| To facilitate the update of the guide, editors can install a useful package that will automatically trigger a new build and the reload of the HTML page for every recorded change in the sources.
+| So the reviewer saves time by controlling on-line their modifications almost as it types and also by avoiding repeated interactive rebuilds.
+
+Install `sphinx-autobuild` package
+
+.. code-block:: console
+
+	$ pip install sphinx-autobuild
+
+Launch a local web server hosting a draft export of the guide (build this time in `./build/livehtml`)
+
+.. code-block:: console
+
+    $ make livehtml
+
+| Open in the same time the 2 formats of the content to review: the source file and the web page by browsing from the new guide hosted by your local server on `<http://127.0.0.1:8000/NEMO_guide.html>`_.
+| Start the update, save your changes and verify instantly the HTML export in your browser.
+
+.. warning::
+
+    | Your modifications are not taken into account?
+    | For symlink file, you will have to close it to update the HTML export. Otherwise look at the log of the Sphinx build, you probably made a typo!
+
+.. hint::
+
+    Are there broken links? Fix "Page not found" errors by running `make linkcheck`

source/_static/file_crs_def.xml

+    <!-- 
+============================================================================================================
+=                                           output files definition                                        =
+=                                            Define your own files                                         =
+=                                         put the variables you want...                                    =
+============================================================================================================
+    -->
+ <file_definition type="multiple_file" name="PATH_OUT/@expname@_@freq@" sync_freq="1d" min_digits="4">
+
+    <file_group id="1d" output_freq="1d"  split_freq="1d" output_level="10" enabled=".TRUE."> <!-- 1d files -->
+
+       <file id="file1" name_suffix="_gcrsT" description="ocean T grid variables" >
+          <field field_ref="e3t"          name="e3t"       />
+          <field field_ref="toce"         name="votemper"  operation="instant" freq_op="1d" > @toce_e3t / @e3t </field>
+          <field field_ref="soce"         name="vosaline"  operation="instant" freq_op="1d" > @soce_e3t / @e3t </field>
+          <field field_ref="mldkz5"       name="somixhgt"  />
+       </file>
+
+       <file id="file2" name_suffix="_gcrsU" description="ocean T grid variables" >
+          <field field_ref="e3u"       name="e3u"           />
+          <field field_ref="uoce"      name="uo"       operation="instant" freq_op="1d" > @uoce_e3u / @e3u </field>
+       </file>
+
+       <file id="file3" name_suffix="_gcrsV" description="ocean T grid variables" >
+          <field field_ref="e3v"       name="e3v"           />
+          <field field_ref="voce"      name="vo"       operation="instant" freq_op="1d" > @voce_e3v / @e3v </field>
+       </file>
+
+       <file id="file4" name_suffix="_gcrsW" description="ocean T grid variables" >
+          <field field_ref="woce"        name="woce"        />
+          <field field_ref="avt"         name="difvho"   />
+       </file>
+
+       <file id="file5" name_suffix="_gcrsC" description="ocean T grid variables" >
+          <field field_ref="Alkalini" operation="instant" freq_op="1d" > @Alkalini_E3T / @e3t </field>
+          <field field_ref="O2"       operation="instant" freq_op="1d" > @O2_E3T / @e3t </field>
+          <field field_ref="Si"       operation="instant" freq_op="1d" > @Si_E3T / @e3t </field>
+          <field field_ref="PHY"      operation="instant" freq_op="1d" > @PHY_E3T / @e3t </field>
+          <field field_ref="ZOO"      operation="instant" freq_op="1d" > @ZOO_E3T / @e3t </field>
+          <field field_ref="DOC"      operation="instant" freq_op="1d" > @DOC_E3T / @e3t </field>
+          <field field_ref="NCHL"     operation="instant" freq_op="1d" > @NCHL_E3T / @e3t </field>
+          <field field_ref="DCHL"     operation="instant" freq_op="1d" > @DCHL_E3T / @e3t </field>
+          <field field_ref="NO3"      operation="instant" freq_op="1d" > @NO3_E3T / @e3t </field>
+       </file>
+
+    </file_group>
+
+    <file_group id="1mo" output_freq="1mo"  split_freq="1mo" output_level="10" enabled=".TRUE."> <!-- 1d files -->
+
+       <file id="file6" name_suffix="_gcrsC" description="ocean T grid variables" >
+          <field field_ref="DIC"      operation="instant" freq_op="1mo" > @DIC_E3T / @e3t </field>
+          <field field_ref="Alkalini" operation="instant" freq_op="1mo" > @Alkalini_E3T / @e3t </field>
+          <field field_ref="O2"       operation="instant" freq_op="1mo" > @O2_E3T / @e3t </field>
+          <field field_ref="CaCO3"    operation="instant" freq_op="1mo" > @CaCO3_E3T / @e3t </field>
+          <field field_ref="PO4"      operation="instant" freq_op="1mo" > @PO4_E3T / @e3t </field>
+          <field field_ref="POC"      operation="instant" freq_op="1mo" > @POC_E3T / @e3t </field>
+          <field field_ref="Si"       operation="instant" freq_op="1mo" > @Si_E3T / @e3t </field>
+          <field field_ref="PHY"      operation="instant" freq_op="1mo" > @PHY_E3T / @e3t </field>
+          <field field_ref="ZOO"      operation="instant" freq_op="1mo" > @ZOO_E3T / @e3t </field>
+          <field field_ref="DOC"      operation="instant" freq_op="1mo" > @DOC_E3T / @e3t </field>
+          <field field_ref="PHY2"     operation="instant" freq_op="1mo" > @PHY2_E3T / @e3t </field>
+          <field field_ref="ZOO2"     operation="instant" freq_op="1mo" > @ZOO2_E3T / @e3t </field>
+          <field field_ref="DSi"      operation="instant" freq_op="1mo" > @DSi_E3T / @e3t </field>
+          <field field_ref="Fer"      operation="instant" freq_op="1mo" > @Fer_E3T / @e3t </field>
+          <field field_ref="BFe"      operation="instant" freq_op="1mo" > @BFe_E3T / @e3t </field>
+          <field field_ref="GOC"      operation="instant" freq_op="1mo" > @GOC_E3T / @e3t </field>
+          <field field_ref="SFe"      operation="instant" freq_op="1mo" > @SFe_E3T / @e3t </field>
+          <field field_ref="DFe"      operation="instant" freq_op="1mo" > @DFe_E3T / @e3t </field>
+          <field field_ref="GSi"      operation="instant" freq_op="1mo" > @GSi_E3T / @e3t </field>
+          <field field_ref="NFe"      operation="instant" freq_op="1mo" > @NFe_E3T / @e3t </field>
+          <field field_ref="NCHL"     operation="instant" freq_op="1mo" > @NCHL_E3T / @e3t </field>
+          <field field_ref="DCHL"     operation="instant" freq_op="1mo" > @DCHL_E3T / @e3t </field>
+          <field field_ref="NO3"      operation="instant" freq_op="1mo" > @NO3_E3T / @e3t </field>
+          <field field_ref="NH4"      operation="instant" freq_op="1mo" > @NH4_E3T / @e3t </field>
+       </file>
+
+    </file_group>
+
+
+ </file_definition>

source/_static/file_def.xml

+    <!-- 
+============================================================================================================
+=                                           output files definition                                        =
+=                                            Define your own files        default value="9.96921e+36"                                  =
+=                                         put the variables you want...                                    =
+============================================================================================================
+    -->
+    
+    <file_definition type="multiple_file" name="PATH_OUT/@expname@_@freq@" sync_freq="1d" min_digits="4" >
+    
+     
+      <file_group id="1d" output_freq="1d" split_freq="1d" output_level="10" enabled=".TRUE." >  <!-- 5d files -->  
+ 
+	<file id="file1" name_suffix="_gridT" description="ocean T grid variables" >
+          <field field_ref="e3t"          name="e3t"        />
+          <field field_ref="toce"         name="votemper"   operation="instant" freq_op="1d" > @toce_e3t / @e3t </field>
+        </file>
+
+	<file id="file2" name_suffix="_gridS" description="ocean T grid variables" >
+          <field field_ref="soce"         name="vosaline"   operation="instant" freq_op="1d" > @soce_e3t / @e3t </field>
+        </file>
+
+	<file id="file3" name_suffix="_grid2D" description="ocean T grid variables" >
+	  <field field_ref="mldkz5"       name="somixhgt"   /> 
+	  <field field_ref="empmr"        name="sowaflup"   />
+          <field field_ref="empbmr"       name="sowaflupb"  />
+	  <field field_ref="fmmflx"       name="iowaflup"   />
+	  <field field_ref="ice_cover"    name="soicecov"   />
+	  <field field_ref="qsr"          name="soceshwf"   />
+	  <field field_ref="taum"         name="sowindsp"   />
+          <field field_ref="runoffs"      name="runoffs"   />
+        </file>
+	
+	<file id="file4" name_suffix="_gridU" description="ocean U grid variables" >
+          <field field_ref="e3u"          name="e3u"        />
+          <field field_ref="uocetr_eff"   name="uocetr_eff" /> 
+          <field field_ref="utau"         name="tauuo"      />
+        </file>
+	
+	<file id="file5" name_suffix="_gridV" description="ocean V grid variables" >
+          <field field_ref="e3v"          name="e3v"        />
+          <field field_ref="vocetr_eff"   name="vocetr_eff" /> 
+          <field field_ref="vtau"         name="tauvo"      />
+        </file>
+
+        <file id="file6" name_suffix="_gridW" description="ocean W grid variables" >
+          <field field_ref="e3w"          name="e3w"        />
+          <field field_ref="wocetr_eff"   name="wocetr_eff" /> 
+        </file>
+
+        <file id="file7" name_suffix="_gridKZ" description="ocean W grid variables" >
+          <field field_ref="avt"          name="voddmavs"   />
+        </file>
+
+        <file id="file8" name_suffix="_gridH" description="ocean W grid variables" >
+          <field field_ref="hdiv"      name="hdivtr"  long_name="horizontal divergence transport"   operation="average"  freq_op="1d" > @hdiv * @e3t </field> 
+        </file>
+
+      </file_group>
+
+      <file_group id="1mo" output_freq="1mo" split_freq="1mo" output_level="10" enabled=".TRUE." >  <!-- 5d files -->
+
+        <file id="file10" name_suffix="_gridT" description="ocean T grid variables" >
+          <field field_ref="e3t"          name="e3t"        />
+          <field field_ref="toce"         name="votemper"   operation="instant" freq_op="1d" > @toce_e3t / @e3t </field>
+        </file>
+
+        <file id="file11" name_suffix="_gridS" description="ocean T grid variables" >
+          <field field_ref="soce"         name="vosaline"   operation="instant" freq_op="1d" > @soce_e3t / @e3t </field>
+        </file>
+
+        <file id="file12" name_suffix="_grid2D" description="ocean T grid variables" >
+          <field field_ref="mldkz5"       name="somixhgt"   />
+          <field field_ref="empmr"        name="sowaflup"   />
+          <field field_ref="empbmr"       name="sowaflupb"  />
+          <field field_ref="fmmflx"       name="iowaflup"   />
+          <field field_ref="ice_cover"    name="soicecov"   />
+          <field field_ref="qsr"          name="soceshwf"   />
+          <field field_ref="taum"         name="sowindsp"   />
+          <field field_ref="runoffs"      name="runoffs"   />
+        </file>
+
+        <file id="file13" name_suffix="_gridU" description="ocean U grid variables" >
+          <field field_ref="e3u"          name="e3u"        />
+          <field field_ref="uocetr_eff"   name="uocetr_eff" /> 
+          <field field_ref="utau"         name="tauuo"      />
+        </file>
+
+        <file id="file14" name_suffix="_gridV" description="ocean V grid variables" >
+          <field field_ref="e3v"          name="e3v"        />
+          <field field_ref="vocetr_eff"   name="vocetr_eff" /> 
+          <field field_ref="vtau"         name="tauvo"      />
+        </file>
+
+        <file id="file15" name_suffix="_gridW" description="ocean W grid variables" >
+          <field field_ref="e3w"          name="e3w"        />
+          <field field_ref="wocetr_eff"   name="wocetr_eff" /> 
+        </file>
+
+        <file id="file16" name_suffix="_gridKZ" description="ocean W grid variables" >
+          <field field_ref="avt"          name="voddmavs"   />
+        </file>
+
+        <file id="file17" name_suffix="_gridH" description="ocean W grid variables" >
+          <field field_ref="hdiv"      name="hdivtr"  long_name="horizontal divergence transport"   operation="average"  freq_op="1d" > @hdiv * @e3t </field> 
+        </file>
+
+
+      </file_group>
+      
+   </file_definition>