Merge branch 'master' into adapt_freq_in_training

.github/labeler.yml

@@ -5,6 +5,10 @@
 #   Since this repository is in itself an automation process to deploy a server instance,
 #   we refer here to CI as the 'meta' configuration files for managing the code and integrations with the repository,
 #   not configurations related to the deployment process itself.
+
+API:
+  - xclim/cli.py
+
 CI:
   - .*  # all '.<something>' files
   - .github/workflows/*
@@ -14,7 +18,7 @@ CI:
   - Makefile
 
 docs:
-  - ".readthedocs.yml"
+  - .readthedocs.yml
   - docs/**/*
   - AUTHORS.rst
   - CONTRIBUTING.rst

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

@@ -15,7 +15,7 @@ jobs:
         with:
           token: ${{ secrets.WORKFLOW_TOKEN }}
       - name: Run GitHub Actions Version Updater
-        uses: saadmk11/github-actions-version-updater@v0.7.4
+        uses: saadmk11/github-actions-version-updater@v0.8.1
         with:
           token: ${{ secrets.WORKFLOW_TOKEN }}
           committer_email: 'bumpversion[bot]@ouranos.ca'

.github/workflows/codeql-analysis.yml

@@ -35,7 +35,7 @@ jobs:
           - 'python'
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v2

.github/workflows/dependency-review.yml

@@ -5,7 +5,8 @@
 # Source repository: https://github.com/actions/dependency-review-action
 # Public documentation: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement
 name: 'Dependency Review'
-on: [pull_request]
+on:
+  pull_request:
 
 permissions:
   contents: read
@@ -17,4 +18,4 @@ jobs:
       - name: 'Checkout Repository'
         uses: actions/checkout@v3
       - name: 'Dependency Review'
-        uses: actions/dependency-review-action@v2
+        uses: actions/dependency-review-action@v3

.github/workflows/first_pull_request.yml

@@ -39,8 +39,8 @@ jobs:
               repo: context.repo.repo,
               body: `**Welcome**, new contributor!
 
-                It appears that this is your first Pull Request. To give credit where it's due, we ask that you add your information to the \`AUTHORS.rst\` and \`.zenodo.json\`:
-                 - [ ] The relevant author information has been added to \`AUTHORS.rst\` and \`.zenodo.json\`
+              It appears that this is your first Pull Request. To give credit where it's due, we ask that you add your information to the \`AUTHORS.rst\` and \`.zenodo.json\`:
+               - [ ] The relevant author information has been added to \`AUTHORS.rst\` and \`.zenodo.json\`
 
-                Please make sure you've read our [contributing guide](CONTRIBUTING.rst). We look forward to reviewing your Pull Request shortly ✨`
+              Please make sure you've read our [contributing guide](CONTRIBUTING.rst). We look forward to reviewing your Pull Request shortly ✨`
             })

.pre-commit-config.yaml

@@ -22,6 +22,7 @@ repos:
   - id: debug-statements
   - id: pretty-format-json
     args: ['--autofix', '--no-ensure-ascii', '--no-sort-keys']
+    exclude: '.ipynb'
 - repo: https://github.com/pappasam/toml-sort
   rev: v0.23.1
   hooks:
@@ -70,7 +71,12 @@ repos:
   hooks:
   - id: blackdoc
     exclude: '(xclim/indices/__init__.py|docs/installation.rst)'
-    additional_dependencies: ['black==23.3.0']
+    additional_dependencies: ['black==23.7.0']
+- repo: https://github.com/python-jsonschema/check-jsonschema
+  rev: 0.23.3
+  hooks:
+  - id: check-github-workflows
+  - id: check-readthedocs
 - repo: meta
   hooks:
   - id: check-hooks-apply

.readthedocs.yml

@@ -13,9 +13,9 @@ build:
     python: "mambaforge-4.10"
   jobs:
     pre_build:
