Repository: Deltares/hydromt_wflow
Pull request #376: Improve installation docs 
Author: login: aslowwriter
Created: 2025-04-14T09:28:14Z | Merged: 2025-04-17T10:46:40Z

## Issue addressed
Fixes #324 

## Explanation
I think it's better to have instructions stand on it's own so I copied some stuff from core. Other than that I just added the warning about the commercial stuff in anaconda, and expanded the explanations of pixi. Since pixi is also the preferred way to setup development envs because of the tasks etc. I also expanded on that in the dev install guide. This also aligns us better with the install guide of core. 

## Checklist
- [x] Updated tests or added new tests
- [x] Branch is up to date with `main`
- [x] Tests & pre-commit hooks pass
- [x] Updated documentation if needed

## Additional Notes (optional)
Add any additional notes or information that may be helpful.


Linked issue #324: Improve installation guide in the docs
### HydroMT-Wflow version checks

- [x] I have checked that the issue still exists on the latest versions of the docs on `main` [here](https://github.com/Deltares/hydromt_wflow)


### Kind of issue

Docs are unclear

### Location of the documentation

https://deltares.github.io/hydromt_wflow/latest/getting_started/installation.html

### Documentation problem

Installation through mamba or conda may give some warnings like:

`warning  libmamba 'repo.anaconda.com', a commercial channel hosted by Anaconda.com, is used.`

It might be worth to emphasize the use of only conda-forge as a channel due to licensing, and encourage users to use miniforge. Also, the link to the HydroMT Core docs is broken


Additionally, HydroMT Core encourages the use of pixi, while HydroMT Wflow uses mamba/conda. Should this be addressed/mentioned before it might raise confusion?

### Suggested fix for documentation

- Adding a tip or warning to use miniforge which only has the conda-forge channel installed?
- Mention something about Pixi?
Linked issue comments: user: login: shartgring
created_at: 2025-04-17T11:25:45Z
body: Thanks @savente93 I see the updated docs now and looks good :) I think you convinced me to switch to Pixi, didn't know it was that fast and convenient to be honest
author_association: COLLABORATOR
user: login: aslowwriter
created_at: 2025-04-17T11:38:12Z
body: ha, a nice unintended consequence 😂 
author_association: CONTRIBUTOR

Diff:
diff --git a/docs/changelog.rst b/docs/changelog.rst
index f5e0494cf..8da054eb1 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -18,6 +18,7 @@ Changed
 
 Fixed
 -----
