Docs overhaul (#1290)

* Docs overhaul * Few more tweaks to new theme
OGGM · Sep 17, 2021 · f000283 · f000283
1 parent c03212f
commit f000283
Show file tree

Hide file tree

Showing 26 changed files with 986 additions and 548 deletions.
diff --git a/docs/api.rst b/docs/api.rst
@@ -166,6 +166,8 @@ the majority of OGGM's tasks). They are parallelizable.
     tasks.copy_to_basedir
     tasks.gdir_to_tar
 
+.. _apiglobaltasks:
+
 Global tasks
 ============
 

diff --git a/docs/assets.rst b/docs/assets.rst
@@ -22,11 +22,11 @@ The following files are available:
 
 If you use these data, please cite `Maussion et al., 2019 <https://gmd.copernicus.org/articles/12/909/2019/>`_.
 
-    .. figure:: _static/assets_shapes.png
-        :width: 100%
+.. figure:: _static/assets_shapes.png
+    :width: 100%
+    :align: left
 
-
-        Shapefile of OGGM's flowlines and widths for a subset of RGI region 15
+    Shapefile of OGGM's flowlines and widths for a subset of RGI region 15
 
 
 RGI-TOPO
@@ -37,10 +37,11 @@ provides a local topography map for each single glacier in the RGI (currently ve
 It was generated with OGGM, and can be used very easily from the :ref:`shop` (visit
 our :ref:`tutorials` if you want to learn how to use them!).
 
-    .. figure:: _static/malaspina_topo.png
-        :width: 100%
+.. figure:: _static/malaspina_topo.png
+    :width: 100%
+    :align: left
 
-        Example of the various RGI-TOPO products at Malaspina glacier
+    Example of the various RGI-TOPO products at Malaspina glacier
 
 
 Useful data tables

diff --git a/docs/citing-oggm.rst b/docs/citing-oggm.rst
@@ -36,18 +36,20 @@ Software DOI
 If you want to refer to a specific version of the software you can use
 the `Zenodo citation`_ for this purpose. An example BibTeX entry::
 
-    @misc{OGGM_v1.1,
-    author       = {Fabien Maussion and Timo Rothenpieler and
-                    Matthias Dusch and Beatriz Recinos and Anouk Vlug and
-                    Ben Marzeion and Johannes Landmann and Julia Eis and
-                    Sadie Bartholomew and Nicolas Champollion and
-                    Philipp Gregor and Anton Butenko and Schmitty Smith and
-                    Moritz Oberrauch},
-    title        = {OGGM/oggm: v1.1},
-    month        = feb,
-    year         = 2019,
-    doi          = {10.5281/zenodo.2580277},
-    url          = {https://doi.org/10.5281/zenodo.2580277}
+    @misc{OGGM_v1.5.2,
+    author       = {Fabien Maussion and Timo Rothenpieler and Matthias Dusch and
+                    Anouk Vlug and Nicolas Champollion and Ben Marzeion and Lilian Schuster and
+                    Moritz Oberrauch and Fei Li and Johannes Landmann and Julia Eis and
+                    Alex Jarosch and Sarah Hanus and David Rounce and Matteo Castellani and
+                    Sadie L. Bartholomew and Chris Merrill and David Loibl and Lizz Ultee and
+                    Schmitty Smith and Anton Butenko and Patrick Schmitt and Philipp Gregor},
+    title        = {OGGM/oggm: v1.5.2},
+    month        = aug,
+    year         = 2021,
+    publisher    = {Zenodo},
+    version      = {v1.5.2},
+    doi          = {10.5281/zenodo.5327634},
+    url          = {https://doi.org/10.5281/zenodo.5327634}
     }
 
 .. _Zenodo citation: https://zenodo.org/badge/latestdoi/43965645

diff --git a/docs/conf.py b/docs/conf.py
@@ -1,4 +1,3 @@
-from __future__ import print_function
 # -*- coding: utf-8 -*-
 #
 # OGGM documentation build configuration file, created by
@@ -118,6 +117,7 @@
     'numpydoc',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
+    'sphinx_togglebutton',
     'IPython.sphinxext.ipython_directive',
     'IPython.sphinxext.ipython_console_highlighting',
 ]
@@ -210,14 +210,22 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+# html_theme = 'sphinx_rtd_theme'
+html_theme = 'sphinx_book_theme'
 
 # 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
 # documentation.
 html_theme_options = {
     'logo_only': True,
-    'display_version': False,
+    "repository_url": "https://github.com/OGGM/oggm",
+    "use_repository_button": True,
+    "use_issues_button": True,
+    "use_edit_page_button": True,
+    "path_to_docs": "docs",
+    # "home_page_in_toc": True,
+    "toc_title": 'On this page',
+    # 'display_version': False,
 }
 
 # Add any paths that contain custom themes here, relative to this directory.

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -116,6 +116,14 @@ e.g.
 
 If you need some specific variables, please write on GitHub and we can discuss.
 
+
+
+Which type of flowlines should I use: elevation bands or multiple?
+------------------------------------------------------------------
+
+We have written a documentation chapter about the :ref:`flprocons`.
+
+
 Troubleshooting
 ===============
 

diff --git a/docs/flowlines.rst b/docs/flowlines.rst
@@ -5,7 +5,6 @@
 Glacier flowlines
 =================
 
-
 .. ipython:: python
    :suppress:
 
@@ -19,22 +18,20 @@ Glacier flowlines
 
     from oggm import graphics
 
-Computing the flowlines is the first task to run after the definition
-of the local map and topography.
-
-OGGM is a "flowline model", which means that the glacier ice flow is
+OGGM's default model is a "flowline model", which means that the glacier ice flow is
 assumed to happen along a representative "1.5D" flowline, as in the image
 below. "1.5D" here is used to emphasize that although glacier ice can flow
 only in one direction along the flowline, each point of the glacier has
 a geometrical width. This width means that flowline glaciers are able to match
 the observed area-elevation distribution of true glaciers, and can parametrize
 the changes in glacier width with thickness changes.
 
-    .. figure:: _static/hef_flowline.jpg
-        :width: 80%
+.. figure:: _static/hef_flowline.jpg
+   :width: 80%
+   :align: left
 
-        Example of a glacier flowline. Background image from
-        http://www.swisseduc.ch/glaciers/alps/hintereisferner/index-de.html
+   Example of a glacier flowline. Background image from
+   http://www.swisseduc.ch/glaciers/alps/hintereisferner/index-de.html
 
 .. admonition:: **New in version 1.4!**
 
@@ -47,8 +44,9 @@ the changes in glacier width with thickness changes.
       averaging of 2D slopes into a "bulk" flowline glacier. This is the method
       first developed and applied by [Huss_Farinotti_2012]_.
 
-   Both methods have strengths and weaknesses, which we discuss in more depth
-   below. First, let's have a look at how they work.
+
+Both methods have strengths and weaknesses, which we discuss in more depth
+below. First, let's have a look at how they work.
 
 
 Geometrical centerlines
@@ -204,25 +202,28 @@ elevation-band flowline per glacier, while there can be several geometrical
 centerlines. The downstream lines are computed the same way for both the
 elevation-band and geometrical flowlines.
 
-    .. figure:: _static/flowchart_flowlines.png
-        :width: 100%
+.. figure:: _static/flowchart_flowlines.png
+   :width: 100%
+   :align: left
 
-        Flowchart illustrating the different ways to compute the flowlines
-        and at which point in the workflow they can be treated equivalently
+   Flowchart illustrating the different ways to compute the flowlines
+   and at which point in the workflow they can be treated equivalently
 
 Both flowline types are available for download and for use in the OGGM
 framework. The plot below has been obtained from the
 `centerlines versus elevation-band flowlines comparison tutorial <https://oggm.org/tutorials/notebooks/elevation_bands_vs_centerlines.html>`_.
 
 
-    .. figure:: _static/eb_vs_cl.png
-        :width: 100%
+.. figure:: _static/eb_vs_cl.png
+   :width: 100%
+   :align: left
 
-        Cross-sections of the two flowline types at the example Hintereisferner
-        with OGGM version 1.4. Note the different lengths. The main flowline in
-        the geometrical centerline case does not reach as high here because
-        other flowlines (tributaries) are higher for this glacier.
+   Cross-sections of the two flowline types at the example Hintereisferner
+   with OGGM version 1.4. Note the different lengths. The main flowline in
+   the geometrical centerline case does not reach as high here because
+   other flowlines (tributaries) are higher for this glacier.
 
+.. _flprocons:
 
 Pros and cons of both methods
 -----------------------------
@@ -241,63 +242,68 @@ Geometrical centerlines
 
 - Pros:
 
-   - Closer to the "true" length of the glacier.
-   - Grid points along the centerlines preserve their geometrical information,
-     i.e. one can compute the exact location of ice thickness change.
-   - It is possibile to have different model parameters for each flowline (e.g.
-     different mass-balance models), although this is comming with its own
-     challenges.
-   - Arguably: better suitability for mass-balance parameterizations taking
-     glacier geometry and exposition into account.
-   - Arguably: better representation of the main glacier flow?
+  - Closer to the "true" length of the glacier.
+  - Grid points along the centerlines preserve their geometrical information,
+    i.e. one can compute the exact location of ice thickness change.
+  - It is possibile to have different model parameters for each flowline (e.g.
+    different mass-balance models), although this is comming with its own
+    challenges.
+  - Arguably: better suitability for mass-balance parameterizations taking
+    glacier geometry and exposition into account.
+  - Arguably: better representation of the main glacier flow?
 
 - Cons:
 
-   - Complex and error prone: considerably more code than the elevation band
-     flowlines.
-   - Less robust: more glaciers are failing in the preprocessing than with
-     the simpler method.
-     When glaciers are badly outlined (or worse, when ice caps are not
-     properly divided), or with bad DEMs, the geometrical flowline
-     can "look" very ugly.
-   - Computationally expensive (more grid points on average, more prone
-     to numerical instabilities).
-   - Complex handling of mass-balance parameters for tributaries at the
-     inversion (leading to multiple temperature sensitivity parameters
-     for large glaciers).
+  - Complex and error prone: considerably more code than the elevation band
+    flowlines.
+  - Less robust: more glaciers are failing in the preprocessing than with
+    the simpler method.
+    When glaciers are badly outlined (or worse, when ice caps are not
+    properly divided), or with bad DEMs, the geometrical flowline
+    can "look" very ugly.
+  - Computationally expensive (more grid points on average, more prone
+    to numerical instabilities).
+  - Complex handling of mass-balance parameters for tributaries at the
+    inversion (leading to multiple temperature sensitivity parameters
+    for large glaciers).
+  - Related: **all "new generation" maas-balance models in OGGM currently
+    handle only a single flowline because of this complexity.**
 
 .. admonition:: **Summary**
 
    **When to use:** when geometry matters, and when length is a important variable.
-   For mountain glaciers (e.g. Alps, Himalayas).
+   For mountain glaciers (e.g. Alps, Himalayas). With the old mass-balance
+   model.
 
    **When not to use:** for ice caps, badly outlined glaciers, very large and
    flat glaciers, for global applications where geometrical details matters less.
+   With the more fancy mass-balance models.
 
 Elevation-band flowlines
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Pros:
 
-   - Robust approach: much less sensitive to DEM and outline errors. This is
-     probably its best attribute, and makes it very interesting for large-scale
-     applications.
-   - Computationally cheap and simple: less error prone.
-   - Arguably: better representation of the main glacier flow?
+  - Robust approach: much less sensitive to DEM and outline errors. This is
+    probably its best attribute, and makes it very interesting for large-scale
+    applications.
+  - Computationally cheap and simple: less error prone.
+  - Simpler mass-balance, because no complexity with the tributaries.
+  - Arguably: better representation of the main glacier flow?
 
 - Cons:
 
-   - Geometry is lost, glaciers cannot be plotted on a map anymore.
-   - Glacier length is not the "true" length.
-   - Somewhat arbitrary: it's not clear why averaging the slopes with subjectively
-     chosen quantiles is a good idea.
-   - Only one flowline.
+  - Geometry is lost, glaciers cannot be plotted on a map anymore.
+  - Glacier length is not the "true" length.
+  - Somewhat arbitrary: it's not clear why averaging the slopes with subjectively
+    chosen quantiles is a good idea.
+  - Only one flowline.
 
 .. admonition:: **Summary**
 
    **When to use:** when "true" geometry does not matter. When doing simulations
    at large scales, and when robustness to bad / uncertain boundary conditions
-   is important.
+   is important. With the new generation mass-balance models.
 
    **When not to use:** when glacier geometry or (absolute) length matters.
 

diff --git a/docs/frontal-ablation.rst b/docs/frontal-ablation.rst
@@ -8,8 +8,9 @@ are still in the testing phase and are switched off per default.
 Visit our `turotials <https://oggm.org/tutorials/notebooks/welcome.html>`_
 if you are interested and would like to give them a go.
 
-    .. figure:: https://oggm.org/img/blog/calving_param/calving_ex.png
-        :width: 100%
+.. figure:: https://oggm.org/img/blog/calving_param/calving_ex.png
+    :width: 100%
+    :align: left
 
-        Illustration of the water-depth – calving-rate feedbacks. See the tutorials
-        for more details.
+    Illustration of the water-depth – calving-rate feedbacks. See the tutorials
+    for more details.
diff --git a/docs/geometry-evolution.rst b/docs/geometry-evolution.rst
@@ -0,0 +1,34 @@
+.. _geometry-evolution:
+
+Geometry evolution models
+=========================
+
+**Geometry evolution models** are responsible to compute the change in
+glacier geometry as a response to the climatic mass-balance
+forcing computed with the :ref:`mass-balance`. They are also in charge of reporting
+diagnostic variables such as length, area, volume. Depending on the model's complexity,
+they can also report about ice velocity, ice thickness, etc.
+
+Currently, OGGM has three operational geometry evolution models:
+
+.. toctree::
+    :maxdepth: 1
+
+    OGGM-VAS (volume-area scaling) <https://github.com/OGGM/oggm-vas>
+    mass-redistribution.rst
+    ice-dynamics.rst
+
+`OGGM-VAS <https://github.com/OGGM/oggm-vas>`_ is a complete python re-write of
+Ben Marzeion's 2012 model. It should be equivalent to the original matlab model,
+but follows the OGGM syntax very closely (and uses OGGM for data pre- and
+post-processing). See Moritz Oberrauch's `thesis <https://diglib.uibk.ac.at/ulbtirolhs/content/titleinfo/5878449>`_
+for more information.
+
+The :ref:`mass-redistribution` is an implementation of the "delta-h" model
+by `Huss & Hock (2015) <https://www.frontiersin.org/articles/10.3389/feart.2015.00054/full>`_ and
+`Rounce et al., (2020) <https://doi.org/10.3389/feart.2019.00331>`_. It works quite
+well for short simulations of the glacier retreat phase.
+
+The default geometry evolution model in OGGM is the :ref:`ice-dynamics`.
+We also have a `distributed SIA model <https://github.com/OGGM/oggm/blob/master/oggm/core/sia2d.py>`_
+to play around, but nothing operational yet.
diff --git a/docs/hub.rst b/docs/hub.rst
@@ -73,10 +73,11 @@ users (the ``shared`` folder in your ``$HOME``). The first time you run a
 new glacier, OGGM will first check if the data is available in the ``shared`` folder,
 and if not it will download it for you and the other users.
 
-    .. figure:: _static/hub_envs.png
-        :width: 100%
+.. figure:: _static/hub_envs.png
+    :width: 100%
+    :align: left
 
-        Welcome screen of https://hub.oggm.org
+    Welcome screen of https://hub.oggm.org
 
 When logging in, you can choose between two environments: