Update installation guide (#1296)

* Fix formatting errors.
* Move switching branches to FAQ.
* Fix some links.

Author: peanutfun

doc/development/Guide_CLIMADA_Development.ipynb

@@ -141,6 +141,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "(dev-pre-commit-hooks)=\n",
+    "\n",
     "### Pre-Commit Hooks\n",
     "\n",
     "Climada developer dependencies include pre-commit hooks to help ensure code linting and formatting.\n",

doc/getting-started/install.rst

@@ -74,7 +74,7 @@ Depening on your level of expertise, we provide two different approaches:
 * If you have never worked with a command line, or if you just want to give CLIMADA a try, follow the :ref:`simple instructions <install-simple>`.
 * If you want to use the very latest development version of CLIMADA or even develop new CLIMADA code, follow the :ref:`advanced instructions <install-advanced>`.
 
-Both approaches are not mutually exclusive.
+Both approaches are **not** mutually exclusive.
 After successful installation, you may switch your setup at any time.
 
 .. _petals-notes:
@@ -146,9 +146,9 @@ These instructions will install the most recent stable version of CLIMADA withou
 
 .. _install-pixi:
 
--------------------
+-------------------------------------------
 Simple Instructions with Pixi (Alternative)
--------------------
+-------------------------------------------
 
 As an alternative to mamba `Pixi`_ can be used to install climada from conda-forge.
 Pixi is a modern package manager, based on Conda, that offers much faster dependency resolution.
@@ -159,8 +159,6 @@ Pixi is a modern package manager, based on Conda, that offers much faster depend
 
       pixi init climada_pixi
 
-.. _install-simple:
-
 #. Add CLIMADA from ``conda-forge``:
 
    .. code-block:: shell
@@ -194,6 +192,7 @@ Advanced Instructions: Installing from source
 ---------------------------------------------
 
 For advanced Python users or developers of CLIMADA, cloning the CLIMADA repository and installing the package from source.
+Installing from source also allows you to :ref:`switch branches <switch-branch>`.
 
 .. warning::
 
@@ -283,24 +282,6 @@ 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)
@@ -311,8 +292,7 @@ They are also not needed for using CLIMADA.
 However, if you want to develop CLIMADA, we strongly recommend you install them.
 
 With the ``climada_env`` activated, enter the workspace directory and then the CLIMADA repository as above.
-Then, add the ``test`` extra specification to the ``pip install`` command (**mind the quotation marks**,
-and see also `pip install examples <https://pip.pypa.io/en/stable/cli/pip_install/#examples>`_):
+Then, add the ``test`` extra specification to the ``pip install`` command (**mind the quotation marks**, and see also `pip install examples <https://pip.pypa.io/en/stable/cli/pip_install/#examples>`_):
 
 .. code-block:: shell
 
@@ -339,7 +319,7 @@ With the ``climada_env`` activated, execute
 
    pre-commit install
 
-Please refer to the `guide on pre-commit hooks <../development/Guide_CLIMADA_Development.html#pre-commit-hooks>`_ for information on how to use this tool.
+Please refer to the :ref:`guide on pre-commit hooks <dev-pre-commit-hooks>` for information on how to use this tool.
 
 For executing the pre-defined test scripts in exactly the same way as they are executed by the automated CI pipeline, you will need ``make`` to be installed.
 On macOS and on Linux it is pre-installed. On Windows, it can easily be installed with Conda:
@@ -348,7 +328,7 @@ On macOS and on Linux it is pre-installed. On Windows, it can easily be installe
 
    mamba install -n climada_env make
 
-Instructions for running the test scripts can be found in the `Testing Guide <../development/Guide_Testing.html>`_.
+Instructions for running the test scripts can be found in the :doc:`Testing Guide </development/Guide_Testing>`.
 
 Install CLIMADA Petals (Optional)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -382,9 +362,9 @@ To install CLIMADA Petals, we assume you have already installed CLIMADA Core wit
       python -m pip install -e ./
 
 
----------------------------------------
+------------
 Code Editors
----------------------------------------
+------------
 
 JupyterLab
 ^^^^^^^^^^
@@ -513,9 +493,9 @@ Therefore, we recommend installing Spyder in a *separate* environment, and then
 #. Set the Python interpreter used by Spyder to the one of ``climada_env``.
    Select *Preferences* > *Python Interpreter* > *Use the following interpreter* and paste the iterpreter path you copied from the ``climada_env``.
 
----------------------------------------
+-----------------------------
 Apps for working with CLIMADA
----------------------------------------
+-----------------------------
 
 To work with CLIMADA, you will need an application that supports Jupyter Notebooks.
 There are plugins available for nearly every code editor or IDE, but if you are unsure about which to choose, we recommend `JupyterLab <https://jupyterlab.readthedocs.io/en/stable/>`_, `Visual Studio Code <https://code.visualstudio.com/>`_ or `Spyder <https://www.spyder-ide.org/>`_.
@@ -571,8 +551,8 @@ Answers to frequently asked questions.
 
 .. _update-climada:
 
-Updating CLIMADA
-^^^^^^^^^^^^^^^^
+How to update CLIMADA?
+^^^^^^^^^^^^^^^^^^^^^^
 
 We recommend keeping CLIMADA up-to-date.
 To update, follow the instructions based on your :ref:`installation type <install-choice>`:
@@ -600,6 +580,30 @@ To update, follow the instructions based on your :ref:`installation type <instal
 
   The same instructions apply for CLIMADA Petals.
 
+.. _switch-branch:
+
+How to switch branches?
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This is only available for :ref:`advanced installations <install-advanced>` from source.
+
+If you want to check out or review a specific feature, you may want to switch to a `Git branch <https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell>`_ other than ``develop``.
+To switch to a new branch, open a terminal and move to the CLIMADA repository.
+Then fetch the latest changes from the remote, switch to the target branch, and update your local version:
+
+.. code-block:: shell
+
+   cd <path/to/workspace>/climada_python
+   git fetch
+   git checkout <branch>
+   git pull
+
+After switching, it is good practice to :ref:`update your environment <update-climada>`, as the dependency definitions might have been changed.
+In rare cases, updating the environment might fail after switching a branch because the dependency updates are incompatible.
+If this happens, create a new environment (see the :ref:`advanced instructions <install-advanced>`).
+
+The above instructions also apply for CLIMADA Petals, but you have to ``cd`` into the ``climada_petals`` repository in the first step, of course.
+
 .. _install-more-packages:
 
 Installing More Packages
@@ -679,12 +683,12 @@ the level set to ``WARNING``.
 
 If you prefer another logging configuration, e.g., for using Climada embedded in another application,
 you can opt out of the default pre-configuration by setting the config value for
-``logging.climada_style`` to ``false`` in the :doc:`configuration file <../development/Guide_Configuration>`
+``logging.climada_style`` to ``false`` in the :doc:`configuration file </development/Guide_Configuration>`
 ``climada.conf``.
 
 Changing the logging level can be done in multiple ways:
 
-* Adjust the :doc:`configuration file <../development/Guide_Configuration>` ``climada.conf`` by setting a the value of the ``global.log_level`` property.
+* Adjust the :doc:`configuration file </development/Guide_Configuration>` ``climada.conf`` by setting a the value of the ``global.log_level`` property.
   This only has an effect if the ``logging.climada_style`` is set to ``true`` though.
 
 * Set a global logging level in your Python script: