From 81ccc926ea7905abc7cc063d17a92e6c5e22ebe8 Mon Sep 17 00:00:00 2001
From: Kor de Jong <k.dejong@geoneric.eu>
Date: Fri, 5 Apr 2024 16:51:44 +0200
Subject: [PATCH] Update documentation

---
 documentation/test/index.rst | 77 ++++++++++++++++++++++++++++++++++--
 1 file changed, 73 insertions(+), 4 deletions(-)

diff --git a/documentation/test/index.rst b/documentation/test/index.rst
index aaacb02..f09c8cc 100644
--- a/documentation/test/index.rst
+++ b/documentation/test/index.rst
@@ -3,7 +3,15 @@ Test
 
 The software can be tested by performing these steps in turn:
 
-#. Create and activate a new virtual environment
+#. Create and activate a new virtual environment. There are multiple options for this. Below
+   we show how to setup a virtual environment using Python's built-in venv module and using Conda.
+
+   .. note::
+
+    Python's built-in venv module and Conda (and others) are alternatives with which you can
+    achieve the same thing: create one or more virtual environments to install Python packages in.
+    You don't need to use Python's venv module if you work with Conda, and vice versa.
+
 #. Install all required Python packages
 #. Test the software
 #. Remove the virtual environment
@@ -11,27 +19,88 @@ The software can be tested by performing these steps in turn:
 This procedure will leave no traces on your computer. If you intent to test the software regularly,
 you can keep the virtual environment as is, and install the updated version of the software later.
 
+
+Create a virtual environment
+----------------------------
+
+Using venv
+~~~~~~~~~~
+
+* `Tutorial <https://docs.python.org/3/tutorial/venv.html>`_
+* `Documentation <https://docs.python.org/3/library/venv.html>`_
+
 .. code-block:: bash
 
    cd ... # prefix of some directory for storing virtual environment
    python3 -m venv ap_test
+   # Use Scripts instead of bin if you use Windows
    source ap_test/bin/activate
    pip3 install --upgrade pip
 
+
+Using Conda
+~~~~~~~~~~~
+
+* `Using pip in a Conda environment <https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#pip-in-env>`_
+
+.. code-block:: bash
+
+   # Python version must be >= 3.9
+   conda create --name ap_test python=3.12
+   conda activate ap_test
+
+
+Install packages
+----------------
+
+The software is packaged as a Python wheel file. The pip command can be used to install it.
+
+.. code-block:: bash
+
    cd ... # prefix of dist directory containing package(s)
    pip3 install -f dist adaptation_pathways
 
+
+Test software
+-------------
+
+Once the software is installed correctly, the following should work:
+
+.. code-block:: bash
+
    # Use an installed script
-   pathways_generator --help
+   ap_plot_pathway_map --help
+   ap_pathway_generator --help
 
    # Use the package
    python3 -c "import adaptation_pathways as ap; print(ap.__version__)"
 
-   # To clean-up afterwards, just remove the ap_test directory containing the virtual environment
-   # ...
+
+Upgrade software
+----------------
 
 Installing an updated version of the software can be done using this command:
 
 .. code-block:: bash
 
    pip3 install upgrade -f dist adaptation_pathways
+
+
+Remove virtual environment
+--------------------------
+
+Using venv
+~~~~~~~~~~
+
+Just remove the ap_test directory containing the virtual environment.
+
+
+Using Conda
+~~~~~~~~~~~
+
+Use the Conda command to remove the virtual environment and all packages installed in it.
+
+.. code-block:: bash
+
+   conda deactivate
+   conda env remote --name ap_test