First docs - slaight reorganisation

OGGM · Aug 15, 2023 · 6983a1c · 6983a1c
1 parent 3aa0f6b
commit 6983a1c
Show file tree

Hide file tree

Showing 10 changed files with 126 additions and 160 deletions.
diff --git a/docs/assets.rst b/docs/assets.rst
@@ -4,6 +4,12 @@ Assets and downloads
 This page lists some datasets that are either generated or used by OGGM and
 that can be useful to others.
 
+.. _standard-projs:
+
+OGGM standard projections (new in v1.6.1!)
+------------------------------------------
+
+TODO
 
 Shapefiles of glacier centerlines, flowlines and widths
 -------------------------------------------------------

diff --git a/docs/cloud.rst b/docs/cloud.rst
@@ -1,26 +1,26 @@
 Try OGGM online
 ===============
 
+.. image:: https://mybinder.org/static/logo.svg
+    :width: 20%
+    :align: right
+    :target: https://mybinder.org/v2/gh/OGGM/tutorials/stable?labpath=notebooks%2Fwelcome.ipynb
+
 You can try OGGM in your web browser **without having to install anything**!
 This is the best way to run the tutorials or even do exploratory research
 to test the model, before you move on to more serious computations.
 
-.. image:: https://gke.mybinder.org/static/logo.svg
-    :width: 25%
-    :target: https://mybinder.org/v2/gh/OGGM/binder/stable?urlpath=git-pull?repo=https://github.com/OGGM/tutorials%26amp%3Bbranch=master%26amp%3Burlpath=lab/tree/tutorials/notebooks/welcome.ipynb%3Fautodecode
-
-Our `Binder <https://mybinder.org/>`_ test space is available to anyone, with no
+Our `Binder <https://mybinder.org>`_ test space is available to anyone, with no
 registration necessary. Using it is very simple. Just click on the
 link below to get you started!
 
 .. figure:: https://img.shields.io/badge/Launch-OGGM%20tutorials-579ACA.svg?style=popout&logo=data:image/png;base64,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
-  :target: https://mybinder.org/v2/gh/OGGM/binder/stable?urlpath=git-pull?repo=https://github.com/OGGM/tutorials%26amp%3Bbranch=master%26amp%3Burlpath=lab/tree/tutorials/notebooks/welcome.ipynb%3Fautodecode
-  :align: left
+  :target: https://mybinder.org/v2/gh/OGGM/tutorials/stable?labpath=notebooks%2Fwelcome.ipynb
 
 If you are new to the Jupyter Notebooks or to JupyterLab, you will probably
 find this `introduction to interactive notebooks`_ quite useful.
 
-.. warning::
+.. important::
 
     Binder environments are only temporary! Perfect for trying and learning,
     but not suitable for development work. Remember to download your notebooks

diff --git a/docs/conf.py b/docs/conf.py
@@ -228,7 +228,7 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-    "logo_only": True,
+    # "logo_only": True,
     "repository_url": "https://github.com/OGGM/oggm",
     "use_repository_button": True,
     "use_issues_button": True,

diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -206,14 +206,13 @@ Installation
 ~~~~~~~~~~~~
 
 There are some extra requirements to build the docs: you will need to
-have ``sphinx``, ``sphinx-togglebutton``, ``sphinx-book-theme``, ``numpydoc``
-and ``ipython`` installed.
+have ``sphinx``, ``sphinx-togglebutton``, ``sphinx-book-theme``,
+``sphinx-reredirects``, ``numpydoc`` and ``ipython`` installed.
 
 If you have a conda environment named ``oggm_env``, you can install the extra
 requirements with::
 
-      mamba install -c conda-forge sphinx ipython numpydoc sphinx-book-theme
-      pip install sphinx-togglebutton
+      mamba install -c conda-forge sphinx ipython numpydoc sphinx-book-theme sphinx-reredirects sphinx-togglebutton
 
 If you don't have an oggm installation yet, download (or clone) the latest version
 of the oggm repository.

diff --git a/docs/flowlines.rst b/docs/flowlines.rst
@@ -158,6 +158,7 @@ Note that a *perfect* match is not possible since the sample size is
 not the same between the "1.5D" and the 2D representation of the glacier,
 but it's close enough.
 
+.. _eb-flowlines:
 
 Elevation bands flowlines
 -------------------------

diff --git a/docs/index.rst b/docs/index.rst
@@ -7,17 +7,17 @@ the past and future mass balance, volume, and geometry of glaciers worldwide.
 
 The model features several glacier evolution models, including an explicit ice
 dynamics module accounting for glacier geometry and frontal ablation.
-With an unwavering commitment to using publicly available data for calibration
-and validation, OGGM is a reliable and readily applicable tool for studying glaciers.
+**With an unwavering commitment to using publicly available data for calibration
+and validation, OGGM is a reliable and readily applicable tool for studying glaciers**.
 
 OGGM is also a modular platform that supports novel modelling workflows,
