Merge remote-tracking branch 'origin/main' into perturbinds

.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.0",
+      "version": "0.3.3",
       "use_pytest": "y",
       "use_black": "y",
       "use_conda": "y",

.github/workflows/actions-versions-updater.yml

@@ -6,19 +6,27 @@ on:
     - cron:  '0 0 1 * *'
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: write
     steps:
       - uses: actions/checkout@v4.1.1
         with:
           # This requires a personal access token with the privileges to push directly to `main`
-          token: ${{ secrets.WORKFLOW_TOKEN }}
+          token: ${{ secrets.ACTIONS_VERSION_UPDATER_TOKEN }}
           persist-credentials: true
+
       - name: Run GitHub Actions Version Updater
         uses: saadmk11/github-actions-version-updater@v0.8.1
         with:
-          token: ${{ secrets.WORKFLOW_TOKEN }}
+          token: ${{ secrets.ACTIONS_VERSION_UPDATER_TOKEN }}
           committer_email: 'bumpversion[bot]@ouranos.ca'
           committer_username: 'update-github-actions[bot]'
           pull_request_title: '[bot] Update GitHub Action Versions'

.github/workflows/bump-version.yml

@@ -28,9 +28,15 @@ on:
       - xhydro/__init__.py
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   bump_patch_version:
     runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: write
     steps:
       - uses: actions/checkout@v4
         with:
@@ -54,5 +60,5 @@ jobs:
         uses: ad-m/github-push-action@master
         with:
           force: false
-          github_token: ${{ secrets.BUMPVERSION_TOKEN }}
+          github_token: ${{ secrets.BUMP_VERSION_TOKEN }}
           branch: ${{ github.ref }}

.github/workflows/first_pull_request.yml

@@ -5,10 +5,16 @@ on:
     types:
       - opened
 
+permissions:
+  contents: read
+
 jobs:
   welcome:
     name: Welcome
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
     steps:
       - uses: actions/github-script@v6
         with:

.github/workflows/main.yml

@@ -12,6 +12,10 @@ on:
       - xhydro/__init__.py
   pull_request:
 
+permissions:
+  contents: read
+  pull-requests: read
+
 jobs:
   lint:
     name: Lint (Python${{ matrix.python-version }})

.github/workflows/publish-pypi.yml

@@ -5,6 +5,9 @@ on:
     types:
       - published
 
+permissions:
+  contents: read
+
 jobs:
   build-n-publish-pypi:
     name: Build and publish Python 🐍 distributions 📦 to PyPI

.github/workflows/tag-testpypi.yml

@@ -5,11 +5,16 @@ on:
     tags:
       - 'v*.*' # Push events to matching v*, i.e. v1.0, v20.15.10
 
+permissions:
+  contents: read
+
 jobs:
   release:
     name: Create Release from tag
     runs-on: ubuntu-latest
     if: startsWith(github.ref, 'refs/tags/v') && endsWith(github.ref, '.0')
+    permissions:
+      contents: write
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

.gitignore

@@ -66,6 +66,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/apidoc/modules.rst
+docs/apidoc/xhydro*.rst
 
 # PyBuilder
 target/

.pre-commit-config.yaml

@@ -29,36 +29,41 @@ repos:
     hooks:
       - id: rst-inline-touching-normal
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 23.11.0
+    rev: 23.12.1
     hooks:
       - id: black
   - repo: https://github.com/PyCQA/isort
-    rev: 5.12.0
+    rev: 5.13.2
     hooks:
       - id: isort
         exclude: ^docs/
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.4
+    rev: v0.1.9
     hooks:
       - id: ruff
   - repo: https://github.com/pycqa/flake8
-    rev: 6.0.0
+    rev: 6.1.0
     hooks:
       - id: flake8
         additional_dependencies: [ 'flake8-alphabetize', 'flake8-rst-docstrings' ]
         args: [ '--config=.flake8' ]
+  - repo: https://github.com/numpy/numpydoc
+    rev: v1.6.0
+    hooks:
+      - id: numpydoc-validation
+        exclude: 'tests|docs/conf.py'
   - repo: https://github.com/keewis/blackdoc
     rev: v0.3.9
     hooks:
       - id: blackdoc
-        additional_dependencies: [ 'black==23.11.0' ]
+        additional_dependencies: [ 'black==23.12.1' ]
   - repo: https://github.com/adrienverge/yamllint.git
     rev: v1.33.0
     hooks:
       - id: yamllint
         args: ['--config-file', '.yamllint.yaml']
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.27.1
+    rev: 0.27.3
     hooks:
       - id: check-github-workflows
       - id: check-readthedocs

.readthedocs.yml

@@ -17,6 +17,7 @@ build:
   jobs:
     pre_build:
       - sphinx-apidoc -o docs/apidoc --private --module-first xhydro