-      - sphinx-apidoc -o docs/ --private --module-first xclim xclim/testing/tests xclim/indicators xclim/indices
-      - rm docs/xclim.rst
-      - env SPHINX_APIDOC_OPTIONS="members,undoc-members,show-inheritance,noindex" sphinx-apidoc -o docs/ --private --module-first xclim xclim/testing/tests
+      - sphinx-apidoc -o docs/apidoc/ --private --module-first xclim xclim/testing/tests xclim/indicators xclim/indices
+      - rm docs/apidoc/xclim.rst
+      - env SPHINX_APIDOC_OPTIONS="members,undoc-members,show-inheritance,noindex" sphinx-apidoc -o docs/apidoc/ --private --module-first xclim xclim/testing/tests
       - sphinx-build -b linkcheck docs/ _build/linkcheck || true
 
 conda:

CHANGES.rst

@@ -11,7 +11,7 @@ New features and enhancements
 * Added ``ensembles.hawkins_sutton`` method to partition the uncertainty sources in a climate projection ensemble. (:issue:`771`, :pull:`1262`).
 * New function ``xclim.core.calendar.convert_doy`` to transform day-of-year data between calendars. Also accessible from ``convert_calendar`` with ``doy=True``. (:issue:`1283`, :pull:`1406`).
 * Added new function ``xclim.sdba.properties.std`` to calculate the standard deviation of a variable over all years at a given time resolution. (:pull:`1445`).
-* Amended the documentation of ``xclim.sdba.properties.trend`` to document already existing functionality of calculating the return values of scipy.stats.linregress. (:pull:`1445`).
+* Amended the documentation of ``xclim.sdba.properties.trend`` to document already existing functionality of calculating the return values of ``scipy.stats.linregress``. (:pull:`1445`).
 * Add support for setting optional variables through the `ds` argument. (:issue:`1432`, :pull:`1435`).
 * `adapt_freq_thresh` argument added `sdba` training functions, allowing to perform frequency adaptation appropriately in each map block. (:pull:`1407`).
 
@@ -29,8 +29,12 @@ Internal changes
 * Tolerance thresholds for error in ``test_stats::test_fit`` have been relaxed to allow for more variation in the results. Previously untested ``*_moving_yearly_window`` functions are now tested. (:issue:`1400`, :pull:`1402`).
 * Increased the guess of number of quantiles needed in ExtremeValues. (:pull:`1413`).
 * Tolerance thresholds for error in ``test_processing::test_adapt_freq`` have been relaxed to allow for more variation in the results. (:issue:`1417`, :pull:`1418`).
-* Added 'streamflow' to the list of known variables (:pull:`1431`).
-* Fix and adapt ``percentile_doy`` for an error raised by xarray > 2023.7.0 (:issue:`1417`, :pull:`1450`).
+* Added 'streamflow' to the list of known variables. (:pull:`1431`).
+* Fix and adapt ``percentile_doy`` for an error raised by xarray > 2023.7.0. (:issue:`1417`, :pull:`1450`).
+* Shuffle autogenerated documentation files into distinct folders that can be easily cleaned using Makefile. (:pull:`1449`).
+* Some docstring adjustments to existing classes. (:pull:`1449`).
+* `identify` now associates Jupyter Notebooks as JSON files. Set `pre-commit` to ignore JSON-formatting of them. (:pull:`1449`).
+* Added a helper module ``_finder`` in the notebooks folder so that the working directory can always be found, with redundancies in place to prevent scripts from failing if the helper file is not found. (:pull:`1449`).
 
 v0.44.0 (2023-06-23)
 --------------------

Makefile

@@ -3,13 +3,9 @@
 
 define BROWSER_PYSCRIPT
 import os, webbrowser, sys
+from urllib.request import pathname2url
 
-try:
-	from urllib import pathname2url
-except:
-	from urllib.request import pathname2url
-
-webbrowser.open("file://" + pathname2url(os.path.abspath(sys.argv[1])))
+webbrowser.open(f"file://{pathname2url(os.path.abspath(sys.argv[1]))}")
 endef
 export BROWSER_PYSCRIPT
 
@@ -39,8 +35,9 @@ clean-build: ## remove build artifacts
 	find . -name '*.egg' -exec rm -f {} +
 
 clean-docs: ## remove docs artifacts
-	rm -f docs/xclim*.rst
-	rm -f docs/modules.rst
+	rm -f docs/apidoc/xclim*.rst
+	rm -f docs/apidoc/modules.rst
+	rm -f docs/notebooks/data/*.nc
 	$(MAKE) -C docs clean
 
 clean-pyc: ## remove Python file artifacts
@@ -81,12 +78,14 @@ coverage: ## check code coverage quickly with the default Python
 	$(BROWSER) htmlcov/index.html
 
 autodoc-obsolete: clean-docs ## create sphinx-apidoc files (obsolete)
-	sphinx-apidoc -o docs/ --private --module-first xclim xclim/testing/tests
+	mkdir -p docs/apidoc/
+	sphinx-apidoc -o docs/apidoc/ --private --module-first xclim xclim/testing/tests
 
 autodoc-custom-index: clean-docs ## create sphinx-apidoc files but with special index handling for indices and indicators
-	sphinx-apidoc -o docs/ --private --module-first xclim xclim/testing/tests xclim/indicators xclim/indices
-	rm docs/xclim.rst
-	env SPHINX_APIDOC_OPTIONS="members,undoc-members,show-inheritance,noindex" sphinx-apidoc -o docs/ --private --module-first xclim xclim/testing/tests
+	mkdir -p docs/apidoc/
+	sphinx-apidoc -o docs/apidoc/ --private --module-first xclim xclim/testing/tests xclim/indicators xclim/indices
+	rm docs/apidoc/xclim.rst
+	env SPHINX_APIDOC_OPTIONS="members,undoc-members,show-inheritance,noindex" sphinx-apidoc -o docs/apidoc/ --private --module-first xclim xclim/testing/tests
 
 linkcheck: autodoc-custom-index ## run checks over all external links found throughout the documentation
 	$(MAKE) -C docs linkcheck

docs/conf.py

@@ -108,12 +108,17 @@ def _indicator_table(module):
     "autodoc_indicator",
     "sphinxcontrib.bibtex",
     "sphinxcontrib.cairosvgconverter",
+    # sphinx_autodoc_typehints must always be listed after sphinx.ext.napoleon
     "sphinx_autodoc_typehints",
     "sphinx_codeautolink",
     "sphinx_copybutton",
     "sphinx_rtd_theme",
 ]
 
+autodoc_typehints = "description"
+autodoc_typehints_format = "fully-qualified"
+autodoc_typehints_description_target = "documented_params"
+
 autosectionlabel_prefix_document = True
 autosectionlabel_maxdepth = 2
 
@@ -177,10 +182,11 @@ def _indicator_table(module):
 intersphinx_mapping = {
     "clisops": ("https://clisops.readthedocs.io/en/latest/", None),
     "flox": ("https://flox.readthedocs.io/en/latest/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "sklearn": ("https://scikit-learn.org/stable/", None),
     "statsmodels": ("https://www.statsmodels.org/stable/", None),
-    "numpy": ("https://numpy.org/doc/stable/", None),
 }
 extlinks = {
     "issue": ("https://github.com/Ouranosinc/xclim/issues/%s", "GH/%s"),

docs/index.rst

@@ -53,7 +53,7 @@ Leveraging xarray and dask, users can easily bias-adjust climate simulations ove
    :maxdepth: 1
    :caption: All Modules
 
-   modules
+   apidoc/modules
 
 .. only:: html
 

docs/notebooks/_finder.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _find_current_folder():
+    """Find the folder containing the notebooks.
+
+    Needed in order to run the notebooks from the docs/notebooks folder.
+    """
+    return Path(__file__).absolute().parent

docs/notebooks/analogs.ipynb

@@ -245,7 +245,7 @@
     "    ax.set_title(metric)\n",
     "axs[0, 0].legend()\n",
     "axs[-1, -1].set_visible(False)\n",
-    "fig.tight_layout()\n"
+    "fig.tight_layout()"
    ]
   }
  ],