Changeset 10602 for NEMO/trunk/README.rst

Timestamp:

2019-01-28T22:58:17+01:00 (4 years ago)

Author:

nicolasmartin

Message:

Review global README and the layout of the guide
Gather release notes, contributing and definitions in Miscellaneous TOC entry

File:

• NEMO/trunk/README.rst (modified) (1 diff)

NEMO/trunk/README.rst

@@ -1 @@
-NEMO_ for **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,
+:Release: |version|
+:Date:    |today|
+
+NEMO_ for **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 a European consortium since 2008.
+
+.. contents::
+   :local:
 
 Overview
 ========
 
-The NEMO_ ocean model has 3 major components:
+The NEMO ocean model has 3 major components:
 
-- **OCE** models the ocean [thermo]dynamics and solves the primitive equations (``./src/OCE``)
-- **SI3** simulates seaice [thermo]dynamics, brine inclusions and subgrid-scale thickness variations (``./src/ICE``)
-- **TOP** models the [on|off]line oceanic tracers transport and biogeochemical processes (``./src/TOP``)
+- |OPA| models the ocean {thermo}dynamics and solves the primitive equations
+  (``./src/OCE``)
+- |SI3| simulates seaice {thermo}dynamics, brine inclusions and subgrid-scale thickness variations
+  (``./src/ICE``)
+- |TOP| models the {on,off}line oceanic tracers transport and biogeochemical processes
+  (``./src/TOP``)
 
-These physical core engines are described in their respective `reference documentation`_ that must be cited for any work related to their use.
+These physical core engines are described in their respective `references`_ that
+must be cited for any work related to their use.
 
-Assets and ready-to-use solutions
-=================================
+Assets and solutions
+====================
 
-Not only does the NEMO_ framework model the ocean circulation, it offers various features to enable
+Not only does the NEMO framework model the ocean circulation,
+it offers various features to enable
 
-- Create embedded zoom seamlessly thanks to 2-way nesting package AGRIF_.
-- Opportunity to integrate an `external biogeochemistry model`_ 
-- Versatile data_assimilation (``./src/OBS``)
-- Generation of diagnostics through effective XIOS_ system
-- Roll-out Earth system modeling with coupling interface based on OASIS_
+- Create :doc:`embedded zooms<zooms>` seamlessly thanks to 2-way nesting package AGRIF_.
+- Opportunity to integrate an :doc:`external biogeochemistry model<tracers>`
+- Versatile :doc:`data assimilation<data_assimilation>`
+- Generation of :doc:`diagnostics<diagnostics>` through effective XIOS_ system
+- Roll-out Earth system modeling with :doc:`coupling interface<coupling>` based on OASIS_
 
-Several built-in configurations are provided to evaluate the skills and performances of the model which can be used as templates for setting up a new configurations (``./cfgs``).
+Several :doc:`built-in configurations<configurations>` are provided to
+evaluate the skills and performances of the model which
+can be used as templates for setting up a new configurations (``./cfgs``).
 
-NEMO user can also checkout available idealized test cases that address specific physical processes(``./tests``).
+The user can also checkout available :doc:`idealized test cases<test_cases>` that
+address specific physical processes(``./tests``).
 
-A set of utilities is also provided to {pre,post}process your data (``./tools``).
+A set of :doc:`utilities <tools>` is also provided to {pre,post}process your data (``./tools``).
 
-Documentation and references
-============================
+Project documentation
+=====================
 
-A walkthrough tutorial illustrates how to get code dependencies, compile and execute NEMO (``./INSTALL.rst``) . 
+A walkthrough tutorial illustrates how to get code dependencies, compile and execute NEMO
+(``./INSTALL.rst``) . 
 
-Reference manuals and quick start guide can be build from source and exported to HTML or PDF formats (``./doc``) or downloaded directly from the NEMO_ website.
+Reference manuals and quick start guide can be build from source and
+exported to HTML or PDF formats (``./doc``) or
+downloaded directly from the :website:`website<bibliography/documentation>`.
 
