Merge branch 'main' into altitude-slope-gis

.cruft.json

@@ -11,7 +11,7 @@
       "project_slug": "xhydro",
       "project_short_description": "Hydrological analysis library built with xarray.",
       "pypi_username": "TC-FF",
-      "version": "0.3.6-dev.6",
+      "version": "0.3.6-dev.7",
       "use_pytest": "y",
       "use_black": "y",
       "use_conda": "y",

CONTRIBUTING.rst

@@ -69,12 +69,19 @@ Get Started!
 
 Ready to contribute? Here's how to set up ``xhydro`` for local development.
 
-#. If you are not already an `xhydro` collaborator, fork the ``xhydro`` repo on GitHub.
-#. Clone your fork locally:
+#. First, clone the ``xhydro`` repo locally.
 
-   .. code-block:: console
+    * If you are not an `xhydro` collaborator, fork the ``xhydro`` repo on GitHub:
+
+       .. code-block:: console
+
+            git clone git@github.com:your_name_here/xhydro.git
+
+    * Otherwise, if you are a collaborator, clone the ``xhydro`` repo locally:
+
+       .. code-block:: console
 
-        git clone git@github.com:your_name_here/xhydro.git
+            git clone git@github.com:hydrologie/xhydro.git
 
 #. Install your local copy into a development environment. You can create a new Anaconda development environment with:
 
@@ -94,7 +101,7 @@ Ready to contribute? Here's how to set up ``xhydro`` for local development.
 
             pre-commit run -a
 
-  If you want to skip the ``pre-commit`` hooks temporarily, you can pass the `--no-verify` flag to `git commit`.
+   If you want to skip the ``pre-commit`` hooks temporarily, you can pass the `--no-verify` flag to `git commit`.
 
 #. Create a branch for local development:
 
@@ -129,7 +136,7 @@ Ready to contribute? Here's how to set up ``xhydro`` for local development.
         git commit -m "Your detailed description of your changes."
         git push origin name-of-your-bugfix-or-feature
 
-    If ``pre-commit`` hooks fail, try re-committing your changes (or, if need be, you can skip them with `git commit --no-verify`).
+    If ``pre-commit`` hooks fail, try fixing the issues, re-staging the files to be committed, and re-committing your changes (or, if need be, you can skip them with `git commit --no-verify`).
 
 #. Submit a `Pull Request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`_ through the GitHub website.
 
@@ -145,13 +152,36 @@ Ready to contribute? Here's how to set up ``xhydro`` for local development.
         # To simply test that the docs pass build checks
         python -m tox -e docs
 
+#. If changes to your branch are made on GitHub, you can update your local branch with:
+
+    .. code-block:: console
+
+        git checkout name-of-your-bugfix-or-feature
+        git fetch
+        git pull origin name-of-your-bugfix-or-feature
+
+    If you have merge conflicts, you might need to replace `git pull` with `git merge` and resolve the conflicts manually.
+    Resolving conflicts from the command line can be tricky. If you are not comfortable with this, you can ignore the last command and instead use a GUI like PyCharm or Visual Studio Code to merge the remote changes and resolve the conflicts.
+
+#. Before merging, your Pull Request will need to be based on the `main` branch of the `xhydro` repository. If your branch is not up-to-date with the `main` branch, you can perform similar steps as above to update your branch:
+
+    .. code-block:: console
+
+        git checkout name-of-your-bugfix-or-feature
+        git fetch
+        git pull origin main
+
+    See the previous step for more information on resolving conflicts.
+
+#. To prevent unnecessary testing of branches that are not ready for review, the `xhydro` repository is set up to run tests only when a Pull Request has been "approved" by a maintainer. Similarly, the notebooks within documentation will only be rebuilt when the Pull Request is "approved", or if the Pull Request makes explicit changes to them. As such, additional changes to the Pull Request might be required after the Pull Request is approved to ensure that the tests pass and the documentation can be built.
+
 #. Once your Pull Request has been accepted and merged to the `main` branch, several automated workflows will be triggered:
 
     - The ``bump-version.yml`` workflow will automatically bump the patch version when pull requests are pushed to the `main` branch on GitHub. **It is not recommended to manually bump the version in your branch when merging (non-release) pull requests (this will cause the version to be bumped twice).**
     - `ReadTheDocs` will automatically build the documentation and publish it to the `latest` branch of `xhydro` documentation website.
     - If your branch is not a fork (ie: you are a maintainer), your branch will be automatically deleted.
 