+      - sphinx-build -M gettext docs docs/_build
 
 conda:
   environment: environment-dev.yml

CHANGES.rst

@@ -2,26 +2,29 @@
 Changelog
 =========
 
+
 v0.4.0 (unreleased)
 -------------------
+Contributors to this version: Trevor James Smith (:user:`Zeitsperre`), Thomas-Charles Fortier Filion (:user:`TC-FF`), Gabriel Rondeau-Genesse (:user:`RondeauG`).
 
 New features and enhancements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-* Added `xh.cc.perturbed_indicators` to compute future indicators using a perturbation approach and random sampling. (:pull:`54`).
+* Added French language support to the documentation. (:issue:`53`, :pull:`55`).
+* Added a new set of functions to support creating and updating `pooch` registries, caching testing datasets from `hydrologie/xhydro-testdata`, and ensuring that testing datasets can be loaded into temporary directories.
+* `xhydro` is now configured to use `pooch` to download and cache testing datasets from `hydrologie/xhydro-testdata`. (:pull:`62`).
+* Added `xh.cc.sampled_indicators` to compute future indicators using a perturbation approach and random sampling. (:pull:`54`).
 
 Breaking changes
 ^^^^^^^^^^^^^^^^
-* N/A
-
-Bug fixes
-^^^^^^^^^
-* N/A
+* Added `pooch` as an installation dependency. (:pull:`62`).
 
 Internal changes
 ^^^^^^^^^^^^^^^^
-
-* N/A
-
+* Added a new module for testing purposes: `xhydro.testing.helpers` with some new functions. (:pull:`62`):
+    * `generate_registry`: Parses data found in package (`xhydro.testing.data`), and adds it to the `registry.txt`
+    * `load_registry`: Loads installed (or custom) registry and returns dictionary
+    * `populate_testing_data`: Fetches the registry and optionally caches files at a different location (helpful for `pytest-xdist`).
+* Added a `pre-commit` hook (`numpydoc`) to ensure that `numpy` docstrings are formatted correctly. (:pull:`62`).
 
 v0.3.0 (2023-12-01)
 -------------------

CONTRIBUTING.rst

@@ -106,6 +106,14 @@ Ready to contribute? Here's how to set up ``xhydro`` for local development.
     # Or, to run multiple build tests
     $ tox
 
+    .. note::
+
+        Running `pytest` or `tox` will automatically fetch and cache the testing data for the package to your local cache (using the `platformdirs` library). On Linux, this is located at ``XDG_CACHE_HOME`` (usually ``~/.cache``). On Windows, this is located at ``%LOCALAPPDATA%`` (usually ``C:\Users\username\AppData\Local``). On MacOS, this is located at ``~/Library/Caches``.
+
+        If for some reason you wish to cache this data elsewhere, you can set the ``XHYDRO_DATA_DIR`` environment variable to a different location before running the tests. For example, to cache the data in the current working directory, run::
+
+            $ export XHYDRO_DATA_DIR=$(pwd)/.cache
+
 #. Commit your changes and push your branch to GitHub::
 
     $ git add .
@@ -134,6 +142,12 @@ Ready to contribute? Here's how to set up ``xhydro`` for local development.
 
 You will have contributed your first changes to ``xhydro``!
 
+.. warning::
+
+    If your Pull Request relies on modifications to the testing data of `xhydro`, you will need to update the testing data repository as well. As a preliminary testing measure, the branch of the testing data can be modified at testing time (from `main`) by setting the ``XHYDRO_TESTDATA_BRANCH`` environment variable to the branch name of the ``xhydro-testdata`` repository.
+
+    Be sure to consult the ReadMe found at https://github.com/hydrologie/xhydro-testdata as well.
+
 Pull Request Guidelines
 -----------------------
 
@@ -160,7 +174,7 @@ To run specific code style checks::
     $ ruff xhydro tests
     $ flake8 xhydro tests
 
-To get ``black``, ``isort ``blackdoc``, ``ruff``, and ``flake8`` (with plugins ``flake8-alphabetize`` and ``flake8-rst-docstrings``) simply install them with `pip` (or `conda`) into your environment.
+To get ``black``, ``isort``, ``blackdoc``, ``ruff``, and ``flake8`` (with plugins ``flake8-alphabetize`` and ``flake8-rst-docstrings``) simply install them with ``pip`` (or ``conda``) into your environment.
 
 Versioning/Tagging
 ------------------

Makefile

@@ -22,6 +22,7 @@ endef
 export PRINT_HELP_PYSCRIPT
 
 BROWSER := python -c "$$BROWSER_PYSCRIPT"
+LOCALES := docs/locales
 
 help:
 	@python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
