Some typos and more edits (#88)

docs/_static/custom.css

@@ -0,0 +1,20 @@
+.rst-content .toggle {
+    background: none repeat scroll 0 0 #e7f2fa;
+    padding: 12px;
+    line-height: 24px;
+    margin-bottom: 24px;
+}
+
+.rst-content .toggle .admonition-title {
+    display: block;
+    clear: both;
+    cursor: pointer;
+}
+
+.rst-content .toggle .admonition-title:after {
+    content: " ▶";
+}
+
+.rst-content .toggle .admonition-title.open:after {
+    content: " ▼";
+}

docs/_templates/page.html

@@ -0,0 +1,16 @@
+{% extends "!page.html" %}
+
+{% set css_files = css_files + ["_static/custom.css"] %}
+
+{% block footer %}
+ <script type="text/javascript">
+    $(document).ready(function() {
+        $(".toggle > *").hide();
+        $(".toggle .admonition-title").show();
+        $(".toggle .admonition-title").click(function() {
+            $(this).parent().children().not(".admonition-title").toggle(400);
+            $(this).parent().children(".admonition-title").toggleClass("open");
+        })
+    });
+</script>
+{% endblock %}

docs/alps_future.rst

@@ -18,7 +18,7 @@ Find out about the future evolution of glaciers in the European Alps! The graphi
 Authors
 -------
 
-`Fabien Maussion <https://fabienmaussion.info/>`_ and co-author: `Zora Schirmeister <https://github.com/zschirmeister>`_
+`Fabien Maussion <https://fabienmaussion.info/>`_ and `Zora Schirmeister <https://github.com/zschirmeister>`_
 
 Data sources
 ------------

docs/conf.py

@@ -380,3 +380,7 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {}
+
+# Add toggle container https://stackoverflow.com/questions/2454577/sphinx-restructuredtext-show-hide-code-snippets
+def setup(app):
+    app.add_stylesheet('custom.css')

docs/gallery.rst

@@ -61,4 +61,4 @@ Possible future improvements
 The application would profit from additional glaciers in regions that are not
 covered yet. If you are interested to contribute you can add a glacier and an
 image of it into this `list <https://github.com/OGGM/glacier-gallery/blob/master/glacier_data.py>`_.
-You can send us the edited file per mail or with a pull-request. Thanks!
+You can send us the edited file per mail or with a pull-request. Thanks!

docs/simulator.rst

@@ -1,18 +1,15 @@
 .. _simulator:
 
-Glacier Simulator (beta)
-========================
+Glacier Simulator
+=================
 
 .. figure:: _static/simulator_thumbnail.png
     :width: 100%
     :target: https://bokeh.oggm.org/simulator/app
 
 The glacier simulator is an **interactive web application** with which
-you can learn (and teach) about how glaciers grow and shrink, how fast they
-flow, what parameters influence their size, and a lot more.
-
-The application is still in beta version, which means that we are working on
-the last details before release.
+you can learn (and teach) about glacier flow, how glaciers grow and shrink,
+what parameters influence their size, and a lot more!
 
 You can start the app by clicking on this link: |badgelink|_
 
@@ -27,7 +24,7 @@ You can start the app by clicking on this link: |badgelink|_
   we recommend to use the app on MyBinder or (even better) locally on your
   own computer (see below).
 
-Alternatively, you can start the app `on mybinder <https://mybinder.org/v2/gh/OGGM/glacier_simulator/master?urlpath=panel/app>`_
+You can also start the app `on mybinder <https://mybinder.org/v2/gh/OGGM/glacier_simulator/master?urlpath=panel/app>`_
 (slightly slower in general, but a good alternative if our server is saturated).
 If you want to run the app on your own computer, see :ref:`docker-launch-simulator` below.
 
@@ -41,60 +38,104 @@ Questions to explore with this app
 
 With this app, you can address many questions, by yourself or in class!
 
+
+Glacier shape
+~~~~~~~~~~~~~
+
+See `antarcticglaciers.org (mass-balance)`_
+for an introduction about glacier mass-balance and the ELA, or our
+:ref:`glacier_basics` graphics for an illustration.
+
+**In "beginner mode", start by setting the ELA to 3000m a.s.l**, and note
+on a piece of paper: the equilibrium volume of the glacier,
+its length and maximal thickness. **Now choose the "wider top" glacier shape**
+and run the model again. Is the new glacier larger or smaller than before? Why?
+
+..  admonition:: Take home messages
+    :class: toggle
+
+    A glacier with a wider top has a larger `accumulation area <https://en.wikipedia.org/wiki/Accumulation_zone>`_.
+    It can therefore accumulate more mass (more ice) and flow further down.
+
+
 Equilibrium Line Altitude (ELA)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-See `antarcticglaciers.org <http://www.antarcticglaciers.org/glacier-processes/introduction-glacier-mass-balance/>`_
-for an intrudction about glacier mass-balance and the ELA, or our
+See `antarcticglaciers.org (mass-balance)`_
+for an introduction about glacier mass-balance and the ELA, or our
 :ref:`glacier_basics` graphics for an illustration.
 
 We are going to show that the ELA is determinant in shaping glaciers.
 
 **In "beginner mode", start by setting the ELA to 2500m a.s.l**, and note
 on a piece of paper: the equilibrium volume of the glacier,
-its lenght and maximal thickness.
+its length and maximal thickness.
+
 **Now change the ELA up to 3500m a.s.l in 200m increments** and, at each
-step, note the equilibrium volume of the glacier, its lenght and maximal thickness.
+step, note the equilibrium volume of the glacier, its length and maximal thickness.
 
 **Now draw these variables on a graph, as a function of the ELA.**
 How does glacier volume change with ELA? Can you explain why?
 What about glacier length and thickness? Are these changes linear, or more
 complex?
 
-An example graphic that students could come up with by varying the ELA
-with different shapes can be found `here <_static/simulator_ela_example.png>`_.
+..  admonition:: Take home messages
+    :class: toggle
 
-Glacier shape
-~~~~~~~~~~~~~
+    An example graphic that students could come up with by varying the ELA
+    with different shapes:
 
-**In "beginner mode", start by setting the ELA to 3000m a.s.l**, and note
-on a piece of paper: the equilibrium volume of the glacier,
-its lenght and maximal thickness. **Now choose the "wider top" glacier shape**
-and run the model again. Is the new glacier larger or smaller than before? Why?
+    .. figure:: _static/simulator_ela_example.png
+        :width: 100%
 
+    **The lower the ELA, the larger the equilibrium glacier**. The length,
+    volume or maximal thickness are not necessarily linear functions of the
+    ELA. 
 
 Glacier slope
 ~~~~~~~~~~~~~
 
-**Intro:**
-
-The slope of a glacier bed is one key ingredient which determine the flow of a glacier. For a introduction on glacier flow see `antarcticglaciers.org <http://www.antarcticglaciers.org/glacier-processes/glacier-flow-2/glacier-flow/>`_. In short glaciers flow downslope driven by the gravitational force. The slope determines how the gravitational force is devided into a part along the slope and a part perpenticular to the slope (see `wikipedia <https://en.wikipedia.org/wiki/Inclined_plane#/media/File:Free_body1.3.svg>`_). The slope parallel force "pulls" the glacier downwards and the perpendicular force wants to "flatten" the glacier.
+The slope of a glacier bed is one key ingredient which determines glacier flow.
+For a introduction, visit `antarcticglaciers.org (glacier-flow)`_.
+In short: glaciers flow downslope driven by the gravitational force.
+This force can be decomposed into an along-slope component and perpenticular to the slope component (see
+`this illustration in wikipedia <https://en.wikipedia.org/wiki/Inclined_plane#/media/File:Free_body1.3.svg>`_).
+The along-slope component "pulls" the glacier downwards and the perpendicular component "flattens" the glacier.
 
 **Experiments:**
 
-- *Beginners*: Use beginner mode with standard settings (constant width, mass balance gradient of 4 and ELA of 3000) and run the model with all different settings for the slope and use the geometry plot for inspection. Take notes on a piece of paper of the ice thickness, volume, area and length at the end of each model run.
-- *Advanced*: Conduct the same experiment as for beginners, but additionally switch on the timeseries plot. Also take notes of the velocity and look how the parameters change with time (in the timeseries plot).
+- *Beginners*: Use beginner mode with standard settings (constant width, mass
+  balance gradient of 4 and ELA of 3000) and run the model with all different
+  settings for the slope and use the geometry plot for inspection.
+  Take notes on a piece of paper of the ice thickness, volume, area and length
+  at the end of each model run.
+- *Advanced*: Conduct the same experiment as for beginners, but additionally
+  switch on the timeseries plot. Also take notes of the velocity and look how
+  the parameters change with time in the timeseries plot.
 
 **Questions to answer:**
 
-- *Beginners*: Are steep or flat glaciers thicker? Why do you think?
-- *Advanced*: Are steep of flat glaciers faster? How and why those the velocity change with time?
+- *Beginners*: which glaciers are thicker? Steep or flat ones? And why?
+- *Advanced*: which glaciers are faster? Steep or flat ones? How and why does
+  the velocity change with time?
+
+
+..  admonition:: Take home messages
+    :class: toggle
 
-**Take Home Messages:**
+    - glaciers flow downslope
+    - the steeper the slope the thinner the glacier (larger along-slope gravitational force)
+    - the flatter the slope the larger the equilibrium velocity. When the glacier
+      is thin (has not much mass) the along-slope component is more important.
+      When the glacier is getting thicker the perpendicular component is getting
+      more weight. This partly explains slower velocities for flatter slopes
+      at the start of the model run, and higher velocities when the glacier is
+      getting thicker. For steeper slopes the velocities at the start are
+      large and so more ice is transported downwards, and the glacier stays
+      relatively thin.
 
-- Glaciers flow downslope
-- the steeper the slope the thinner the glacier (larger slope parallel gravitational force)
-- the flatter the slope the larger the velocity in the end (in equilibrium): when the glacier is thin (has not much mass) the slope parallel part is more important, when the glacier is getting thicker the perpendicular part is getting more weight. This partly explains slower velocities for flatter slopes at the start of the model run which getting larger when the glacier is getting thicker. For steeper slopes the velocities at the start are larger and so more ice is transported downwards and the glacier stays relative thin.
+.. _antarcticglaciers.org (mass-balance): http://www.antarcticglaciers.org/glacier-processes/introduction-glacier-mass-balance
+.. _antarcticglaciers.org (glacier-flow): http://www.antarcticglaciers.org/glacier-processes/glacier-flow-2/glacier-flow
 
 Mass-balance gradient
 ~~~~~~~~~~~~~~~~~~~~~