-    You will have contributed your first changes to ``xhydro``!
+    You will have contributed to ``xhydro``!
 
 .. warning::
 
@@ -166,9 +196,13 @@ Before you submit a pull request, check that it meets these guidelines:
 
 #. The pull request should include tests and should aim to provide `code coverage <https://en.wikipedia.org/wiki/Code_coverage>`_ for all new lines of code. You can use the `--cov-report html --cov xhydro` flags during the call to ``pytest`` to generate an HTML report and analyse the current test coverage.
 
-#. If the pull request adds functionality, the docs should also be updated. Put your new functionality into a function with a docstring, and add the feature to the list in ``README.rst``.
+#. All functions should be documented with `docstrings` following the `numpydoc <https://numpydoc.readthedocs.io/en/latest/format.html>`_ format.
+
+#. If the pull request adds functionality, either update the documentation or create a new notebook in the `docs/notebooks` directory that demonstrates the feature. Library-defining features should also be listed in ``README.rst``.
+
+#. The ChangeLog should be updated with a brief description of the changes made in the Pull Request. If this is your first contribution to the project, please add your name and information to the `AUTHORS.rst` and `.zenodo.json` files.
 
-#. The pull request should work for Python 3.9, 3.10, 3.11, and 3.12. Check that the tests pass for all supported Python versions.
+#. The pull request should work for all currently supported Python versions. Check the `pyproject.toml` or `tox.ini` files for the supported versions.
 
 Tips
 ----

README.rst

@@ -22,7 +22,12 @@ Hydrological analysis library built with xarray
 Features
 --------
 
-* TODO
+* Easily find and extract geospacial data from the Planetary Computer API and watershed boundaries from the HydroSHEDS API over any area of interest.
+* Calibrate and execute Hydrotel and Raven-emulated hydrological models.
+* Perform optimal interpolation on hydrological data (daily streamflow and indices).
+* Compute hydrological indicators (e.g. n-day peak flow, annual maximum series, low flow, average flow, etc.) over custom date ranges.
+* Perform frequency analysis on hydrological indicators using a variety of methods (e.g. Gumbel, GEV, etc.).
+* Perform climate change impact analysis of hydrological data.
 
 Credits
 -------

docs/installation.rst

@@ -2,9 +2,26 @@
 Installation
 ============
 
+We strongly recommend installing `xhydro` in an Anaconda Python environment. Futhermore, due to the complexity of some packages, the default dependency solver can take a long time to resolve the environment. If `mamba` is not already your default solver, consider running the following commands in order to speed up the process:
+
+    .. code-block:: console
+
+        conda install -n base conda-libmamba-solver
+        conda config --set solver libmamba
+
+If you don't have `pip`_ installed, this `Python installation guide`_ can guide you through the process.
+
+.. _pip: https://pip.pypa.io
+.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
+
 Stable release
 --------------
-Due to the complexity of the install process of some dependencies, we strongly recommend installing `xhydro` in an Anaconda Python environment.
+Due to the complexity of the install process of some dependencies, `xhydro` should not be installed directly from `PyPI` unless you are sure that all requirements are met.
+
+Until the library is available on `Conda-Forge` for a more streamlined installation, we recommend following the instructions below, but replacing the first step with files from the latest release on `PyPI`_.
+
+.. _PyPI: https://pypi.org/project/xhydro/
+
 To create a working environment and install xHydro, copy the `environment-dev.yml` file from the root of the repository and run the following commands:
 
     .. code-block:: console
@@ -17,44 +34,50 @@ This is the preferred method to install `xHydro`, as it will always install the
 
 If for some reason you wish to install the `PyPI` version of `xhydro` into an existing Anaconda environment (*not recommended if requirements are not met*), only run the last command above.
 
-If you don't have `pip`_ installed, this `Python installation guide`_ can guide you through the process.
 
-.. _pip: https://pip.pypa.io
-.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
 
 From sources
 ------------
 `xHydro` is still under active development and the latest features might not yet be available on `PyPI`.
 To install the latest development version, you can install `xHydro` directly from the `Github repo`_.
 
-You can either clone the public repository:
+#. Download the source code from the `Github repo`_.
 
-    .. code-block:: console
+    * Clone the public repository:
 
-     git clone git@github.com:hydrologie/xhydro
+        .. code-block:: console
 
-Or download the `tarball`_:
+         git clone git@github.com:hydrologie/xhydro
 
-    .. code-block:: console
+    * Download the `tarball`_:
+
+        .. code-block:: console
 
-     curl -OJL https://github.com/hydrologie/xhydro/tarball/main
+         curl -OJL https://github.com/hydrologie/xhydro/tarball/main
 
-Once you have a copy of the source, you can create a working environment and install `xHydro` in it:
+#. Once you have a copy of the source, you can create a working environment and install `xHydro` in it:
 
     .. code-block:: console
 
-     conda env create -f environment.yml
-     conda activate xhydro
-     python -m pip install . --no-deps
+     conda env create -f environment-dev.yml
+     conda activate xhydro-dev
+     make dev
+
+    Even if you do not intend to contribute to `xhydro`, we favor using `environment-dev.yml` over `environment.yml` because it includes additional packages that are used to run all the examples provided in the documentation.
+    If for some reason you wish to install the `PyPI` version of `xhydro` into an existing Anaconda environment (*not recommended if requirements are not met*), only run the last command above.
 
-When new changes are made to the `Github repo`_, you can update your local copy using:
+#. When new changes are made to the `Github repo`_, you can update your local copy using the following commands from the root of the repository:
 
     .. code-block:: console
 
+     git fetch
+     git checkout main
      git pull origin main
-     conda env update -n xhydro -f environment.yml
-     conda activate xhydro
-     python -m pip install . --no-deps
+     conda env update -n xhydro-dev -f environment-dev.yml
+     conda activate xhydro-dev
+     make dev
+
+    These commands should work most of the time, but if big changes are made to the repository, you might need to remove the environment and create it again.
 
 .. _Github repo: https://github.com/hydrologie/xhydro
 .. _tarball: https://github.com/hydrologie/xhydro/tarball/main

docs/planification.rst

@@ -2,9 +2,11 @@
 Package Structure
 =================
 
-Here is `xhydro`'s structure as of v0.3.3 (2024-02-22), with the planned or discussed additions for the future.
+Here is `xhydro`'s structure as of v0.3.6 (2024-06-10), with the planned or discussed additions for the future.
 
 Testing data can be found here: https://github.com/hydrologie/xhydro-testdata
 
+The LSTM module can be found here: https://github.com/hydrologie/xhydro-lstm. It is not included in this package to avoid dependencies on `tensorflow`.
+
 .. image:: _static/_images/xhydro_structure.png
   :width: 800

pyproject.toml

@@ -124,7 +124,7 @@ target-version = [
 ]
 
 [tool.bumpversion]
-current_version = "0.3.6-dev.6"
+current_version = "0.3.6-dev.7"
 commit = true
 commit_args = "--no-verify"
 tag = false

src/xhydro/__init__.py

@@ -7,4 +7,4 @@
 
 __author__ = """Thomas-Charles Fortier Filion"""
 __email__ = "tcff_hydro@outlook.com"
-__version__ = "0.3.6-dev.6"
+__version__ = "0.3.6-dev.7"

tests/test_xhydro.py

@@ -36,4 +36,4 @@ def test_package_metadata():
         contents = f.read()
         assert """Thomas-Charles Fortier Filion""" in contents
         assert '__email__ = "tcff_hydro@outlook.com"' in contents
-        assert '__version__ = "0.3.6-dev.6"' in contents
+        assert '__version__ = "0.3.6-dev.7"' in contents