@@ -38,6 +39,7 @@ clean-build: ## remove build artifacts
 clean-docs: ## remove docs artifacts
 	rm -f docs/apidoc/xhydro*.rst
 	rm -f docs/apidoc/modules.rst
+	rm -f docs/locales/fr/LC_MESSAGES/*.mo
 	$(MAKE) -C docs clean
 
 clean-pyc: ## remove Python file artifacts
@@ -78,13 +80,21 @@ coverage: ## check code coverage quickly with the default Python
 autodoc: clean-docs ## create sphinx-apidoc files:
 	sphinx-apidoc -o docs/apidoc --private --module-first xhydro
 
+initialize-translations: clean-docs ## initialize translations, ignoring autodoc-generated files
+	${MAKE} -C docs gettext
+	sphinx-intl update -p docs/_build/gettext -d docs/locales -l fr
+
 linkcheck: autodoc ## run checks over all external links found throughout the documentation
 	$(MAKE) -C docs linkcheck
 
 docs: autodoc ## generate Sphinx HTML documentation, including API docs
-	$(MAKE) -C docs html
+	$(MAKE) -C docs html BUILDDIR="_build/html/en"
+ifneq ("$(wildcard $(LOCALES))","")
+	${MAKE} -C docs gettext
+	$(MAKE) -C docs html BUILDDIR="_build/html/fr" SPHINXOPTS="-D language='fr'"
+endif
 ifndef READTHEDOCS
-	$(BROWSER) docs/_build/html/index.html
+	$(BROWSER) docs/_build/html/en/html/index.html
 endif
 
 servedocs: docs ## compile the docs watching for changes

docs/conf.py

@@ -112,6 +112,10 @@
 # Usually you set "language" from the command line for these cases.
 language = "en"
 
+# Set the locales
+locale_dirs = ["locales"]
+gettext_compact = False
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path

docs/locales/fr/LC_MESSAGES/authors.po

@@ -0,0 +1,73 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2023, Thomas-Charles Fortier Filion
+# This file is distributed under the same license as the xHydro package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2023.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: xHydro 0.3.0\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2023-12-08 12:18-0500\n"
+"PO-Revision-Date: 2023-12-13 17:00-0500\n"
+"Last-Translator: Thomas-Charles Fortier Filion <tcff_hydro@outlook."
+"com>\n"
+"Language-Team: fr <LL@li.org>\n"
+"Language: fr\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n > 1);\n"
+"Generated-By: Babel 2.12.1\n"
+"X-Generator: Poedit 3.4.1\n"
+
+#: ../../../AUTHORS.rst:3
+msgid "Credits"
+msgstr "Crédits"
+
+#: ../../../AUTHORS.rst:6
+msgid "Development Lead"
+msgstr "Responsable du développement"
+
+#: ../../../AUTHORS.rst:8
+msgid ""
+"Thomas-Charles Fortier Filion <tcff_hydro@outlook.com> `@TC-FF <https://"
+"github.com/TC-FF>`_"
+msgstr ""
+"Thomas-Charles Fortier Filion <tcff_hydro@outlook.com> `@TC-FF <https://"
+"github.com/TC-FF>`_"
+
+#: ../../../AUTHORS.rst:11
+msgid "Co-Developers"
+msgstr "Co-développeurs"
+
+#: ../../../AUTHORS.rst:13
+msgid ""
+"Trevor James Smith <smith.trevorj@ouranos.ca> `@Zeitsperre <https://"
+"github.com/Zeitsperre>`_"
+msgstr ""
+"Trevor James Smith <smith.trevorj@ouranos.ca> `@Zeitsperre <https://"
+"github.com/Zeitsperre>`_"
+
+#: ../../../AUTHORS.rst:14
+msgid ""
+"Gabriel Rondeau-Genesse <rondeau-genesse.gabriel@ouranos.ca> `@RondeauG "
+"<https://github.com/RondeauG>`_"
+msgstr ""
+"Gabriel Rondeau-Genesse <rondeau-genesse.gabriel@ouranos.ca> `@RondeauG "
+"<https://github.com/RondeauG>`_"
+
+#: ../../../AUTHORS.rst:15
+msgid ""
+"Sébastien Langlois `@sebastienlanglois <https://github.com/"
+"sebastienlanglois>`_"
+msgstr ""
+"Sébastien Langlois `@sebastienlanglois <https://github.com/"
+"sebastienlanglois>`_"
+
+#: ../../../AUTHORS.rst:18
+msgid "Contributors"
+msgstr "Contributeurs"
+
+#: ../../../AUTHORS.rst:20
+msgid "None yet. Why not be the first?"
+msgstr "Il n'y en a pas encore. Pourquoi ne pas être le premier ?"