-encouraging researchers to create unique models and analyses for their research.
+**encouraging researchers to create unique models and analyses for their research**.
 Our framework is designed to be flexible and adaptable, making it an
 ideal tool for a wide range of applications in glaciology and related fields.
 
 .. warning::
 
-   OGGM v1.6.0 is a substantial change to v1.5.3. Among other developments,
+   OGGM v1.6 is a substantial change to v1.5.3. Among other developments,
    the mass balance calibration has substantially improved. In order to
    allow easier and faster developments from the community in the future,
    several variable names have changed and older workflows are not available
@@ -26,13 +26,9 @@ ideal tool for a wide range of applications in glaciology and related fields.
    Older versions of OGGM will always be available via github and Zenodo,
    and older documentation pages can be accessed via the interface below.
 
-
 **This webpage is for the software documentation: for general information about the
 OGGM project and related news, visit** `oggm.org <http://oggm.org>`_.
 
-
-.. include:: _generated/version_text.txt
-
 Video presentation
 ^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/installing-oggm.rst b/docs/installing-oggm.rst
@@ -275,6 +275,26 @@ are frequent and point to errors in upstream packages, rarely in OGGM itself.
 If you encounter issues, please get in touch with
 us `on github <https://github.com/OGGM/oggm/issues>`_.
 
+Install a minimal OGGM environment
+----------------------------------
+
+If you plan to use only the numerical core of OGGM (that is, for idealized
+simulations or teaching), you can skip many dependencies and only
+install this shorter list:
+
+.. include:: recommended_minimal_env.yml
+   :literal:
+
+Installing them with pip or conda should be much easier.
+`Install OGGM itself`_ then as above.
+
+Running the tests in this minimal environment works the same. Simply run
+from a terminal::
+
+    pytest.oggm
+
+The number of tests will be much smaller!
+
 .. _virtualenv-install:
 
 Install with pyenv (Linux)
@@ -303,7 +323,7 @@ For building python and stuff::
 
 For NetCDF and HDF::
 
-    $ sudo apt-get install netcdf-bin ncview hdf5-tools libhdf5-dev 
+    $ sudo apt-get install netcdf-bin ncview hdf5-tools libhdf5-dev
 
 
 Pyenv and pyenv-virtualenv
@@ -314,7 +334,7 @@ Pyenv and pyenv-virtualenv
     If you are not familiar with pyenv, you can visit
     `their documentation <https://realpython.com/intro-to-pyenv/>`_
     (especially the installing pyenv section).
-    
+
 Install `pyenv <https://github.com/pyenv/pyenv>`_ and create a new virtual environment
 with a recent python version (3.7+) using `pyenv-virtualenv <https://github.com/pyenv/pyenv-virtualenv>`_.
 
@@ -348,23 +368,3 @@ Install OGGM and run the tests
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Refer to `Install OGGM itself`_ above.
-
-Install a minimal OGGM environment
-----------------------------------
-
-If you plan to use only the numerical core of OGGM (that is, for idealized
-simulations or teaching), you can skip many dependencies and only
-install this shorter list:
-
-.. include:: recommended_minimal_env.yml
-   :literal:
-
-Installing them with pip or conda should be much easier.
-`Install OGGM itself`_ then as above.
-
-Running the tests in this minimal environment works the same. Simply run
-from a terminal::
-
-    pytest.oggm
-
-The number of tests will be much smaller!
diff --git a/docs/mass-balance-monthly.rst b/docs/mass-balance-monthly.rst
@@ -30,6 +30,8 @@ temperature and precipitation at the altitude :math:`z` of the glacier
 grid points. The default is to use a fixed lapse rate of
 -6.5K km :math:`^{-1}` and no gradient for precipitation.
 
+.. _mb-calib:
+
 Calibration
 -----------
 

diff --git a/docs/recommended_env.yml b/docs/recommended_env.yml
@@ -2,8 +2,6 @@ name: oggm_env
 channels:
   - conda-forge
 dependencies:
-  - jupyter
-  - jupyterlab
   - numpy
   - scipy
   - pandas
@@ -12,7 +10,6 @@ dependencies:
   - Pillow
   - netcdf4
   - scikit-image
-  - scikit-learn
   - configobj
   - xarray
   - pytest
@@ -27,17 +24,9 @@ dependencies:
   - pytables
   - salem
   - motionless
-  - sphinx
-  - sphinx-book-theme>=0.3.3
-  - ipython
-  - numpydoc
-  - seaborn
-  - sphinx-intl
-  - sphinx-reredirects
   - pip
   - pip:
     - joblib
     - progressbar2
-    - sphinx-togglebutton
     - git+https://github.com/OGGM/pytest-mpl
     - oggm