+- Updated installation guide (#376)
 
 Deprecated
 ----------
diff --git a/docs/dev_guide/dev_install.rst b/docs/dev_guide/dev_install.rst
index 183ef85f0..7fc67e8c9 100644
--- a/docs/dev_guide/dev_install.rst
+++ b/docs/dev_guide/dev_install.rst
@@ -14,38 +14,41 @@ the code folder (where the envs folder and pyproject.toml are located):
     $ git clone https://github.com/Deltares/hydromt_wflow.git
     $ cd hydromt_wflow
 
-The next step is to create an environment yaml.
-This is done by calling the `make_env.py` script from commandline:
-(This requires the presence of the package `tomli` or Python 3.11)
+once you are in the directory you can install the environment using pixi with
 
 .. code-block:: console
 
-    $ python make_env.py full
+    $ pixi install
 
-The 'full' argument guarantees all the necessary tools!
-Now create the environment using conda and activate it:
+Afterwards you can run any of the tasks we defined for doing things such as running the test suite:
 
 .. code-block:: console
 
-    $ conda env create -f environment.yml
-    $ conda activate hydromt_wflow
+    $ pixi run test
 
-If you wish to make changes in HydroMT-Wflow, you should make an editable install of the plugin.
-This can be done with:
+generating the documentation:
 
 .. code-block:: console
 
-    $ pip install -e .
+    $ pixi run docs-html
 
-If you encounter issues with the installation of some packages, you might consider cleaning conda to remove unused packages and caches.
-This can be done through the following command from your base environment:
+We have several environments to make sure we can test ``hydromt_wflow`` under, for example,
+with all of the different python versions we support. The default environment should have
+everything you need, but if you want to run something (for example in CI) from a specific
+environment you can do so like this:
 
 .. code-block:: console
 
-    $ conda clean -a
+  $ pixi -e test-full-py311 run path/to/script.py
 
-It may also be advisable to clear pip's cache:
+
+Editors like vscode should be able to find pixi environments you make automatically,
+however if you use something else like ``vim`` or ``helix`` then you can make sure they run in
+the context of your environment:
 
 .. code-block:: console
 
-    $ pip cache purge
+    $ pixi run hx .
+
+this will make sure your LSP can find your environment so it can give you proper
+tab completion and other warnings if necessary.
diff --git a/docs/getting_started/installation.rst b/docs/getting_started/installation.rst
index e1de742e4..f539cf655 100644
--- a/docs/getting_started/installation.rst
+++ b/docs/getting_started/installation.rst
@@ -4,94 +4,201 @@
 Installation Guide
 ==================
 
-Prerequisites
-=============
-For more information about the prerequisites for an installation of the HydroMT package
-and related dependencies, please visit the documentation of
-`HydroMT core <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
 
-Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
+.. _optional_dependencies:
 
-- `toml <https://github.com/uiri/toml>`_
-- `pcraster <https://pcraster.geo.uu.nl>`_ (optional)
-- `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
-- `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
+Optional Dependencies
+=====================
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+HydroMT-Wflow has several optional dependencies that need to be installed in your environment to enable specific
+functionalities, though they are not necessary for hydromt-wflow to function as a whole. Due to limitations in the conda-forge
+package specification you will have to install these yourself in addition to hydromt-wflow if you want to use them.
 
-.. code-block:: console
-
-  $ conda install mamba -n base -c conda-forge
+They are:
+- `pcraster <https://pcraster.geo.uu.nl>`_ This one is used for the reading and writing of pcr maps. Note that this one is only available on conda-forge so if you install hydromt-wflow through pypi you will not be able to access this functionality.
+- `gwwapi <https://github.com/global-water-watch/gww-api>`_ This one is used for providing more resources about reservoirs and how to set them up. This one is only available through pypi at the moment.
+- `hydroengine <https://github.com/openearth/hydro-engine>`_ Similar to ``gwwapi`` the ``hydroengine`` package gives access to more data sources, and is currently only available through pypi.
+- `wradlib <https://github.com/wradlib/wradlib>`_ This package provides downloading and processing functionalities of radar weather data.
+- `pyet <https://github.com/pyet-org/pyet>`_ Provides processing functionalities of evapotranspriation.
+- `gdal <https://gdal.org/en/stable/>`_ Provides many drivers and GIS transformations.  Only available through conda-forge.
 
+Since some dependencies are only availabe through conda-forge and some only through pypi, you will need a packange manager that can handle both.
 
 Installation
 ============
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
+
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
 
-.. Note::
+.. _user_install_pixi:
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+Installation using Pixi
+-----------------------
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
 .. Tip::
 
     This is our recommended way of installing HydroMT-Wflow!
 
-You can install HydroMT-Wflow in a new environment called `hydromt-wflow`:
+
+If you do not have a ``pyproject.toml`` yet you can make one by executing the command:
+
+.. code-block:: console
+
+    $ pixi init --format pyproject myproject
+
+
+A new folder with a ``pyproject.toml`` called ``myproject`` will be created for you. After this, you can
+navigate to this new directory and add ``hydromt_wflow`` as a dependency:
+
+.. code-block:: console
+
+    $ pixi add hydromt_wflow[extra] --pypi
+
+Pixi will then add it as a dependency to the project. The ``[extra]`` instruct pixi to also
+include some optional dependencies.
+
+If you don't want these extra dependencies (or need specific versions, or only want some)
+
+You can also add it like so:
+
+.. code-block:: console
+
+    $ pixi add hydromt_wflow
+
+This will install hydromt_wflow from conda-forge without any of the optional dependencies
+which you can then add yourself afterwards as you like:
+
+.. code-block:: console
+
+  $ pixi add gwwapi --pypi
+  $ pixi add hydroengine --pypi
+  $ pixi add pcraster
+  $ pixi add wradlib
+  $ pixi add pyet
+  $ pixi add gdal
+
+the ``--pypi`` in this case is necessary because these dependencies are only available through pypi and not conda-forge
+adding this flag will tell pixi to install them from there.
+
+For a more indepth explanation on the dependencies see :ref:`this section <optional_dependencies>`.
+
+Once you have your new (or existing ``pyproject.toml``) file install the pixi
+environment and activate it with the following commands to be able to start using it:
+
+.. code-block:: console
+
+    $ pixi install
+    $ pixi shell activate
+
+
+If you did activate the shell like above you should now be able to run any python script like usual:
 
 .. code-block:: console
 
-  $ mamba create -n hydromt-wflow -c conda-forge hydromt_wflow
+  (hydromt-wflow) $ python path/to/script.py
 
-Then, activate the environment (as stated by mamba/conda) to start making use of HydroMT-Wflow:
-HydroMT-Wflow will be installed together with all optional (see above) and a few additional dependencies with:
+If you did not activate the shell you can still run the script in the environment by running it through pixi:
+
+.. code-block:: console
+
+  (hydromt-wflow) $ pixi run path/to/script.py
+
+If you intend to only use ``hydromt_wflow`` via the cli you can also install it globally using pixi like so:
+
+.. code-block:: console
+
+  $ pixi global install hydromt_wflow
+
+This will install hydromt_wflow in an isolated environment for you and make it available to run from basically
+anywhere on your system through the commandline
+
+
+.. _user_install_conda:
+
+Installation using Conda
+------------------------
+
+.. warning::
+
+  Due to the changes Anaconda made to their `lisencing agreements in 2024 <https://legal.anaconda.com/policies/en/?name=terms-of-service#anaconda-terms-of-service>`
+  using any packages from the anaconda channel (which is available by default in the main `conda` and `mamba` distributions) may require a paid license.
+  Therefore we highly recommend you only use the free and community maintained `conda-forge` channel. While you can configure existing `conda` / `mamba`
+  installations to do this correctly, we recommend that if you do not want to use pixi, that you use a `miniforge<https://github.com/conda-forge/miniforge>` distribution which has this correctly
+  configured by default.
+
+You can install HydroMT-Wflow in a new environment called ``hydromt-wflow``:
+
+.. code-block:: console
+
+  $ conda create -n hydromt-wflow -c conda-forge hydromt_wflow
+
+Then, activate the environment (as stated by mamba/conda depending on which you are using) to start making use of that environment:
 
 .. code-block:: console
 
   $ conda activate hydromt-wflow
 
+After it has been activated you can install hydromt-wflow into it using this command:
+
+.. code-block:: console
+
+  (hydromt-wflow) $ conda install hydromt_wflow
+
 .. Tip::
 
     If you already have this environment with this name either remove it with
     `conda env remove -n hydromt-wflow` **or** set a new name for the environment
     by changing `-n <name>` to the name of your new environment.
 
-.. Note::
-
-    Please take into account that gwwapi or hydroengine packages are not available from conda and therefore have to be installed from pypi separately (in the activated environment).
+After you have installed ``hydromt_wflow`` in your environment you will also need to add
+the optional dependencies to it, if you want to make use of all the functionalities available:
 
 .. code-block:: console
 
-  $ pip install gwwapi
-  $ pip install hydroengine
+  (hydromt-wflow) $ pip install gwwapi
+  (hydromt-wflow) $ pip install hydroengine
+  (hydromt-wflow) $ conda install pcraster
+  (hydromt-wflow) $ conda install wradlib
+  (hydromt-wflow) $ conda install pyet
+  (hydromt-wflow) $ conda install gdal
+
+For a more indepth explanation on the dependencies see :ref:`this section <optional_dependencies>`.
 
 Install HydroMT-Wflow in an existing environment
 ------------------------------------------------
 
 To install HydroMT-Wflow in an existing environment execute the command below
-where you replace `<environment_name>` with the name of the existing environment.
+where you replace ``<environment_name>`` with the name of the existing environment.
 Note that if some dependencies are not installed from conda-forge but from other
 channels the installation may fail.
 
 .. code-block:: console
 
-  $ mamba install -c conda-forge hydromt_wflow -n <environment_name>
+  $ conda install -c conda-forge hydromt_wflow -n <environment_name>
+
+.. code-block:: console
 
-.. Note::
+  $ conda activate <environment_name>
 
-    Please take into account that gwwapi or hydroengine packages are not available from conda and therefore have to be installed from pypi separately.
+After you have installed ``hydromt_wflow`` in your environment you will also need to add
+the optional dependencies to it, if you want to make use of all the functionalities available:
 
 .. code-block:: console
 
-  $ conda activate <environment_name>
-  $ pip install gwwapi
-  $ pip install hydroengine
+  (<environment_name>) $ pip install gwwapi
+  (<environment_name>) $ pip install hydroengine
+  (<environment_name>) $ conda install pcraster
+  (<environment_name>) $ conda install wradlib
+  (<environment_name>) $ conda install pyet
+  (<environment_name>) $ conda install gdal
+
+For a more indepth explanation on the dependencies see :ref:`this section <optional_dependencies>`.
+
 
 Developer install
 ==================
diff --git a/pixi.lock b/pixi.lock
index 93909db0d..4ec1cd00a 100644
--- a/pixi.lock
+++ b/pixi.lock
@@ -6629,7 +6629,7 @@ packages:
 - pypi: .
   name: hydromt-wflow
   version: 0.8.1.dev0
-  sha256: 603dfdf7b763d2912c39f267e2cb45cd345e469f1b3c9226325fe285f17510da
+  sha256: e33a34ed81465d90ba35065a52268199b3433a61f0ee36f06a489d893fcd5d03
   requires_dist:
   - dask
   - geopandas>=0.10
diff --git a/pyproject.toml b/pyproject.toml
index d03a96ece..47614ef3b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -164,6 +164,8 @@ docs-html = { cmd = [
   "docs/_build",
   "-W",
 ] }
+doc = { depends-on = ["docs-html"]}
+docs = { depends-on = ["docs-html"]}
 docs-html-rebuild = { depends-on = ["clean-docs", "docs-html"] }
 serve = { cmd = [
   "python",


Reviews:
user: login: deltamarnix
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-14T14:53:21Z
user: login: deltamarnix
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-14T14:54:04Z
user: login: deltamarnix
body: I would write the installation.rst in reverse order. Just start with `pixi init` and maybe just add that it's easiest to do `pixi add --pypi hydromt[full]`, so that the user gets everything.
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-14T15:00:16Z
user: login: deltamarnix
body: Almost there. There is still some confusion for me with the optional dependencies. Some of them are pypi only, others are conda only. That makes it confusing. Can we make that simpler for users?
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-15T12:22:46Z
user: login: aslowwriter
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-15T12:27:54Z
user: login: deltamarnix
body: Let's change the conda recipe for this PR and add all optionals directly to the recipe. This would be in line with how applications like xarray do it.
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-16T10:25:51Z
user: login: aslowwriter
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-16T11:40:08Z
user: login: aslowwriter
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-16T11:40:28Z
user: login: deltamarnix
body: Still needs some more information for the conda optionals.
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-16T11:51:01Z
user: login: aslowwriter
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-16T11:55:39Z
user: login: LuukBlom
body: Looks like good improvements to me! 

I have one note/question on the optional dependencies.
Why do we tell users to manually install specific optional packages? Should this not be taken care of by the `extra`  / `optional` dependencies defined in the pyproject.toml file? 

Users would add `hydromt_wflow['extra']` to their pyproject.toml and get all optional dependencies.
If they have overlapping packages in their environment already, in other words, the packages would be in their pyproject.toml/env already. Both conda and pixi would try to resolve it with all constraints in mind. 

The information is correct, just wondering if it is necessary to explain or would be better to remove for conciseness. 
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-17T08:26:03Z
user: login: aslowwriter
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-17T09:02:46Z
user: login: LuukBlom
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-17T09:57:49Z
user: login: LuukBlom
body: LGTM
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-04-17T09:59:07Z

Review comments:
diff_hunk: @@ -28,34 +30,123 @@ we recommend installing it into your *base* environment using:
 Installation
 ============
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
 
-.. Note::
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
 .. Tip::
 
     This is our recommended way of installing HydroMT-Wflow!
 
+You can add HydroMT-Wflow to any python environment that is defined in either a `pyproject.toml` or `pixi.toml` by
+running the command:
+
+.. code-block:: shell
+
+    $ pixi add hydromt_wflow
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: I would maybe write here:

```sh
    $ pixi init myproject
    $ cd myproject
    $ pixi add hydromt_wflow
```

So that it's clear that you are starting a new project.
created_at: 2025-04-14T14:53:21Z
author_association: CONTRIBUTOR
diff_hunk: @@ -28,34 +30,123 @@ we recommend installing it into your *base* environment using:
 Installation
 ============
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
 
-.. Note::
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
 .. Tip::
 
     This is our recommended way of installing HydroMT-Wflow!
 
+You can add HydroMT-Wflow to any python environment that is defined in either a `pyproject.toml` or `pixi.toml` by
+running the command:
+
+.. code-block:: shell
+
+    $ pixi add hydromt_wflow
+
+
+Pixi will then it as a dependency to either your `pyproject.toml` or `pixi.toml` depending on which it can find
+(in that order or precedence).
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: ```suggestion
Pixi will then add it as a dependency to the pixi project.
```
created_at: 2025-04-14T14:54:04Z
author_association: CONTRIBUTOR
diff_hunk: @@ -14,38 +14,41 @@ the code folder (where the envs folder and pyproject.toml are located):
     $ git clone https://github.com/Deltares/hydromt_wflow.git
     $ cd hydromt_wflow
 
-The next step is to create an environment yaml.
-This is done by calling the `make_env.py` script from commandline:
-(This requires the presence of the package `tomli` or Python 3.11)
+once you are in the directory you can install the environment using pixi with
 
 .. code-block:: console
 
-    $ python make_env.py full
+    $ pixi install
 
-The 'full' argument guarantees all the necessary tools!
-Now create the environment using conda and activate it:
+Afterwards you can run any of the tasks we defined for doing things such as running the test suite:
 
 .. code-block:: console
 
-    $ conda env create -f environment.yml
-    $ conda activate hydromt_wflow
+    $ pixi run test
 
-If you wish to make changes in HydroMT-Wflow, you should make an editable install of the plugin.
-This can be done with:
+generating the documentation:
 
 .. code-block:: console
 
-    $ pip install -e .
+    $ pixi run docs-html
 
-If you encounter issues with the installation of some packages, you might consider cleaning conda to remove unused packages and caches.
-This can be done through the following command from your base environment:
+We have several environments to make sure we can test ``hydromt_wflow`` under, for example,
+with all of the different python versions we support. The default environment should have
+everything you need, but if you want to run something (for example in CI) from a specific
+environment you can do so like this:
 
 .. code-block:: console
 
-    $ conda clean -a
+  $ pixi -e test-full-py311 run path/to/script.py
 
-It may also be advisable to clear pip's cache:
+
+Editors like vscode should be able to find pixi environments you make automatically,
+however if you use something else like `vim` or `helix` then you can make sure they run in
+the context of your environment:
path: docs/dev_guide/dev_install.rst
user: login: deltamarnix
body: I would also recommend `pixi run code .`, because it ensures that mypy and everything is found. Or is that already fixed nowadays?
created_at: 2025-04-15T12:10:56Z
author_association: CONTRIBUTOR
diff_hunk: @@ -14,38 +14,41 @@ the code folder (where the envs folder and pyproject.toml are located):
     $ git clone https://github.com/Deltares/hydromt_wflow.git
     $ cd hydromt_wflow
 
-The next step is to create an environment yaml.
-This is done by calling the `make_env.py` script from commandline:
-(This requires the presence of the package `tomli` or Python 3.11)
+once you are in the directory you can install the environment using pixi with
 
 .. code-block:: console
 
-    $ python make_env.py full
+    $ pixi install
 
-The 'full' argument guarantees all the necessary tools!
-Now create the environment using conda and activate it:
+Afterwards you can run any of the tasks we defined for doing things such as running the test suite:
 
 .. code-block:: console
 
-    $ conda env create -f environment.yml
-    $ conda activate hydromt_wflow
+    $ pixi run test
 
-If you wish to make changes in HydroMT-Wflow, you should make an editable install of the plugin.
-This can be done with:
+generating the documentation:
 
 .. code-block:: console
 
-    $ pip install -e .
+    $ pixi run docs-html
 
-If you encounter issues with the installation of some packages, you might consider cleaning conda to remove unused packages and caches.
-This can be done through the following command from your base environment:
+We have several environments to make sure we can test ``hydromt_wflow`` under, for example,
+with all of the different python versions we support. The default environment should have
+everything you need, but if you want to run something (for example in CI) from a specific
+environment you can do so like this:
 
 .. code-block:: console
 
-    $ conda clean -a
+  $ pixi -e test-full-py311 run path/to/script.py
 
-It may also be advisable to clear pip's cache:
+
+Editors like vscode should be able to find pixi environments you make automatically,
+however if you use something else like `vim` or `helix` then you can make sure they run in
+the context of your environment:
 
 .. code-block:: console
 
-    $ pip cache purge
+    $ pixi run hx .
+
+this will make sure your LSP can find your environment so it can give you proper
+tabcompletion and other warnings if necessary.
path: docs/dev_guide/dev_install.rst
user: login: deltamarnix
body: ```suggestion
tab completion and other warnings if necessary.
```
created_at: 2025-04-15T12:11:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -4,11 +4,13 @@
 Installation Guide
 ==================
 
+
+
 Prerequisites
 =============
 For more information about the prerequisites for an installation of the HydroMT package
 and related dependencies, please visit the documentation of
-`HydroMT core <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
+`HydroMT core <https://deltares.github.io/hydromt/stable/guides/user_guide/installation.html>`_
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: ```suggestion
`HydroMT core <https://deltares.github.io/hydromt/latest/guides/user_guide/installation.html>`_
```
created_at: 2025-04-15T12:11:29Z
author_association: CONTRIBUTOR
diff_hunk: @@ -17,45 +19,117 @@ Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
 - `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
 - `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: Should wradlib and pyet also be in this list?
created_at: 2025-04-15T12:13:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -17,45 +19,117 @@ Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
 - `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
 - `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+Installation
+============
+
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
+
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
+
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
+
+.. Tip::
+
+    This is our recommended way of installing HydroMT-Wflow!
+
+
+If you do not have a ``pyproject.toml`` yet you can make one by executing the command:
 
 .. code-block:: console
 
-  $ conda install mamba -n base -c conda-forge
+    $ pixi init --format pyproject myproject
 
 
-Installation
-============
+A new folder with a ``pyproject.toml`` called ``myproject`` will be created for you. After this, you can
+navigate to this new directory and add ``hydromt_wflow`` as a dependency:
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+.. code-block:: console
 
-.. Note::
+    $ pixi add hydromt_wflow[full] --pypi
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: I was mistaken. `full` doesn't exist in the pyproject. Instead one should use:

```suggestion
    $ pixi add hydromt_wflow[extra, examples] --pypi
```

`full` doesn't exist and I don't think people really need everything. Only `extra` and `examples`.
created_at: 2025-04-15T12:17:01Z
author_association: CONTRIBUTOR
diff_hunk: @@ -17,45 +19,117 @@ Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
 - `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
 - `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+Installation
+============
+
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
+
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
+
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
+
+.. Tip::
+
+    This is our recommended way of installing HydroMT-Wflow!
+
+
+If you do not have a ``pyproject.toml`` yet you can make one by executing the command:
 
 .. code-block:: console
 
-  $ conda install mamba -n base -c conda-forge
+    $ pixi init --format pyproject myproject
 
 
-Installation
-============
+A new folder with a ``pyproject.toml`` called ``myproject`` will be created for you. After this, you can
+navigate to this new directory and add ``hydromt_wflow`` as a dependency:
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+.. code-block:: console
 
-.. Note::
+    $ pixi add hydromt_wflow[full] --pypi
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+Pixi will then add it as a dependency to the project. The ``[full]`` is to make sure you include all
+of the optional dependencies.
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
-.. Tip::
+You can also add the optional dependencies to it like so:
 
-    This is our recommended way of installing HydroMT-Wflow!
+.. code-block:: console
+
+  $ pixi add gwwapi --pypi
+  $ pixi add hydroengine --pypi
+  $ pixi add pcraster --pypi
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: pcraster is a conda dependency only, just like gdal. So I don't think pcraster --pypi will work.

Also, I miss pyet and wradlib.
created_at: 2025-04-15T12:18:26Z
author_association: CONTRIBUTOR
diff_hunk: @@ -17,45 +19,117 @@ Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
 - `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
 - `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+Installation
+============
+
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
+
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
+
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
+
+.. Tip::
+
+    This is our recommended way of installing HydroMT-Wflow!
+
+
+If you do not have a ``pyproject.toml`` yet you can make one by executing the command:
 
 .. code-block:: console
 
-  $ conda install mamba -n base -c conda-forge
+    $ pixi init --format pyproject myproject
 
 
-Installation
-============
+A new folder with a ``pyproject.toml`` called ``myproject`` will be created for you. After this, you can
+navigate to this new directory and add ``hydromt_wflow`` as a dependency:
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+.. code-block:: console
 
-.. Note::
+    $ pixi add hydromt_wflow[full] --pypi
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+Pixi will then add it as a dependency to the project. The ``[full]`` is to make sure you include all
+of the optional dependencies.
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
-.. Tip::
+You can also add the optional dependencies to it like so:
 
-    This is our recommended way of installing HydroMT-Wflow!
+.. code-block:: console
+
+  $ pixi add gwwapi --pypi
+  $ pixi add hydroengine --pypi
+  $ pixi add pcraster --pypi
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: ```suggestion
  $ pixi add gwwapi --pypi
  $ pixi add hydroengine --pypi
  $ pixi add pcraster
  $ pixi add --pypi wradlib
  $ pixi add --pypi pyet
  $ pixi add gdal
```
created_at: 2025-04-15T12:19:08Z
author_association: CONTRIBUTOR
diff_hunk: @@ -17,45 +19,117 @@ Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
 - `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
 - `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+Installation
+============
+
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
+
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
+
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
+
+.. Tip::
+
+    This is our recommended way of installing HydroMT-Wflow!
+
+
+If you do not have a ``pyproject.toml`` yet you can make one by executing the command:
 
 .. code-block:: console
 
-  $ conda install mamba -n base -c conda-forge
+    $ pixi init --format pyproject myproject
 
 
-Installation
-============
+A new folder with a ``pyproject.toml`` called ``myproject`` will be created for you. After this, you can
+navigate to this new directory and add ``hydromt_wflow`` as a dependency:
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+.. code-block:: console
 
-.. Note::
+    $ pixi add hydromt_wflow[full] --pypi
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+Pixi will then add it as a dependency to the project. The ``[full]`` is to make sure you include all
+of the optional dependencies.
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
-.. Tip::
+You can also add the optional dependencies to it like so:
 
-    This is our recommended way of installing HydroMT-Wflow!
+.. code-block:: console
+
+  $ pixi add gwwapi --pypi
+  $ pixi add hydroengine --pypi
+  $ pixi add pcraster --pypi
+
+the `--pypi` in this case is necessary because these dependencies are only available through pypi and not conda-forge
+adding this flag will tell pixi to install them from there.
+
+Once you have your new (or existing ``pyproject.toml``) file install the pixi
+environment and activate it with the following commands to be able to start using it:
+
+.. code-block:: console
+
+    $ pixi install
+    $ pixi shell activate
+
+
+If you did activate the shell like above you should now be able to run any python script like usual:
+
+.. code-block:: console
+
+  (hydromt-wflow) $ python path/to/script.py
+
+If you did not activate the shell you can still run the script in the environment by running it through pixi:
+
+.. code-block:: console
+
+  (hydromt-wflow) $ pixi run path/to/script.py
+
+If you intend to only use `hydromt_wflow` via the cli you can also install it globally using pixi like so:
+
+.. code-block:: console
+
+  $ pixi global install hydromt_wflow
+
+This will install hydromt_wflow in an isolated environment for you and make it available to run from basically
+anywhere on your system through the commandline
+
+
+.. _user_install_conda:
+
+Installation using Conda
+------------------------
+
+.. warning::
+
+  Due to the changes Anaconda made to their `lisencing agreements in 2024 <https://legal.anaconda.com/policies/en/?name=terms-of-service#anaconda-terms-of-service>`
+  using any packages from the anaconda channel (which is available by default in the main `conda` and `mamba` distributions) may require a paid license.
+  Therefore we highly recommend you only use the free and community maintained `conda-forge` channel. While you can configure existing `conda` / `mamba`
+  instaltions to do this correctly, we recommend that if you do not want to use pixi, that you use a `miniforge<https://github.com/conda-forge/miniforge>` distribution which has this correctly
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: ```suggestion
  installations to do this correctly, we recommend that if you do not want to use pixi, that you use a `miniforge<https://github.com/conda-forge/miniforge>` distribution which has this correctly
```
created_at: 2025-04-15T12:21:04Z
author_association: CONTRIBUTOR
diff_hunk: @@ -17,45 +19,117 @@ Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
 - `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
 - `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+Installation
+============
+
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
+
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
+
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
+
+.. Tip::
+
+    This is our recommended way of installing HydroMT-Wflow!
+
+
+If you do not have a ``pyproject.toml`` yet you can make one by executing the command:
 
 .. code-block:: console
 
-  $ conda install mamba -n base -c conda-forge
+    $ pixi init --format pyproject myproject
 
 
-Installation
-============
+A new folder with a ``pyproject.toml`` called ``myproject`` will be created for you. After this, you can
+navigate to this new directory and add ``hydromt_wflow`` as a dependency:
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+.. code-block:: console
 
-.. Note::
+    $ pixi add hydromt_wflow[full] --pypi
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+Pixi will then add it as a dependency to the project. The ``[full]`` is to make sure you include all
+of the optional dependencies.
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
-.. Tip::
+You can also add the optional dependencies to it like so:
 
-    This is our recommended way of installing HydroMT-Wflow!
+.. code-block:: console
+
+  $ pixi add gwwapi --pypi
+  $ pixi add hydroengine --pypi
+  $ pixi add pcraster --pypi
+
+the `--pypi` in this case is necessary because these dependencies are only available through pypi and not conda-forge
+adding this flag will tell pixi to install them from there.
+
+Once you have your new (or existing ``pyproject.toml``) file install the pixi
+environment and activate it with the following commands to be able to start using it:
+
+.. code-block:: console
+
+    $ pixi install
+    $ pixi shell activate
+
+
+If you did activate the shell like above you should now be able to run any python script like usual:
+
+.. code-block:: console
+
+  (hydromt-wflow) $ python path/to/script.py
+
+If you did not activate the shell you can still run the script in the environment by running it through pixi:
+
+.. code-block:: console
+
+  (hydromt-wflow) $ pixi run path/to/script.py
+
+If you intend to only use `hydromt_wflow` via the cli you can also install it globally using pixi like so:
+
+.. code-block:: console
+
+  $ pixi global install hydromt_wflow
+
+This will install hydromt_wflow in an isolated environment for you and make it available to run from basically
+anywhere on your system through the commandline
+
+
+.. _user_install_conda:
+
+Installation using Conda
+------------------------
+
+.. warning::
+
+  Due to the changes Anaconda made to their `lisencing agreements in 2024 <https://legal.anaconda.com/policies/en/?name=terms-of-service#anaconda-terms-of-service>`
+  using any packages from the anaconda channel (which is available by default in the main `conda` and `mamba` distributions) may require a paid license.
+  Therefore we highly recommend you only use the free and community maintained `conda-forge` channel. While you can configure existing `conda` / `mamba`
+  instaltions to do this correctly, we recommend that if you do not want to use pixi, that you use a `miniforge<https://github.com/conda-forge/miniforge>` distribution which has this correctly
+  configured by default
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: ```suggestion
  configured by default.
```
created_at: 2025-04-15T12:21:17Z
author_association: CONTRIBUTOR
diff_hunk: @@ -14,38 +14,41 @@ the code folder (where the envs folder and pyproject.toml are located):
     $ git clone https://github.com/Deltares/hydromt_wflow.git
     $ cd hydromt_wflow
 
-The next step is to create an environment yaml.
-This is done by calling the `make_env.py` script from commandline:
-(This requires the presence of the package `tomli` or Python 3.11)
+once you are in the directory you can install the environment using pixi with
 
 .. code-block:: console
 
-    $ python make_env.py full
+    $ pixi install
 
-The 'full' argument guarantees all the necessary tools!
-Now create the environment using conda and activate it:
+Afterwards you can run any of the tasks we defined for doing things such as running the test suite:
 
 .. code-block:: console
 
-    $ conda env create -f environment.yml
-    $ conda activate hydromt_wflow
+    $ pixi run test
 
-If you wish to make changes in HydroMT-Wflow, you should make an editable install of the plugin.
-This can be done with:
+generating the documentation:
 
 .. code-block:: console
 
-    $ pip install -e .
+    $ pixi run docs-html
 
-If you encounter issues with the installation of some packages, you might consider cleaning conda to remove unused packages and caches.
-This can be done through the following command from your base environment:
+We have several environments to make sure we can test ``hydromt_wflow`` under, for example,
+with all of the different python versions we support. The default environment should have
+everything you need, but if you want to run something (for example in CI) from a specific
+environment you can do so like this:
 
 .. code-block:: console
 
-    $ conda clean -a
+  $ pixi -e test-full-py311 run path/to/script.py
 
-It may also be advisable to clear pip's cache:
+
+Editors like vscode should be able to find pixi environments you make automatically,
+however if you use something else like `vim` or `helix` then you can make sure they run in
+the context of your environment:
path: docs/dev_guide/dev_install.rst
user: login: aslowwriter
body: vscode can detect pixi environments now a days without doing this, but it also wouldn't hurt to mention it. Want me to add it? 
created_at: 2025-04-15T12:27:54Z
author_association: CONTRIBUTOR
diff_hunk: @@ -4,58 +4,142 @@
 Installation Guide
 ==================
 
-Prerequisites
-=============
-For more information about the prerequisites for an installation of the HydroMT package
-and related dependencies, please visit the documentation of
-`HydroMT core <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
 
-Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
+.. _optional_dependencies:
 
-- `toml <https://github.com/uiri/toml>`_
-- `pcraster <https://pcraster.geo.uu.nl>`_ (optional)
-- `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
-- `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
+Optional Dependencies
+=====================
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+HydroMT-Wflow has several optional dependencies that need to be installed in your environment to enable specific
+functionalities, though they are not necessary for hydromt-wflow to function as a whole. Due to limitations in the conda-forge
+package specification you will have to install these yourself in addition to hydromt-wflow if you want to use them.
 
-.. code-block:: console
-
-  $ conda install mamba -n base -c conda-forge
+They are:
+- `pcraster <https://pcraster.geo.uu.nl>`_ This one is used for the reading and writing of pcr maps. Note that this one is only available on conda-forge so if you install hydromt-wflow through pypi you will not be able to access this functionality.
+- `gwwapi <https://github.com/global-water-watch/gww-api>`_ This one is used for providing more resources about reservoirs and how to set them up. This one is only available through pypi at the moment.
+- `hydroengine <https://github.com/openearth/hydro-engine>`_ Similar to ``gwwapi`` the ``hydroengine`` package gives access to more data sources, and is currently only available through pypi.
+- `wraplib <https://github.com/wradlib/wradlib>`_ This package provides downloading and processing functionalities of radar weather data.
+- `pyet <https://github.com/pyet-org/pyet>`_ Provides processing functionalities of evapotranspriation.
+- `gdal <https://gdal.org/en/stable/>`_ Provides many drivers and GIS transformations.  Only available through conda-forge.
 
+Since some dependencies are only availabe through conda-forge and some only through pypi, you will need a packange manager that can handle both.
 
 Installation
 ============
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
 
-.. Note::
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
 .. Tip::
 
     This is our recommended way of installing HydroMT-Wflow!
 
-You can install HydroMT-Wflow in a new environment called `hydromt-wflow`:
+
+If you do not have a ``pyproject.toml`` yet you can make one by executing the command:
+
+.. code-block:: console
+
+    $ pixi init --format pyproject myproject
+
+
+A new folder with a ``pyproject.toml`` called ``myproject`` will be created for you. After this, you can
+navigate to this new directory and add ``hydromt_wflow`` as a dependency:
+
+.. code-block:: console
+
+    $ pixi add hydromt_wflow[extra, examples] --pypi
+
+Pixi will then add it as a dependency to the project. The ``[full]`` is to make sure you include all
+of the optional dependencies.
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: `[full]` doesn't exist. Please remove this sentence.
created_at: 2025-04-16T10:19:22Z
author_association: CONTRIBUTOR
diff_hunk: @@ -4,58 +4,142 @@
 Installation Guide
 ==================
 
-Prerequisites
-=============
-For more information about the prerequisites for an installation of the HydroMT package
-and related dependencies, please visit the documentation of
-`HydroMT core <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
 
-Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
+.. _optional_dependencies:
 
-- `toml <https://github.com/uiri/toml>`_
-- `pcraster <https://pcraster.geo.uu.nl>`_ (optional)
-- `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
-- `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
+Optional Dependencies
+=====================
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+HydroMT-Wflow has several optional dependencies that need to be installed in your environment to enable specific
+functionalities, though they are not necessary for hydromt-wflow to function as a whole. Due to limitations in the conda-forge
+package specification you will have to install these yourself in addition to hydromt-wflow if you want to use them.
 
-.. code-block:: console
-
-  $ conda install mamba -n base -c conda-forge
+They are:
+- `pcraster <https://pcraster.geo.uu.nl>`_ This one is used for the reading and writing of pcr maps. Note that this one is only available on conda-forge so if you install hydromt-wflow through pypi you will not be able to access this functionality.
+- `gwwapi <https://github.com/global-water-watch/gww-api>`_ This one is used for providing more resources about reservoirs and how to set them up. This one is only available through pypi at the moment.
+- `hydroengine <https://github.com/openearth/hydro-engine>`_ Similar to ``gwwapi`` the ``hydroengine`` package gives access to more data sources, and is currently only available through pypi.
+- `wraplib <https://github.com/wradlib/wradlib>`_ This package provides downloading and processing functionalities of radar weather data.
+- `pyet <https://github.com/pyet-org/pyet>`_ Provides processing functionalities of evapotranspriation.
+- `gdal <https://gdal.org/en/stable/>`_ Provides many drivers and GIS transformations.  Only available through conda-forge.
 
+Since some dependencies are only availabe through conda-forge and some only through pypi, you will need a packange manager that can handle both.
 
 Installation
 ============
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
 
-.. Note::
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
 .. Tip::
 
     This is our recommended way of installing HydroMT-Wflow!
 
-You can install HydroMT-Wflow in a new environment called `hydromt-wflow`:
+
+If you do not have a ``pyproject.toml`` yet you can make one by executing the command:
+
+.. code-block:: console
+
+    $ pixi init --format pyproject myproject
+
+
+A new folder with a ``pyproject.toml`` called ``myproject`` will be created for you. After this, you can
+navigate to this new directory and add ``hydromt_wflow`` as a dependency:
+
+.. code-block:: console
+
+    $ pixi add hydromt_wflow[extra, examples] --pypi
+
+Pixi will then add it as a dependency to the project. The ``[full]`` is to make sure you include all
+of the optional dependencies.
+
+You can also add the optional dependencies to it like so:
+
+.. code-block:: console
+
+  $ pixi add gwwapi --pypi
+  $ pixi add hydroengine --pypi
+  $ pixi add pcraster
+  $ pixi add --pypi wradlib
+  $ pixi add --pypi pyet
+  $ pixi add gdal
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: I think this is now wrong with the lines above.

If you install over pypi, `[extra]` will already give you the optional dependencies. So you would not need to add gwwapi, hydroengine, wradlib, pyet.

If you install over `pixi add hydromt_wflow`, you will not get any of the optionals and would have to do this.

I would rather see, like `xarray`, that we add all optionals in the conda recipe. For pypi I'm okay with optionals. In that case wradlib, pyet, pcraster and gdal would already be installed via the recipe. Still, like in the conda instructions, one would still have to install gwwapi and hydroengine via pip.
created_at: 2025-04-16T10:22:07Z
author_association: CONTRIBUTOR
diff_hunk: @@ -4,58 +4,142 @@
 Installation Guide
 ==================
 
-Prerequisites
-=============
-For more information about the prerequisites for an installation of the HydroMT package
-and related dependencies, please visit the documentation of
-`HydroMT core <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
 
-Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
+.. _optional_dependencies:
 
-- `toml <https://github.com/uiri/toml>`_
-- `pcraster <https://pcraster.geo.uu.nl>`_ (optional)
-- `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
-- `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
+Optional Dependencies
+=====================
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+HydroMT-Wflow has several optional dependencies that need to be installed in your environment to enable specific
+functionalities, though they are not necessary for hydromt-wflow to function as a whole. Due to limitations in the conda-forge
+package specification you will have to install these yourself in addition to hydromt-wflow if you want to use them.
 
-.. code-block:: console
-
-  $ conda install mamba -n base -c conda-forge
+They are:
+- `pcraster <https://pcraster.geo.uu.nl>`_ This one is used for the reading and writing of pcr maps. Note that this one is only available on conda-forge so if you install hydromt-wflow through pypi you will not be able to access this functionality.
+- `gwwapi <https://github.com/global-water-watch/gww-api>`_ This one is used for providing more resources about reservoirs and how to set them up. This one is only available through pypi at the moment.
+- `hydroengine <https://github.com/openearth/hydro-engine>`_ Similar to ``gwwapi`` the ``hydroengine`` package gives access to more data sources, and is currently only available through pypi.
+- `wraplib <https://github.com/wradlib/wradlib>`_ This package provides downloading and processing functionalities of radar weather data.
+- `pyet <https://github.com/pyet-org/pyet>`_ Provides processing functionalities of evapotranspriation.
+- `gdal <https://gdal.org/en/stable/>`_ Provides many drivers and GIS transformations.  Only available through conda-forge.
 
+Since some dependencies are only availabe through conda-forge and some only through pypi, you will need a packange manager that can handle both.
 
 Installation
 ============
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
 
-.. Note::
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
 .. Tip::
 
     This is our recommended way of installing HydroMT-Wflow!
 
-You can install HydroMT-Wflow in a new environment called `hydromt-wflow`:
+
+If you do not have a ``pyproject.toml`` yet you can make one by executing the command:
+
+.. code-block:: console
+
+    $ pixi init --format pyproject myproject
+
+
+A new folder with a ``pyproject.toml`` called ``myproject`` will be created for you. After this, you can
+navigate to this new directory and add ``hydromt_wflow`` as a dependency:
+
+.. code-block:: console
+
+    $ pixi add hydromt_wflow[extra, examples] --pypi
+
+Pixi will then add it as a dependency to the project. The ``[full]`` is to make sure you include all
+of the optional dependencies.
+
+You can also add the optional dependencies to it like so:
+
+.. code-block:: console
+
+  $ pixi add gwwapi --pypi
+  $ pixi add hydroengine --pypi
+  $ pixi add pcraster
+  $ pixi add --pypi wradlib
+  $ pixi add --pypi pyet
+  $ pixi add gdal
path: docs/getting_started/installation.rst
user: login: aslowwriter
body: I think that is a good one, but we can't do this now as it can only be done during release time, so we'll have to make a note of that for the next release. 
created_at: 2025-04-16T11:40:08Z
author_association: CONTRIBUTOR
diff_hunk: @@ -4,58 +4,142 @@
 Installation Guide
 ==================
 
-Prerequisites
-=============
-For more information about the prerequisites for an installation of the HydroMT package
-and related dependencies, please visit the documentation of
-`HydroMT core <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
 
-Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
+.. _optional_dependencies:
 
-- `toml <https://github.com/uiri/toml>`_
-- `pcraster <https://pcraster.geo.uu.nl>`_ (optional)
-- `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
-- `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
+Optional Dependencies
+=====================
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+HydroMT-Wflow has several optional dependencies that need to be installed in your environment to enable specific
+functionalities, though they are not necessary for hydromt-wflow to function as a whole. Due to limitations in the conda-forge
+package specification you will have to install these yourself in addition to hydromt-wflow if you want to use them.
 
-.. code-block:: console
-
-  $ conda install mamba -n base -c conda-forge
+They are:
+- `pcraster <https://pcraster.geo.uu.nl>`_ This one is used for the reading and writing of pcr maps. Note that this one is only available on conda-forge so if you install hydromt-wflow through pypi you will not be able to access this functionality.
+- `gwwapi <https://github.com/global-water-watch/gww-api>`_ This one is used for providing more resources about reservoirs and how to set them up. This one is only available through pypi at the moment.
+- `hydroengine <https://github.com/openearth/hydro-engine>`_ Similar to ``gwwapi`` the ``hydroengine`` package gives access to more data sources, and is currently only available through pypi.
+- `wraplib <https://github.com/wradlib/wradlib>`_ This package provides downloading and processing functionalities of radar weather data.
+- `pyet <https://github.com/pyet-org/pyet>`_ Provides processing functionalities of evapotranspriation.
+- `gdal <https://gdal.org/en/stable/>`_ Provides many drivers and GIS transformations.  Only available through conda-forge.
 
+Since some dependencies are only availabe through conda-forge and some only through pypi, you will need a packange manager that can handle both.
 
 Installation
 ============
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
 
-.. Note::
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
 .. Tip::
 
     This is our recommended way of installing HydroMT-Wflow!
 
-You can install HydroMT-Wflow in a new environment called `hydromt-wflow`:
+
+If you do not have a ``pyproject.toml`` yet you can make one by executing the command:
+
+.. code-block:: console
+
+    $ pixi init --format pyproject myproject
+
+
+A new folder with a ``pyproject.toml`` called ``myproject`` will be created for you. After this, you can
+navigate to this new directory and add ``hydromt_wflow`` as a dependency:
+
+.. code-block:: console
+
+    $ pixi add hydromt_wflow[extra, examples] --pypi
+
+Pixi will then add it as a dependency to the project. The ``[full]`` is to make sure you include all
+of the optional dependencies.
+
+You can also add the optional dependencies to it like so:
+
+.. code-block:: console
+
+  $ pixi add gwwapi --pypi
+  $ pixi add hydroengine --pypi
+  $ pixi add pcraster
+  $ pixi add --pypi wradlib
+  $ pixi add --pypi pyet
+  $ pixi add gdal
path: docs/getting_started/installation.rst
user: login: aslowwriter
body: I will add some explanations about when you'd need to install the optional dependencies

created_at: 2025-04-16T11:40:28Z
author_association: CONTRIBUTOR
diff_hunk: @@ -4,58 +4,151 @@
 Installation Guide
 ==================
 
-Prerequisites
-=============
-For more information about the prerequisites for an installation of the HydroMT package
-and related dependencies, please visit the documentation of
-`HydroMT core <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
 
-Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
+.. _optional_dependencies:
 
-- `toml <https://github.com/uiri/toml>`_
-- `pcraster <https://pcraster.geo.uu.nl>`_ (optional)
-- `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
-- `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
+Optional Dependencies
+=====================
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+HydroMT-Wflow has several optional dependencies that need to be installed in your environment to enable specific
+functionalities, though they are not necessary for hydromt-wflow to function as a whole. Due to limitations in the conda-forge
+package specification you will have to install these yourself in addition to hydromt-wflow if you want to use them.
 
-.. code-block:: console
-
-  $ conda install mamba -n base -c conda-forge
+They are:
+- `pcraster <https://pcraster.geo.uu.nl>`_ This one is used for the reading and writing of pcr maps. Note that this one is only available on conda-forge so if you install hydromt-wflow through pypi you will not be able to access this functionality.
+- `gwwapi <https://github.com/global-water-watch/gww-api>`_ This one is used for providing more resources about reservoirs and how to set them up. This one is only available through pypi at the moment.
+- `hydroengine <https://github.com/openearth/hydro-engine>`_ Similar to ``gwwapi`` the ``hydroengine`` package gives access to more data sources, and is currently only available through pypi.
+- `wraplib <https://github.com/wradlib/wradlib>`_ This package provides downloading and processing functionalities of radar weather data.
+- `pyet <https://github.com/pyet-org/pyet>`_ Provides processing functionalities of evapotranspriation.
+- `gdal <https://gdal.org/en/stable/>`_ Provides many drivers and GIS transformations.  Only available through conda-forge.
 
+Since some dependencies are only availabe through conda-forge and some only through pypi, you will need a packange manager that can handle both.
 
 Installation
 ============
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
 
-.. Note::
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
 .. Tip::
 
     This is our recommended way of installing HydroMT-Wflow!
 
-You can install HydroMT-Wflow in a new environment called `hydromt-wflow`:
+
+If you do not have a ``pyproject.toml`` yet you can make one by executing the command:
+
+.. code-block:: console
+
+    $ pixi init --format pyproject myproject
+
+
+A new folder with a ``pyproject.toml`` called ``myproject`` will be created for you. After this, you can
+navigate to this new directory and add ``hydromt_wflow`` as a dependency:
+
+.. code-block:: console
+
+    $ pixi add hydromt_wflow[extra, examples] --pypi
+
+Pixi will then add it as a dependency to the project. The ``[extra, examples]`` instruct pixi to also
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: Since we were just looking at the source that is being built by flit, it seems that the `examples` optional package is not needed, only if you can get your hands on the examples. Should we just say `hydromt_wflow[extras]`?
created_at: 2025-04-16T11:48:54Z
author_association: CONTRIBUTOR
diff_hunk: @@ -4,58 +4,142 @@
 Installation Guide
 ==================
 
-Prerequisites
-=============
-For more information about the prerequisites for an installation of the HydroMT package
-and related dependencies, please visit the documentation of
-`HydroMT core <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
 
-Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
+.. _optional_dependencies:
 
-- `toml <https://github.com/uiri/toml>`_
-- `pcraster <https://pcraster.geo.uu.nl>`_ (optional)
-- `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
-- `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
+Optional Dependencies
+=====================
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+HydroMT-Wflow has several optional dependencies that need to be installed in your environment to enable specific
+functionalities, though they are not necessary for hydromt-wflow to function as a whole. Due to limitations in the conda-forge
+package specification you will have to install these yourself in addition to hydromt-wflow if you want to use them.
 
-.. code-block:: console
-
-  $ conda install mamba -n base -c conda-forge
+They are:
+- `pcraster <https://pcraster.geo.uu.nl>`_ This one is used for the reading and writing of pcr maps. Note that this one is only available on conda-forge so if you install hydromt-wflow through pypi you will not be able to access this functionality.
+- `gwwapi <https://github.com/global-water-watch/gww-api>`_ This one is used for providing more resources about reservoirs and how to set them up. This one is only available through pypi at the moment.
+- `hydroengine <https://github.com/openearth/hydro-engine>`_ Similar to ``gwwapi`` the ``hydroengine`` package gives access to more data sources, and is currently only available through pypi.
+- `wraplib <https://github.com/wradlib/wradlib>`_ This package provides downloading and processing functionalities of radar weather data.
+- `pyet <https://github.com/pyet-org/pyet>`_ Provides processing functionalities of evapotranspriation.
+- `gdal <https://gdal.org/en/stable/>`_ Provides many drivers and GIS transformations.  Only available through conda-forge.
 
+Since some dependencies are only availabe through conda-forge and some only through pypi, you will need a packange manager that can handle both.
 
 Installation
 ============
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
 
-.. Note::
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
 .. Tip::
 
     This is our recommended way of installing HydroMT-Wflow!
 
-You can install HydroMT-Wflow in a new environment called `hydromt-wflow`:
+
+If you do not have a ``pyproject.toml`` yet you can make one by executing the command:
+
+.. code-block:: console
+
+    $ pixi init --format pyproject myproject
+
+
+A new folder with a ``pyproject.toml`` called ``myproject`` will be created for you. After this, you can
+navigate to this new directory and add ``hydromt_wflow`` as a dependency:
+
+.. code-block:: console
+
+    $ pixi add hydromt_wflow[extra, examples] --pypi
+
+Pixi will then add it as a dependency to the project. The ``[full]`` is to make sure you include all
+of the optional dependencies.
+
+You can also add the optional dependencies to it like so:
+
+.. code-block:: console
+
+  $ pixi add gwwapi --pypi
+  $ pixi add hydroengine --pypi
+  $ pixi add pcraster
+  $ pixi add --pypi wradlib
+  $ pixi add --pypi pyet
+  $ pixi add gdal
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: pyet and wradlib are available through conda-forge. Please remove `--pypi`
created_at: 2025-04-16T11:49:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -66,22 +159,24 @@ HydroMT-Wflow will be installed together with all optional (see above) and a few
 
     Please take into account that gwwapi or hydroengine packages are not available from conda and therefore have to be installed from pypi separately (in the activated environment).
 
-.. code-block:: console
+    .. code-block:: console
 
-  $ pip install gwwapi
-  $ pip install hydroengine
+      (hydromt-wflow) $ pip install gwwapi
+      (hydromt-wflow) $ pip install hydroengine
path: docs/getting_started/installation.rst
user: login: deltamarnix
body: You will also need to tell the user to `conda install pyet` and the other optionals.
created_at: 2025-04-16T11:50:40Z
author_association: CONTRIBUTOR
diff_hunk: @@ -4,58 +4,151 @@
 Installation Guide
 ==================
 
-Prerequisites
-=============
-For more information about the prerequisites for an installation of the HydroMT package
-and related dependencies, please visit the documentation of
-`HydroMT core <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
 
-Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
+.. _optional_dependencies:
 
-- `toml <https://github.com/uiri/toml>`_
-- `pcraster <https://pcraster.geo.uu.nl>`_ (optional)
-- `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
-- `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
+Optional Dependencies
+=====================
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+HydroMT-Wflow has several optional dependencies that need to be installed in your environment to enable specific
+functionalities, though they are not necessary for hydromt-wflow to function as a whole. Due to limitations in the conda-forge
+package specification you will have to install these yourself in addition to hydromt-wflow if you want to use them.
 
-.. code-block:: console
-
-  $ conda install mamba -n base -c conda-forge
+They are:
+- `pcraster <https://pcraster.geo.uu.nl>`_ This one is used for the reading and writing of pcr maps. Note that this one is only available on conda-forge so if you install hydromt-wflow through pypi you will not be able to access this functionality.
+- `gwwapi <https://github.com/global-water-watch/gww-api>`_ This one is used for providing more resources about reservoirs and how to set them up. This one is only available through pypi at the moment.
+- `hydroengine <https://github.com/openearth/hydro-engine>`_ Similar to ``gwwapi`` the ``hydroengine`` package gives access to more data sources, and is currently only available through pypi.
+- `wraplib <https://github.com/wradlib/wradlib>`_ This package provides downloading and processing functionalities of radar weather data.
+- `pyet <https://github.com/pyet-org/pyet>`_ Provides processing functionalities of evapotranspriation.
+- `gdal <https://gdal.org/en/stable/>`_ Provides many drivers and GIS transformations.  Only available through conda-forge.
 
+Since some dependencies are only availabe through conda-forge and some only through pypi, you will need a packange manager that can handle both.
 
 Installation
 ============
 
-HydroMT-Wflow is available from pypi and conda-forge.
-We recommend installing using mamba from conda-forge in a new environment.
+There are various ways in which one can install hydrom_wflow in a python environment, the main being:
 
-.. Note::
+- :ref:`Pixi <user_install_pixi>`
+- :ref:`Miniforge/conda <user_install_conda>`
+
+All of these options will be discussed below but we recommend using pixi, as it is the fastest and most
+robust (and reproducible) option.
 
-    In the commands below you can exchange `mamba` for `conda`, see
-    `here <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
-    for the difference between both.
+.. _user_install_pixi:
+
+Installation using Pixi
+-----------------------
 
-Install HydroMT-Wflow in a new environment
-------------------------------------------
 .. Tip::
 
     This is our recommended way of installing HydroMT-Wflow!
 
-You can install HydroMT-Wflow in a new environment called `hydromt-wflow`:
+
+If you do not have a ``pyproject.toml`` yet you can make one by executing the command:
+
+.. code-block:: console
+
+    $ pixi init --format pyproject myproject
+
+
+A new folder with a ``pyproject.toml`` called ``myproject`` will be created for you. After this, you can
+navigate to this new directory and add ``hydromt_wflow`` as a dependency:
+
+.. code-block:: console
+
+    $ pixi add hydromt_wflow[extra, examples] --pypi
+
+Pixi will then add it as a dependency to the project. The ``[extra, examples]`` instruct pixi to also
path: docs/getting_started/installation.rst
user: login: aslowwriter
body: good point, I'm not sure anymore why I included the examples there
created_at: 2025-04-16T11:55:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -4,94 +4,201 @@
 Installation Guide
 ==================
 
-Prerequisites
-=============
-For more information about the prerequisites for an installation of the HydroMT package
-and related dependencies, please visit the documentation of
-`HydroMT core <https://deltares.github.io/hydromt/latest/getting_started/installation.html#installation-guide>`_
 
-Compared to HydroMT, HydroMT-Wflow has additional dependencies, namely:
+.. _optional_dependencies:
 
-- `toml <https://github.com/uiri/toml>`_
-- `pcraster <https://pcraster.geo.uu.nl>`_ (optional)
-- `gwwapi <https://github.com/global-water-watch/gww-api>`_ (optional)
-- `hydroengine <https://github.com/openearth/hydro-engine>`_ (optional)
+Optional Dependencies
+=====================
 
-If you already have a python & conda installation but do not yet have mamba installed,
-we recommend installing it into your *base* environment using:
+HydroMT-Wflow has several optional dependencies that need to be installed in your environment to enable specific
+functionalities, though they are not necessary for hydromt-wflow to function as a whole. Due to limitations in the conda-forge
+package specification you will have to install these yourself in addition to hydromt-wflow if you want to use them.
 
-.. code-block:: console
-
-  $ conda install mamba -n base -c conda-forge
+They are:
+- `pcraster <https://pcraster.geo.uu.nl>`_ This one is used for the reading and writing of pcr maps. Note that this one is only available on conda-forge so if you install hydromt-wflow through pypi you will not be able to access this functionality.
+- `gwwapi <https://github.com/global-water-watch/gww-api>`_ This one is used for providing more resources about reservoirs and how to set them up. This one is only available through pypi at the moment.
+- `hydroengine <https://github.com/openearth/hydro-engine>`_ Similar to ``gwwapi`` the ``hydroengine`` package gives access to more data sources, and is currently only available through pypi.
+- `wraplib <https://github.com/wradlib/wradlib>`_ This package provides downloading and processing functionalities of radar weather data.
path: docs/getting_started/installation.rst
user: login: LuukBlom
body: typo wraplib -> wradlib
created_at: 2025-04-17T08:09:32Z
author_association: COLLABORATOR
diff_hunk: @@ -164,6 +164,8 @@ docs-html = { cmd = [
   "docs/_build",
   "-W",
 ] }
+doc = { depends-on = ["docs-html"]}
+docs = { depends-on = ["docs-html"]}
path: pyproject.toml
user: login: LuukBlom
body: Should this be here? Seems redundant to me
created_at: 2025-04-17T08:14:18Z
author_association: COLLABORATOR
diff_hunk: @@ -164,6 +164,8 @@ docs-html = { cmd = [
   "docs/_build",
   "-W",
 ] }
+doc = { depends-on = ["docs-html"]}
+docs = { depends-on = ["docs-html"]}
path: pyproject.toml
user: login: aslowwriter
body: it is redundant, but sometimes I forget which we used, so having some aliases is nice, I can remove them if you want. 
created_at: 2025-04-17T09:02:46Z
author_association: CONTRIBUTOR
diff_hunk: @@ -164,6 +164,8 @@ docs-html = { cmd = [
   "docs/_build",
   "-W",
 ] }
+doc = { depends-on = ["docs-html"]}
+docs = { depends-on = ["docs-html"]}
path: pyproject.toml
user: login: LuukBlom
body: Ah okay thas fine, I dont mind it being there, just checking it wasnt an accidental commit/typo.
created_at: 2025-04-17T09:57:49Z
author_association: COLLABORATOR

PR comments:
user: login: aslowwriter
created_at: 2025-04-15T12:40:15Z
body: > Can we make that simpler for users?

The only way I can see of making it simpler is to just do away with them being optional but I don't know how important it is that they remain optional. Aside from that, we could either ask those dependencies to start publishing to conda, or create feedstocks for them ourselves (which you don't have to be the original author for to do). The first doesn't sound very likely to succeed in the short term and the last one doesn't sound appealing for hopefully obvious reasons. 
author_association: CONTRIBUTOR
user: login: aslowwriter
created_at: 2025-04-17T09:12:38Z
body: > Why do we tell users to manually install specific optional packages? Should this not be taken care of by the extra / optional dependencies defined in the pyproject.toml file?

Because conda-forge doesn't handle optional dependencies. if you install hydromt through pypi then yes `hydromt_wflow[extra]` should work, but if you do it through conda forge, this either doesn't do anything or fails (can't remember which one) So for the `conda` version this is actually strictly necessary. For pixi we could omit it, but it's good to be complete I think 
author_association: CONTRIBUTOR
user: login: sonarqubecloud[bot]
created_at: 2025-04-17T09:16:16Z
body: ## [![Quality Gate Passed](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/checks/QualityGateBadge/qg-passed-20px.png 'Quality Gate Passed')](https://sonarcloud.io/dashboard?id=Deltares_hydromt_wflow&pullRequest=376) **Quality Gate passed**  
Issues  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0 New issues](https://sonarcloud.io/project/issues?id=Deltares_hydromt_wflow&pullRequest=376&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/accepted-16px.png '') [0 Accepted issues](https://sonarcloud.io/project/issues?id=Deltares_hydromt_wflow&pullRequest=376&issueStatuses=ACCEPTED)

Measures  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0 Security Hotspots](https://sonarcloud.io/project/security_hotspots?id=Deltares_hydromt_wflow&pullRequest=376&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0.0% Coverage on New Code](https://sonarcloud.io/component_measures?id=Deltares_hydromt_wflow&pullRequest=376&metric=new_coverage&view=list)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0.0% Duplication on New Code](https://sonarcloud.io/component_measures?id=Deltares_hydromt_wflow&pullRequest=376&metric=new_duplicated_lines_density&view=list)  
  
[See analysis details on SonarQube Cloud](https://sonarcloud.io/dashboard?id=Deltares_hydromt_wflow&pullRequest=376)


author_association: NONE
user: login: aslowwriter
created_at: 2025-04-17T10:46:24Z
body: Given that Marnix is on leave for the next week, I'd like to move on. If he comes back and would still like to see changes, I'll be happy to open an new PR 
author_association: CONTRIBUTOR