add sphinx documentation (contents) (#2)

* switch to sphinx_rtd_theme
* convert documentation from tex to sphinx using pandoc (fixes needed)
* index.rst: incorporate abstract content and Fig 1
* prep_basic.rst, prep_demo.rst: include figures and treat fig refs
* add the figure files
* add sphinxcontrib-bibtex requirement
* fix quotes, tables, and references
* various fixes and improvements.
* document octave branch, grid directories, and doInteractive option
* add links for Octave and m_map

docs/bibli.bib

@@ -0,0 +1,63 @@
+@string{angl    = {Ann.\ Glaciol.}}
+@string{arfm  = {Annu.~Rev.~Fluid Mech.}}
+@string{bams  = {Bull.~Am.~Met.~Soc.}}
+@string{blm = {Bound.~Layer~Meteorol.}}
+@string{climd = {Clim.~Dynamics}}
+@string{cch     = {Clim.\ Change}}
+@string{cup = {Cambridge University Press}}
+@string{dao     = {Dyn.~Atmos.~Oceans}}
+@string{dkrz  = {Deutsches Klimarechenzentrum (DKRZ)}}
+@string{dnmi  = {The Norwegian Meteorological Institute (DNMI)}}
+@string{dsr = {Deep Sea Res.}}
+@string{ecmwf = {ECMWF}}
+@string{eos     = {Eos~Trans.\ AGU}}
+@string{esa = {European Space Agency (ESA)}}
+@string{esapub  = {ESA Publications Division, ESTEC, Noordwijk (NL)}}
+@string{estec = {European Space Research and Technology Centre (ESTEC)}}
+@string{gaos  = {Global Atmos.~Ocean System}}
+@string{grl = {Geophys.~Res.~Lett.}}
+@string{ieee  = {IEEE Trans.~Geosci. Remote Sensing}}
+@string{ifremer = {IFREMER/CERSAT}}
+@string{igarss  = {IEEE Press, Piscataway, N.J., USA}}
+@string{jam = {J.~Appl.~Meteor.}}
+@string{jaot  = {J.~Atmos.~Ocean.~Technol.}}
+@string{jas = {J.~Atmos.~Sci.}}
+@string{jclim = {J.~Clim.}}
+@string{jcp = {J.~Comput.~Phys.}}
+@string{jfm = {J.~Fluid Mech.}}
+@string{jgr = {J.~Geophys.~Res.}}
+@string{ijrs  = {Int.~J.~Remote Sensing}}
+@string{jms = {J.~Mar.~Sys.}}
+@string{jpo = {J.~Phys.~Oceanogr.}}
+@string{mpi = {MPI f\"ur Meteorologie}}
+@string{mcp = {Meth. Comput. Phys.}}
+@string{mwr     = {Mon.~Wea.~Rev.}}
+@string{om  = {Ocean Modelling}}
+@string{pf = {Physics of Fluids}}
+@string{pd = {Physica D.}}
+@string{ptrsl   = {{Phil.~Trans.~R.~Soc.~Lond.}}}
+@string{rgsp = {{Rev.~Geophys.~Space~Phys.}}}
+@string{qjrms   = {{Q.~J.~R.~Meteorol.~Soc.}}}
+@string{siscicom= {SIAM J.\ Sci.\ Comput.}}
+@string{tel = {Tellus}}
+
+@Article{for-eta:15,
+ author         = {Forget, G. and Campin, J.-M. and Heimbach, P. and Hill, C. N. and Ponte, R. M and Wunsch, C.},
+ title          = {{ECCO} version 4: an integrated framework for non-linear inverse modeling and global ocean state estimation},
+ journal        = {Geoscientific Model Development},
+ volume         = {8},
+ year           = {2015},
+ number         = {10},
+ pages          = {3071--3104},
+ url            = {http://www.geosci-model-dev.net/8/3071/2015/},
+ doi            = {10.5194/gmd-8-3071-2015}
+}
+
+@Article{dspace-eccov4r2,
+ AUTHOR   = {Forget, G. and Campin, J.-M. and Heimbach, P. and Hill, C. N. and Ponte, R. M and Wunsch, C.},
+ TITLE    = {{ECCO} version 4: Second Release},
+ YEAR     = {2016},
+ journal  = {},
+ URL      = {http://hdl.handle.net/1721.1/102062}
+}
+

docs/biblirefs.rst

@@ -0,0 +1,10 @@
+.. _references:
+
+.. only:: html
+
+   References
+   **********
+
+.. bibliography:: bibli.bib
+   :all:
+

docs/conf.py

@@ -30,7 +30,10 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['sphinx.ext.autodoc',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.viewcode',
+    'sphinxcontrib.bibtex']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -76,13 +79,30 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# number figures
+
+numfig_format = {'figure': 'Figure %s',
+                 'table': 'Table %s',
+                 'code-block': 'Code %s',
+                }
+
+numfig = True
+
+# number figures within section
+numfig_secnum_depth = 1
+
+#math_number_all = True
+
+numfig_format = {'figure': 'Figure %s', 'table': 'Table %s', 'code-block': 'Listing %s', 'section': 'Section %s'}
 
 # -- 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 = 'alabaster'
+import sphinx_rtd_theme
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -93,7 +113,9 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+### gf: the following is commented to avoid warning
+### gf: see https://github.com/terasolunaorg/guideline/issues/1358
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/gcmfaces_demo_dirtree.rst

@@ -0,0 +1,18 @@
+
+::
+
+   gcmfaces/ (Matlab / Octave toolbox)
+   MITprof/ (Matlab / Octave toolbox)
+   m_map/ (Matlab / Octave toolbox)
+   nctiles_grid/ (downloaded data)
+   release2_climatology/
+       nctiles_climatology/ (downloaded data)
+       mat/ (created by software)
+       tex/ (created by software)
+   release2/
+       nctiles_monthly/ (downloaded data)
+       nctiles_remotesensing/ (downloaded data)
+       profiles/ (downloaded data)
+       mat/ (created by software)
+       tex/ (created by software)
+

docs/index.rst

@@ -3,14 +3,50 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to gcmfaces's documentation!
-====================================
+Welcome to gcmfaces' documentation!
+===================================
+
+.. A Generic Treatment Of Gridded Earth Variables In Matlab And Octave.
+
+Here, you will learn about the `gcmfaces` toolbox that provides a generic
+treatment of gridded Earth variables in Matlab and Octave.
+
+The `gcmfaces` toolbox handles gridded Earth variables as sets of connected
+arrays. This object-oriented approach allows users to
+write generic, compact analysis codes that readily become applicable
+to a wide variety of grids (e.g., those in :numref:`sphere_all`).
+`gcmfaces` notably allows for analysis of MITgcm output on any of its
+`familiar grids <ftp://mit.ecco-group.org/ecco_for_las/version_4/grids/>`__.
+It was originally developed as part the `ECCO version 4` framework along with
+the companion `MITprof` toolbox that handles unevenly
+distributed in-situ ocean observations :cite:`for-eta:15`.
+
+This user manual provides an installation guide for `gcmfaces` and `MITprof`
+(:numref:`install`), a documentation of the basic `gcmfaces` features
+(:numref:`features`), and an overview of higher-level `gcmfaces` functionalities
+for mapping, transport, etc. operations (:numref:`demo` and :numref:`standard`).
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :maxdepth: 3
+   :caption: Contents
+   :numbered: 4
+
+   prep_install.rst
+   prep_basic.rst
+   prep_demo.rst
+   prep_diags.rst
+   biblirefs.rst
+
+Sample grids
+============
 
+.. figure:: figs/sphere_all.pdf
+   :width: 95%
+   :align: center
+   :alt: TBD
+   :name: sphere_all
 
+   Four approaches to gridding the Earth which are all commonly used in numerical models. Top left: lat-lon grid; mapping the Earth to a single rectangular array (`face`). Top right: cube-sphere grid; mapping the earth to the six faces of a cube. Bottom right: lat-lon-cap, `LLC`, grid (five faces). Bottom left: quadripolar grid (four faces). In this depiction, faces are color-coded, only grid line subsets are shown, and gaps are introduced between faces to highlight the defining characteristics of each grid.
 
 Indices and tables
 ==================