revised sphinx documentation (#9)

* Clean-up the tools section and add reference to I. Fenty's python tutorial.
* Move sections 2.1 and 2.2 to separate rst files
* move the directory tree depiction to a separate file (eccov4r2_dirtree.rst) which is
  now included inside of downloads.rst (rather than runs.rst) after eccov4r2_setup.rst
* revise eccov4r2_setup.rst (download instructions) and the beginning of runs.rst
* mostly cosmetic edits to downloads.rst and the beginning of runs.rst
* revise "Re-Run Other Solutions" and add release 3 at the top
* revise opening pargraphs and section titles
* general clean up of sphinx documentation

docs/downloads.rst

@@ -1,15 +1,10 @@
 
 .. _downloads:
 
-Downloading ECCO Version 4
-**************************
+Downloading
+***********
 
-This section provides directions to download the ECCO v4 r2 output 
-(:numref:`download-solution`), the underlying model setup 
-(:numref:`download-setup`) that can be used to re-run ECCO v4 r2 
-(:numref:`eccov4-baseline`), `Matlab` tools to analyze ECCO v4 r2 and
-other model output (:numref:`download-analysis`), and a list of
-additional resources (:numref:`other-resources`).
+This section provides directions to download the `ECCO v4 r2` output (:numref:`download-solution`), the underlying model setup that can be used to re-run `ECCO v4 r2` (:numref:`download-setup`), tools for manipulating and analyzing model output (:numref:`download-analysis`), and a list of additional resources (:numref:`other-resources`).
 
 .. _download-solution:
 
@@ -25,8 +20,7 @@ The Release 2 Setup
 
 .. include:: eccov4r2_setup.rst
 
-The :ref:`mitgcmdirs` is shown below. While organizing the downloaded directories differently is certainly possible, the :numref:`eccov4-baseline` instructions to :ref:`baseline` the model and :ref:`testreportecco` are based on this organization.
-
+The :ref:`mitgcmdirs` is shown below. While organizing the downloaded directories differently is certainly possible, the :numref:`eccov4-baseline` instructions to :ref:`baseline` the model and :ref:`testreportecco` are based on this organization. 
 
 .. _mitgcmdirs:
 
@@ -39,38 +33,35 @@ The :ref:`mitgcmdirs` is shown below. While organizing the downloaded directorie
 The Gcmfaces Toolbox
 --------------------
 
-The `gcmfaces` toolbox :cite:`for-eta:15` can be used to analyze model output that has either been downloaded (:numref:`download-solution`) or reproduced (:numref:`eccov4-baseline`) by user. Matlab and Octave implementations are available in `this repository <https://github.com/gaelforget/gcmfaces>`__. They can be installed by typing, at the command line, either
+The `gcmfaces` toolbox :cite:`for-eta:15` can be used to analyze model output that has either been downloaded (:numref:`download-solution`) or reproduced (:numref:`eccov4-baseline`) by users. From the command line, you can install either the `Matlab` version by executing:
 
 :: 
 
     git clone https://github.com/gaelforget/gcmfaces
 
-or
+or the `Octave` version by executing:
 
 ::
 
     git clone -b octave https://github.com/gaelforget/gcmfaces
 
-It can be used, for example, to reproduce the ECCO v4 standard analysis (i.e., the plots included in :cite:`dspace-eccov4r2` for ECCO v4 r2) from the released model output (:numref:`download-solution`) or from the plain, binary, model output (:numref:`eccov4-baseline`). Documentation for `gcmfaces` is provided in the `github repository <https://github.com/gaelforget/gcmfaces>`__.
-
+The `gcmfaces` toolbox can be used, for example, to reproduce the `ECCO v4` standard analysis (i.e., the plots included in :cite:`dspace-eccov4r2` for `ECCO v4 r2`) from the released model output (:numref:`download-solution`) or from the plain, binary, model output (:numref:`eccov4-baseline`). Detailed documentation is provided by ``gcmfaces.pdf`` within the `github repository <https://github.com/gaelforget/gcmfaces>`__.
 
 .. _other-resources:
 
 Other Resources
 ---------------
 
--  A series of three presentations given at the May 2016 `MIT` ECCO meeting provides an overview of the ECCO v4 data sets and applications
+-  A series of three presentations given during the May 2016 `ECCO` meeting at `MIT` provides an overview of `ECCO v4` data sets, capabilities, and applications
    (`Overview <http://doi.org/10.13140/RG.2.2.33361.12647>`__;
    `Processes <http://doi.org/10.13140/RG.2.2.26650.24001>`__;
    `Tracers <http://doi.org/10.13140/RG.2.2.36716.56967>`__).
 
--  Various Python tools are available for analysis purposes (see `this Python tutorial <https://github.com/ECCO-GROUP/ECCO-v4-Python-Tutorial>`__).
+-  Various Python tools are available to analyse model output (see, e.g., `this tutorial <https://github.com/ECCO-GROUP/ECCO-v4-Python-Tutorial>`__).
 
 -  Any `netcdf` enabled software such as `Panoply <http://www.giss.nasa.gov/tools/panoply/>`__ (available for `MS-Windows`, `Linux`, or `macOS`) can be used to plot the interpolated output (``interp_*`` directories).
 
--  The stand-alone `eccov4_lonlat.m <http://mit.ecco-group.org/opendap/ecco_for_las/version_4/release2/doc/eccov4_lonlat.m>`__ `Matlab` script can alternatively be used to extract the lat-lon sector, which spans the 69S to 56N latitude range, of native grid fields :cite:`for-eta:15`.
-
--  The MITgcm ``utils/`` directory provides basic `Matlab` and `Python` functionalities.
+-  The stand-alone `eccov4_lonlat.m <http://mit.ecco-group.org/opendap/ecco_for_las/version_4/release2/doc/eccov4_lonlat.m>`__ program can be used to extract the lat-lon sector, which spans the 69S to 56N latitude range, of native grid fields :cite:`for-eta:15`.
 
--  ECCO v4 estimates can be plotted via the `NASA` `Sea Level Change Portal <https://sealevel.nasa.gov>`__ tools (interpolated output) or downloaded from the `Harvard Dataverse <https://dataverse.harvard.edu>`__ APIs (native grid input and output).
+-  `ECCO v4` estimates can be plotted via the `NASA` `Sea Level Change Portal <https://sealevel.nasa.gov>`__ tools (interpolated output) or downloaded from the `Harvard Dataverse <https://dataverse.harvard.edu>`__ APIs (native grid input and output).
 

docs/eccov4r2_dirtree.rst

@@ -16,3 +16,7 @@
          forcing_baseline2/    (user installed)
          inputs_baseline2/     (user installed)
 
+.. note::
+
+   Some subdirectories are omitted in this depiction.
+

docs/eccov4r2_output.rst

@@ -1,12 +1,11 @@
 
-The ECCO v4 r2 state estimate output is permanently archived within the `Harvard Dataverse <https://dataverse.harvard.edu/dataverse/ECCOv4r2>`__ that provides citable identifiers for the various datasets as reported in this `README.pdf <https://dataverse.harvard.edu/api/access/datafile/2863409>`__. For download purposes, the ECCO v4 r2 output is also made available via this `ftp
-server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/>`__ by the `ECCO Consortium <http://ecco-group.org>`__. The various directory contents are summarized in this `README <http://mit.ecco-group.org/opendap/ecco_for_las/version_4/release2/README>`__ and specific details are provided in each subdirectory’s README. Under Linux or macOS for instance, a simple download method consists in using ``wget`` at the command line by typing
+The `ECCO v4 r2` state estimate output is permanently archived within the `Harvard Dataverse <https://dataverse.harvard.edu/dataverse/ECCOv4r2>`__ that provides citable identifiers for the various datasets as reported in this `README.pdf <https://dataverse.harvard.edu/api/access/datafile/2863409>`__. For direct download purposes, the `ECCO v4 r2` output is also made available via this `ftp server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/>`__ by the `ECCO Consortium <http://ecco-group.org>`__. The various directory contents are summarized in this `README <http://mit.ecco-group.org/opendap/ecco_for_las/version_4/release2/README>`__ and specific details are provided in each subdirectory’s README. Under Linux or macOS for instance, a simple download method consists in using ``wget`` at the command line by typing
 
 ::
 
     wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/nctiles_grid
     wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/nctiles_climatology
     wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/nctiles_monthly
 
-and similarly for the other directories. The ``nctiles_`` directory prefix indicates that contents are provided on the native LLC90 grid in the nctiles format :cite:`for-eta:15` which can be read in `Matlab` using the `gcmfaces` toolbox (see :numref:`download-analysis`). Alternatively users can download interpolated fields, on a :math:`1/2\times1/2^\circ` grid in the netcdf format, from the ``interp_*`` directories. The ``input_*`` directories contain binary and netcdf input files that can be read by `MITgcm` (:numref:`download-setup` and :numref:`eccov4-baseline`). The ``profiles/`` directory (`see ftp server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/profiles/>`_) additionally contains the MITprof collections of collocated in situ and state estimate profiles in `netcdf` format :cite:`for-eta:15`.
+and similarly for the other directories. The ``nctiles_`` directory prefix indicates that contents are provided on the native LLC90 grid in the nctiles format :cite:`for-eta:15` which can be read in `Matlab` using the `gcmfaces` toolbox (see :numref:`download-analysis`). Alternatively users can download interpolated fields, on a :math:`1/2\times1/2^\circ` grid in the netcdf format, from the ``interp_*`` directories. The ``input_*`` directories contain binary and netcdf input files that can be read by `MITgcm` (:numref:`eccov4-baseline`). The ``profiles/`` directory additionally contains the MITprof, netcdf collections of collocated in situ and state estimate profiles :cite:`for-eta:15`.
 

docs/eccov4r2_setup.rst

@@ -4,12 +4,11 @@ Users can donwload the `MITgcm` from `this github repository <https://github.com
 ::
 
     git clone https://github.com/MITgcm/MITgcm
+    git clone https://github.com/gaelforget/ECCO_v4_r2
     mkdir MITgcm/mysetups
     mv ECCO_v4_r2 MITgcm/mysetups/.
-    cd MITgcm/mysetups
-    git clone https://github.com/gaelforget/ECCO_v4_r2
 
-Re-running ECCO v4 r2 additionally requires downloading surface forcing input (96G of 6-hourly fields in ECCO v4 r2), initial condition, grid, etc. input (610M), and observational input (25G) either from the `Harvard Dataverse <https://dataverse.harvard.edu/dataverse/ECCOv4r2inputs>`__ permanent archive or from the `ECCO ftp server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/>`__ as follows:
+Re-running `ECCO v4 r2` additionally requires downloading surface forcing input (96G of 6-hourly fields in `ECCO v4 r2`), initial condition, grid, etc. input (610M), and observational input (25G) either from the `Harvard Dataverse <https://dataverse.harvard.edu/dataverse/ECCOv4r2inputs>`__ permanent archive or directly from the `ECCO ftp server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/>`__ as follows:
 
 ::
 

docs/index.rst

@@ -6,14 +6,14 @@
 Welcome to ECCO version 4's documentation!
 ==========================================
 
-Here, you will learn about simple methods that allow you to download, analyze, rerun, or modify ECCO and MITgcm solutions. Estimating the Circulation and Climate of the Ocean, version 4, release 2 (`ECCO v4 r2`) is used as a representative example before documenting newer solutions and additional resources associated with the MIT general circulation model (`MITgcm`).
+Here, you will learn about simple methods that are available to download, analyze, rerun, or modify `ECCO version 4` and `MITgcm` solutions. In the :ref:`downloads` and :ref:`runs` section, the `ECCO v4 r2` solution is taken as an example before reviewing other solutions and additional resources. For an overview of the `ECCO version 4` framework, please refer to :cite:`for-eta:15`.
 
 .. toctree::
    :maxdepth: 3
    :caption: Contents:
    :numbered: 4
 
-   overview.rst
+   introduction.rst
    downloads.rst
    runs.rst
    biblirefs.rst

docs/introduction.rst

@@ -0,0 +1,17 @@
+
+.. _introduction:
+
+Introduction
+************
+
+`ECCO v4 r2` is an ocean state estimate and solution of the `MIT` general circulation model (`MITgcm`) that covers the period from 1992 to 2011 :cite:`dspace-eccov4r2`. It is a minor update of the original `ECCO v4 r1` solution :cite:`for-eta:15` that 
+
+#. benefits from a few additional corrections listed in :cite:`dspace-eccov4r2`
+
+#. is provided with additional model-data misfit and model budget output
+
+#. has become easier to rerun than `ECCO v4 r1`. 
+
+
+The :ref:`downloads` section provides an installation guide and links to various analysis tools. The :ref:`runs` section provides simple instructions to rerun model solutions, which can be useful to generate additional output for example, and start experimenting with the model.
+