-=========== =================== ===================
- Component    Reference Manual   Quick start
-=========== =================== ===================
- OCE          `NEMO manual`_     `NEMO guide`_
- SI3          `SI3 manual`_
- TOP          `TOP manual`_      
-=========== =================== ===================
+=========== ===================== ===============
+ Component   Reference Manual      Quick start
+=========== ===================== ===============
+ |OPA|       |NEMO manual|_        |NEMO guide|_
+             :cite:`NEMO_manual`
+ |SI3|       |SI3 manual|_
+             :cite:`SI3_manual`
+ |TOP|       |TOP manual|_
+             :cite:`TOP_manual`
+=========== ===================== ===============
 
-Since 2014 the project has a `Special Issue`_ in the open-access journal Geoscientific Model Development (GMD) from the European Geosciences Union (EGU).
-The main scope is to collect relevant manuscripts covering various topics and to provide a single portal to assess the model potential and evolution.
+Since 2014 the project has a `Special Issue`_ in the open-access journal
+Geoscientific Model Development (GMD) from the European Geosciences Union (EGU).
+The main scope is to collect relevant manuscripts covering various topics and
+to provide a single portal to assess the model potential and evolution.
 
-Used by a wide audience, numerous `associated projects`_ have been carried out and extensive `bibliography`_ published.
+Used by a wide audience,
+numerous :website:`associated projects<projects>` have been carried out and
+extensive :website:`bibliography<bibliography/publications>` published.
 
-NEMO Consortium
-===============
+Development board
+=================
 
-The NEMO Consortium pulling together 5 European institutes (CMCC_, CNRS_, MOI_, `Met Office`_ and NERC_) plans the sustainable development in order to keep a reliable evolving framework since 2008.
+The NEMO Consortium pulling together 5 European institutes (CMCC_, CNRS_, MOI_, `Met Office`_ and NERC_)
+plans the sustainable development in order to keep a reliable evolving framework since 2008.
 
-It defines the NEMO strategy that is implemented by the System Team on a yearly basis in order to release a new version almost every four years.
+It defines the |NEMO strategy|_ that is implemented by the System Team on a yearly basis in order to
+release a new version almost every four years.
 
-When the need arises, `working groups`_ are created or resumed to gather the community expertise for advising on the development activities.
+When the need arises, :forge:`working groups<wiki/WorkingGroups>` are created or resumed to
+gather the community expertise for advising on the development activities.
 
-..  _external biogeochemistry model : http://forge.ipsl.jussieu.fr/nemo/wiki/WorkingGroups/TOP/TOP-UserQuickGuide
-.. _working groups : https://forge.ipsl.jussieu.fr/nemo/wiki/WorkingGroups
-.. _reference documentation : https://www.nemo-ocean.eu/bibliography/documentation/
-.. _Special Issue : http://www.geosci-model-dev.net/special_issue40.html
-.. _associated projects : https://www.nemo-ocean.eu/projects/
-.. _bibliography : https://www.nemo-ocean.eu/wp-content/plugins/wp-bibtexbrowser/bibtexbrowser.php?bib=nemo.bib
+
+.. Substitutions / Links
+
+.. |NEMO manual| image:: http://zenodo.org/badge/DOI/10.5281/zenodo.1464816.svg
+.. |NEMO guide|  image:: http://zenodo.org/badge/DOI/10.5281/zenodo.1475325.svg
+.. |SI3 manual|  image:: http://zenodo.org/badge/DOI/10.5281/zenodo.1471689.svg
+.. |TOP manual|  image:: http://zenodo.org/badge/DOI/10.5281/zenodo.1471700.svg
+
+.. |NEMO strategy| replace:: multi-year development strategy
+
+.. _Special Issue: http://www.geosci-model-dev.net/special_issue40.html