From 8d1accf9aedb28cbff6bbf2a5578804e8902a1f1 Mon Sep 17 00:00:00 2001 From: Trevor James Smith <10819524+Zeitsperre@users.noreply.github.com> Date: Wed, 1 Feb 2023 13:45:40 -0500 Subject: [PATCH] update install and configuration instructions, clearly indicate lack of Windows support --- docs/installation.rst | 68 +++++++++++++++++++++++++------------------ environment.yml | 8 ++--- 2 files changed, 43 insertions(+), 33 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 3b85a8fb..95334dc0 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -5,35 +5,48 @@ Installation Full Installation (Anaconda) ---------------------------- -For many reasons, we recommend using a `Conda environment -`_ -to work with the full RavenPy installation. This implementation is able to manage -the harder to install GIS dependencies, like `GDAL`. Begin by creating an environment: +For many reasons, we recommend using a `Conda environment `_ +to work with the full RavenPy installation. This implementation is able to manage the harder-to-install GIS dependencies,like `GDAL`. +Begin by creating an environment: .. code-block:: console - $ conda create -c conda-forge --name ravenpy-env + $ conda create -c conda-forge --name ravenpy The newly created environment must then be activated: .. code-block:: console - $ conda activate ravenpy-env + $ conda activate ravenpy RavenPy can then be installed directly via its `conda-forge` package by running: .. code-block:: console - (ravenpy-env) $ conda install -c conda-forge ravenpy + (ravenpy) $ conda install -c conda-forge ravenpy + +This approach installs both the `Raven `_ binary directly to your environment `PATH`, +as well as installs all the necessary Python and C libraries supporting GIS functionalities. + +.. warning:: + + `OSTRICH `_ is another dependency needed for some key functions + in RavenPy but is not currently available for Windows conda users. We suggest performing either a manual installation of OSTRICH + or compiling it from source code: https://github.com/usbr/ostrich + +For Unix/Linux users, OSTRICH can be installed from conda by running: -This approach also installs both the `Raven `_ and `OSTRICH -`_ binaries directly to your environment `PATH`, -as well as installs all the necessary libraries supporting GIS functionalities. +.. code-block:: console + + (ravenpy) $ conda install -c conda-forge ostrich Custom Installation (Python/Pip) -------------------------------- -If you wish to install RavenPy and its C-libraries manually, compiling the `Raven` and `Ostrich binarioes for your system, +.. warning:: + The following instructions will only work on POSIX-like systems (Unix/Linux; not supported on Windows). + +If you wish to install RavenPy and its C-libraries manually, compiling the `Raven` and `Ostrich binaries for your system, you can install the entire system directly, placing them in the `bin` folder of your environment. In order to perform this from Ubuntu/Debian: @@ -48,6 +61,11 @@ Then, from your python environment, run: $ pip install ravenpy[gis] $ pip install ravenpy[gis] --verbose --install-option="--with-binaries" +.. warning:: + + It is imperative that the Python dependencies are pre-installed before running the `--with-binaries` + option; This install step will fail otherwise. + If desired, the core functions of `RavenPy` can be installed without its GIS functionalities as well. This implementation of RavenPy is much lighter on dependencies and can be installed easily with `pip`, without the need for `conda` or `virtualenv`. @@ -74,9 +92,9 @@ If for any reason you prefer to install without the binaries, from a fresh pytho (ravenpy-env) $ pip install ravenpy[gis] -But then you will be in charge of providing either ``raven`` and ``ostrich`` binaries on your PATH, -or values for ``RAVENPY_RAVEN_BINARY_PATH`` and ``RAVENPY_OSTRICH_BINARY_PATH`` environment -variables (both as absolute paths) at runtime. +But then you will be in charge of providing either ``raven`` and ``ostrich`` binaries on your PATH, or setting values for +``RAVENPY_RAVEN_BINARY_PATH`` and ``RAVENPY_OSTRICH_BINARY_PATH`` environment variables (both as absolute paths) in the +terminal/command prompt/shell used at runtime. .. note:: @@ -100,22 +118,23 @@ by doing: $ cd /path/to/ravenpy $ conda env create -f environment.yml - $ conda activate ravenpy-env + $ conda activate ravenpy You can then install RavenPy with: .. code-block:: console # for the python dependencies - (ravenpy-env) $ pip install --editable ".[dev]" - # for the Raven and OSTRICH binaries - (ravenpy-env) $ pip install --editable "." --install-option="--with-binaries" + (ravenpy) $ pip install --editable ".[dev]" + +.. warning:: -Then clone the Raven Test Data repo somewhere on your disk: + The following command will only work on POSIX-like systems (Unix/Linux; not supported on Windows). .. code-block:: console - (ravenpy-env) $ git clone git@github.com:Ouranosinc/raven-testdata.git + # for the Raven and OSTRICH binaries + (ravenpy) $ pip install --editable "." --install-option="--with-binaries" Install the pre-commit hook (to make sure that any code you contribute is properly formatted): @@ -127,13 +146,4 @@ If everything was properly installed the test suite should run successfully: .. code-block:: console - (ravenpy-env) $ export RAVENPY_TESTDATA_PATH=/path/to/raven-testdata (ravenpy-env) $ pytest tests - -Or set the conda environment variable permanently: - -.. code-block:: console - - (ravenpy-env) $ conda env config vars set RAVENPY_TESTDATA_PATH=/path/to/raven-testdata - -then deactivate and reactivate the environment. diff --git a/environment.yml b/environment.yml index 67ea9799..a1ee4e89 100644 --- a/environment.yml +++ b/environment.yml @@ -1,10 +1,10 @@ -name: ravenpy-env +name: ravenpy channels: -- conda-forge -- defaults + - conda-forge + - defaults dependencies: - raven-hydro ==3.5 - - ostrich ==21.03.16 + - ostrich ==21.03.16 # Not available on Windows - python >=3.8 - affine - cf_xarray