doc(notebooks and rst files): Applies changes from review, fixes some url

Author: spjuhel

doc/conf.py

@@ -131,7 +131,7 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-    "header_links_before_dropdown": 8,
+    "header_links_before_dropdown": 6,
     "navbar_align": "left",
     # "icon_links": [
     #     {

doc/development/Guide_Euler.ipynb

@@ -72,12 +72,13 @@
     "\n",
     "(The last two lines may seem odd but they are working around a conficting dependency version situation.)\n",
     "\n",
-    "You need to execute this every time you login to Euler before Climada can be used. \n",
+    "You need to execute this every time you login to Euler before Climada can be used.\n",
     "To safe yourself from doing it manually, append these lines to the ~/.bashrc script, which is automatically executed upon logging in to Euler."
    ]
   },
   {
    "cell_type": "markdown",
+   "id": "4dad7c27",
    "metadata": {},
    "source": [
     "\n",
@@ -144,12 +145,13 @@
   },
   {
    "cell_type": "markdown",
+   "id": "479e0ac2",
    "metadata": {},
    "source": [
     "\n",
     "### 5. Adjust the Climada configuration\n",
     "\n",
-    "Edit a configuration file according to your needs (see [Guide_Configuration](../guide/Guide_Configuration.ipynb)).\n",
+    "Edit a configuration file according to your needs (see [Configuration](../development/Guide_Configuration.ipynb)).\n",
     "Create a climada.conf file e.g., in /cluster/home/$USER/.config with the following content:\n",
     "\n",
     "```json\n",
@@ -186,12 +188,13 @@
     "\n",
     "Look for the \"`OK`\" in the hereby created `slurm-[XXXXXXX].out` file\n",
     "\n",
-    "Please see the docs at https://slurm.schedmd.com/ on how to use the `slurm` batch system \n",
+    "Please see the docs at https://slurm.schedmd.com/ on how to use the `slurm` batch system\n",
     "and the Wiki https://scicomp.ethz.ch/wiki/Transition_from_LSF_to_Slurm for a mapping of `lsf` commands to their `slurm` equivalents."
    ]
   },
   {
    "cell_type": "markdown",
+   "id": "e5c90bff",
    "metadata": {},
    "source": [
     "\n",

doc/development/Guide_Review.ipynb

@@ -63,19 +63,19 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This is a generic set of instruction which should always work.\n",
+    "In order to make your review, you will have to have climada installed from source (see [here](../getting-started/install.rst#install-advanced)), and switch to the branch you are reviewing (see [here](../getting-started/install.rst#change-branch))\n",
     "\n",
-    "Assuming you already cloned the climada repository, and are at the root of that folder:\n",
+    "Creating a new python environment is often not necessary (*e.g.*, for minor feature branch that do not change the dependencies you can probably use a generic `develop` environment where you installed climada in editable mode), but can help in some cases (for instance changes in dependencies), to do so:\n",
+    "\n",
+    "Here is a generic set of instructions which should always work, assuming you already cloned the climada repository, and are at the root of that folder:\n",
     "\n",
     "```\n",
     "git fetch && git checkout <branch to review>\n",
     "mamba create -n <choose a name> # restrict python version here with \"python==3.x.*\"\n",
     "mamba env update -n <same name> -f requirements/env_climada.yml\n",
     "mamba activate <same name>\n",
     "pip install -e ./\n",
-    "```\n",
-    "\n",
-    "Creating a new python environment is strongly recommended, but not always necessary (*e.g.*, for minor feature branch that do not change the dependencies you can probably use a generic `develop` environment where you installed climada in editable mode)"
+    "```\n"
    ]
   },
   {

doc/development/Guide_Testing.ipynb

@@ -47,13 +47,13 @@
     "  `python -m unittest climada.x.test_y.TestY.test_z`\\\n",
     "  _Interactively:_ \\\n",
     "  `climada.x.test_y.TestY().test_z()`\n",
-    "- __Right after implementation.__ In case the coverage analysis shows that there are missing tests, see [Test Coverage](#CICover).\n",
-    "- __Later, when a bug was encountered.__ Whenever a bug gets fixed, also the tests need to be adapted or amended. "
+    "- __Right after implementation.__ In case the coverage analysis shows that there are missing tests, see [Test Coverage](#test-coverage).\n",
+    "- __Later, when a bug was encountered.__ Whenever a bug gets fixed, also the tests need to be adapted or amended."
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
+   "id": "5819e8c6",
    "metadata": {},
    "source": [
     "### Basic Test Procedure\n",
@@ -323,7 +323,7 @@
     "```\n",
     "make integ_test\n",
     "```\n",
-    "It lasts about 15 minutes and runs extensive integration tests, during which also data from external resources is read. An open internet connection is required for a successful test run. \n",
+    "It lasts about 15 minutes and runs extensive integration tests, during which also data from external resources is read. An open internet connection is required for a successful test run.\n",
     "\n",
     "### Coverage\n",
     "\n",

doc/development/dev-git.rst

@@ -6,7 +6,7 @@ This developer guide regroups all information intended for contributors.
 
 Very minimal instruction for contributing can be found below.
 
-If you are interested in contributing to Climada, we recommand you to start with the
+If you are interested in contributing to CLIMADA, we recommand you to start with the
 :doc:`Overview <Guide_CLIMADA_Development>` part of this guide.
 
 .. include:: ../../CONTRIBUTING.md
@@ -18,7 +18,8 @@ If you are interested in contributing to Climada, we recommand you to start with
    :hidden:
 
    Overview <Guide_CLIMADA_Development>
-   Developing with Git <dev-git>
+   Development with Git <Guide_Git_Development>
+   Guide_continuous_integration_GitHub_actions
    Coding in python <coding-in-python>
    CLIMADA Coding Conventions <Guide_CLIMADA_conventions>
    CLIMADA Configuration convention <Guide_Configuration>

doc/development/index.rst

@@ -5,23 +5,23 @@ Getting started
 Quick Installation
 --------------------
 
+The simple CLIMADA installation only requires the `mamba` (or `conda`) python environment manager (look :ref:`here <install-manager>`).
 
-
-Are you already working with mamba or conda? proceed to install CLIMADA by executing the following line in the terminal::
+If you are already working with mamba or conda, you can install CLIMADA by executing the following line in the terminal:
 
     mamba create -n climada_env -c conda-forge climada
 
-Each time you will want to work with CLIMADA, simply activate the environnment::
+Each time you will want to work with CLIMADA, simply activate the environment::
 
     mamba activate climada_env
 
 You are good to go!
 
 .. seealso::
 
-   You don't have mamba or conda installed or you are looking for advanced installation instructions? Look up our :doc:`detailed instructions <install>` on CLIMADA installation.
+   You don't have mamba or conda installed, or you are looking for advanced installation instructions? Look up our :doc:`detailed instructions <install>` on CLIMADA installation.
 
-Climada in a Nutshell
+CLIMADA in a Nutshell
 ---------------------
 
 .. dropdown:: How does CLIMADA compute impacts ?
@@ -33,7 +33,7 @@ Climada in a Nutshell
    (e.g., population, infrastructure), and applies vulnerability functions that estimate damage
    given the hazard intensity. By aggregating these results, CLIMADA calculates expected
    impacts, such as economic losses or affected populations. See the dedicated :doc:`impact tutorial </user-guide/climada_engine_Impact>`
-   for more informations.
+   for more information.
 
    .. image:: /user-guide/img/risk_framework.png
       :width: 400
@@ -43,7 +43,7 @@ Climada in a Nutshell
 .. dropdown:: How do you create a Hazard ?
    :color: primary
 
-   From a risk perspective, the intersting aspect of a natural hazard is its location and intensity. For such,
+   From a risk perspective, the interesting aspect of a natural hazard is its location and intensity. For such,
    CLIMADA allows you to load your own :doc:`hazard </user-guide/climada_hazard_Hazard>` data or to directly define it in the platform. As an example,
    users can easily load historical tropical cyclone tracks (IBTracks) and apply stochastic methods to generate
    a larger ensemble of tracks from the historical ones, from which they can easily compute the maximal windspeed,

doc/getting-started/index.rst

@@ -14,6 +14,8 @@ All following instructions should work on any operating system (OS) that is supp
 
 .. hint:: If you need help with the vocabulary used on this page, refer to the :ref:`Glossary <install-glossary>`.
 
+.. _install-manager:
+
 ---------------------------
 Install environment manager
 ---------------------------
@@ -226,6 +228,24 @@ For advanced Python users or developers of CLIMADA, cloning the CLIMADA reposito
    If this test passes, great!
    You are good to go.
 
+.. _change-branch:
+
+How to switch branch
+^^^^^^^^^^^^^^^^^^^^^^
+
+Advanced users, or reviewers, may also want to check the feature of a specific branch other than develop.
+To do so, **assuming you did install CLIMADA in editable mode (`pip install` with the `-e` flag)**, you just have to:
+
+```
+git fetch
+git checkout <branch>
+git pull
+```
+
+This will work most of the time, except if the target branch defines new dependencies that you don't have already in your environment (as they will not get installed this way), in that case you can install these dependencies yourself, or create a new environment with the *new* requirements from the branch.
+
+If you did not install CLIMADA in editable mode, you can also reinstall CLIMADA from its folder after switching the branch (`pip install [-e] ./`).
+
 .. _devdeps:
 
 Install Developer Dependencies (Optional)

doc/getting-started/install.rst

@@ -4,17 +4,17 @@
 Welcome to CLIMADA!
 ===================
 
-.. raw:: html
-
-    <div class="hero">
-      <b style="font-size: 1.5rem; display: block;">CLIMADA (CLIMate ADAptation)</b>
-      <p style="font-size: 1.5rem; display: block;">
-        is a free and open-source software framework for climate risk assessment and
-        adaptation option appraisal. Designed by a large scientific community, it
-        helps reasearchers, policymakers, and businesses analyse the impacts of
-        natural hazards and explore adaptation strategies.
-      </p>
-    </div>
+.. card:: CLIMADA (CLIMate ADAptation)
+   :text-align: center
+   :width: 75%
+   :margin: auto
+
+   CLIMADA is a free and open-source software framework for climate risk assessment and
+   adaptation option appraisal.
+   Designed by a large scientific community, it
+   helps researchers, policymakers, and businesses analyse the impacts of
+   natural hazards and explore adaptation strategies.
+
 
 CLIMADA is primarily developed and maintained by the `Weather and Climate Risks
 Group <https://wcr.ethz.ch/>`_ at `ETH Zürich <https://ethz.ch/en.html>`_.
@@ -31,12 +31,14 @@ specialized applications can be found in the `CLIMADA Petals
 **Useful links:** `WCR Group <https://wcr.ethz.ch/>`_ | `CLIMADA Petals <https://climada-petals.readthedocs.io/en/stable/>`_ | `CLIMADA website <https://climada.ethz.ch>`_ | `Mailing list <https://sympa.ethz.ch/sympa/info/climada-users>`_
 
 .. grid:: 1 2 2 2
-    :gutter: 4
-    :padding: 2 2 0 0
+    :margin: 5
+    :gutter: 0 2 3 4
+    :padding: 0 0 2 2
     :class-container: sd-text-center
 
     .. grid-item-card:: Getting Started
         :shadow: md
+        :width: 75%
 
         Getting started with CLIMADA: How to install?
         What are the basic concepts and functionalities?
@@ -52,6 +54,7 @@ specialized applications can be found in the `CLIMADA Petals
 
     .. grid-item-card:: User Guide
         :shadow: md
+        :width: 75%
 
         Want to go more in depth? Check out the User guide. It contains detailed
         tutorials on the different concepts, modules and possible usage of CLIMADA.
@@ -70,6 +73,7 @@ specialized applications can be found in the `CLIMADA Petals
 
     .. grid-item-card::  Implementation API reference
         :shadow: md
+        :width: 75%
 
         The reference guide contains a detailed description of
         the CLIMADA API. The API reference describes each module, class,
@@ -87,6 +91,7 @@ specialized applications can be found in the `CLIMADA Petals
 
     .. grid-item-card::  Developer guide
         :shadow: md
+        :width: 75%
 
         Saw a typo in the documentation? Want to improve
         existing functionalities? Want to extend them?