Some refactoring (#169)

.gitignore

@@ -33,6 +33,7 @@ docs/_build
 docs/_autosummary
 docs/_build_html
 docs/generated
+docs/locale/*/LC_MESSAGES/generated/
 docs/_sources
 docs/_images
 docs/savefig

docs/api.rst

@@ -1,17 +1,22 @@
 .. _api:
 
-#######################
-oggm-edu python package
-#######################
+###########################
+The oggm-edu python package
+###########################
 
 .. currentmodule:: oggm_edu
 
-This page lists all classes, their methods and attributes available in the
-``oggm-edu`` python package.
+The ``oggm-edu`` python package is a "simplification layer" meant to hide many
+of the complex OGGM internals to the students. In fact, it can be seen as a
+fully functional glacier flow model optimized for education.
+
+To see it in action, visit our dedicated
+`oggm-edu notebooks website <https://oggm.org/oggm-edu-notebooks/oggm-edu/edu_intro.html>`_,
+or run them yourself on MyBinder:
 
 |badge_edu_notebooks|
 
-Open a MyBinder interactive session to try them yourself!
+For a complete documentation, visit the full :ref:`api_detailed`.
 
 .. important::
 
@@ -22,171 +27,56 @@ Open a MyBinder interactive session to try them yourself!
         from oggm_edu import legacy
 
     Don't hesitate to `let us know <https://github.com/OGGM/oggm-edu/issues>`_
-    if you find any mistakes in the tool or in the docs!
-
-GlacierBed
-----------
+    if you encounter any problem with the change!
 
-.. autosummary::
-   :toctree: generated/
+A 2 minutes introduction to the package
+---------------------------------------
 
-   GlacierBed
-   GlacierBed.plot
+The main objective of package is to propose an expressive syntax and preconfigured
+plotting functions:
 
-GlacierBed example
-~~~~~~~~~~~~~~~~~~
+.. code-block:: python
 
-.. ipython:: python
+    from oggm_edu import MassBalance, GlacierBed, Glacier
 
-    from oggm_edu import GlacierBed
+    # Create the bed
     bed = GlacierBed(top=3400, bottom=1500, width=300)
-    @savefig plot_bed.png width=100%
-    bed.plot();
-
-MassBalance
------------
-
-.. autosummary::
-   :toctree: generated/
-
-   MassBalance
-   MassBalance.reset
-   MassBalance.get_monthly_mb
-   MassBalance.get_annual_mb
-   MassBalance.gradient
-   MassBalance.ela
-   MassBalance.temp_bias
-
-MassBalance example
-~~~~~~~~~~~~~~~~~~~
-
-.. ipython:: python
-
-    from oggm_edu import MassBalance
+    # And the mass balance
     mass_balance = MassBalance(ela=3000, gradient=4)
-    mass_balance
-
-Glacier
--------
-
-.. autosummary::
-   :toctree: generated/
-
-   Glacier
-
-Glacier methods
-~~~~~~~~~~~~~~~
-
-.. autosummary::
-   :toctree: generated/
-
-   Glacier.reset
-   Glacier.copy
-   Glacier.progress_to_year
-   Glacier.progress_to_equilibrium
-   Glacier.plot
-   Glacier.plot_mass_balance
-   Glacier.plot_history
-   Glacier.plot_state_history
-   Glacier.add_temperature_bias
-
-Glacier attributes
-~~~~~~~~~~~~~~~~~~
-
-.. autosummary::
-   :toctree: generated/
-
-   Glacier.ela
-   Glacier.mb_gradient
-   Glacier.mass_balance
-   Glacier.annual_mass_balance
-   Glacier.specific_mass_balance
-   Glacier.age
-   Glacier.history
-   Glacier.state_history
-   Glacier.creep
-   Glacier.basal_sliding
-   Glacier.eq_states
-   Glacier.response_time
-   Glacier.current_state
-
-Glacier example
-~~~~~~~~~~~~~~~
-
-.. ipython:: python
-
-    from oggm_edu import Glacier
+    # And finally the glacier!
     glacier = Glacier(bed=bed, mass_balance=mass_balance)
-    glacier.progress_to_equilibrium()
-    @savefig plot_glacier.png width=100%
-    glacier.plot();
-
-.. ipython:: python
+    glacier.plot()
 
-    @savefig plot_glacier_equi.png width=100%
-    glacier.plot_history();
+.. image:: https://oggm.org/img/blog/oggm-edu-new/edu_intro_26_0.png
 
-SurgingGlacier
---------------
+To grow the glacier we can either progress the glacier to a specified year:
 
-.. autosummary::
-   :toctree: generated/
+.. code-block:: python
 
-   SurgingGlacier
-   SurgingGlacier.reset
-   SurgingGlacier.progress_to_year
-   SurgingGlacier.plot_history
-   SurgingGlacier.normal_years
-   SurgingGlacier.surging_years
-   SurgingGlacier.basal_sliding_surge
+    glacier.progress_to_year(150)
+    glacier.plot()
 
+.. image:: https://oggm.org/img/blog/oggm-edu-new/edu_intro_31_0.png
 
-GlacierCollection
------------------
+Or progress the glacier to equilibrium:
 
-.. autosummary::
-   :toctree: generated/
+.. code-block:: python
 
-   GlacierCollection
-
-GlacierCollection methods
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. autosummary::
-   :toctree: generated/
+    glacier.progress_to_equilibrium()
+    glacier.plot()
 
-   GlacierCollection.reset
-   GlacierCollection.fill
-   GlacierCollection.add
-   GlacierCollection.change_attributes
-   GlacierCollection.progress_to_year
-   GlacierCollection.progress_to_equilibrium
-   GlacierCollection.plot
-   GlacierCollection.plot_history
-   GlacierCollection.plot_mass_balance
+.. image:: https://oggm.org/img/blog/oggm-edu-new/edu_intro_37_0.png
 
-GlacierCollection attributes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+It is just as easy to inspect the history of the length, volume and area of the glacier:
 
-.. autosummary::
-   :toctree: generated/
+.. code-block:: python
 
-   GlacierCollection.glaciers
-   GlacierCollection.annual_mass_balance
+    glacier.plot_history()
 
+.. image:: https://oggm.org/img/blog/oggm-edu-new/edu_intro_43_0.png
 
-GlacierCollection example
-~~~~~~~~~~~~~~~~~~~~~~~~~
+This is just a small part of what is possible with the new interface.
 
-.. ipython:: python
+For a complete documentation, visit the full :ref:`api_detailed`.
 
-    from oggm_edu import GlacierCollection
-    wide_narrow_bed = GlacierBed(altitudes=[3400, 2800, 1500],
-                                 widths=[600, 300, 300])
-    wide_narrow_glacier = Glacier(bed=wide_narrow_bed,
-                                  mass_balance=mass_balance)
-    collection = GlacierCollection()
-    collection.add([glacier, wide_narrow_glacier])
-    collection.progress_to_year(600)
-    @savefig plot_glacier_collection.png width=100%
-    collection.plot()
+We hope that you will find this interesting, and are waiting for your feedback!