Docs update: Api reference (#142)

* Convert some attributes and methods to private.

Some glacier attributes like current_state and model_state are never
interacted with by the user. The same is true for the method state().
To indicate this we make them "private". This also cleans up the
documentation.

* Docs update.

This adds a api reference of the new classes to the documentation. It
differs somewhat from the e.g. oggm.GlacierDir in that it also has a full
documentation of class methods. To achieve this an additional template
for classes is needed. Property setters are however not documented yet.

* Edits and new build structure

Co-authored-by: Fabien Maussion <fabien.maussion@uibk.ac.at>

.gitignore

@@ -30,6 +30,7 @@ eggs
 *.lock
 *.mo
 docs/_build
+docs/_autosummary
 docs/_build_html
 docs/generated
 docs/_sources

.readthedocs.yaml

@@ -0,0 +1,9 @@
+version: 2
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "mambaforge-4.10"
+conda:
+  environment: docs/environment.yml
+sphinx:
+   configuration: docs/conf.py

docs/api.rst

@@ -0,0 +1,133 @@
+#######################
+oggm-edu python package
+#######################
+
+.. currentmodule:: oggm_edu
+
+This page lists all classes, their methods and attributes available in the
+``oggm-edu`` python package.
+
+.. important::
+
+    This programming interface is relatively new (2022). It replaces a
+    much simpler previous interface which is now accessible via
+    ``from oggm_edu import legacy``.
+
+    Don't hesitate to `let us know <https://github.com/OGGM/oggm-edu/issues>`_
+    if you find any mistakes!.
+
+Glacier bed
+-----------
+
+.. autosummary::
+   :toctree: generated/
+
+   GlacierBed
+   GlacierBed.plot
+
+MassBalance
+-----------
+
+.. autosummary::
+   :toctree: generated/
+
+   MassBalance
+   MassBalance.reset
+   MassBalance.get_monthly_mb
+   MassBalance.get_annual_mb
+   MassBalance.gradient
+   MassBalance.ela
+   MassBalance.temp_bias
+
+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
+
+SurgingGlacier
+--------------
+
+.. autosummary::
+   :toctree: generated/
+
+   SurgingGlacier
+   SurgingGlacier.reset
+   SurgingGlacier.progress_to_year
+   SurgingGlacier.plot_history
+   SurgingGlacier.normal_years
+   SurgingGlacier.surging_years
+   SurgingGlacier.basal_sliding_surge
+
+
+GlacierCollection
+-----------------
+
+.. autosummary::
+   :toctree: generated/
+
+   GlacierCollection
+
+GlacierCollection methods
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   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
+
+GlacierCollection attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   GlacierCollection.glaciers
+   GlacierCollection.annual_mass_balance
+
+

docs/environment.yml

@@ -1,11 +1,41 @@
-name: edudocs
+name: oggm_edu_docs
 channels:
   - conda-forge
+  - oggm
 dependencies:
-  - python
-  - numpydoc
-  - ipython
+  - jupyter
+  - jupyterlab
+  - numpy
+  - scipy
+  - pandas
+  - shapely
+  - matplotlib
+  - Pillow
+  - netcdf4
+  - scikit-image
+  - scikit-learn
+  - configobj
+  - xarray
+  - pytest
+  - dask
+  - bottleneck
+  - pyproj
+  - cartopy
+  - geopandas
+  - rasterio<1.2.10
+  - rioxarray
+  - seaborn
+  - pytables
+  - salem
+  - motionless
   - sphinx
-  - pip
+  - sphinx-book-theme
+  - ipython
+  - numpydoc
+  - seaborn
+  - sphinx-intl
   - pip:
-      - sphinx-book-theme
+    - joblib
+    - progressbar2
+    - git+https://github.com/OGGM/pytest-mpl
+    - oggm

docs/index.rst

@@ -95,9 +95,9 @@ possible. Read our :ref:`notebooks_howto` first if you are new to these things.
     :caption: Interactive Notebooks
 
     notebooks_howto.rst
+    api.rst
     OGGM-Edu notebooks <https://oggm.org/oggm-edu-notebooks>
 
-
 .. _title_tuto:
 
 OGGM tutorials