Ouranosinc · Zeitsperre · Mar 8, 2023 · Feb 27, 2023 · Feb 27, 2023 · Feb 27, 2023
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -7,6 +7,7 @@ repos:
   hooks:
   - id: pyupgrade
     args: ['--py38-plus']
+    exclude: 'xclim/core/indicator.py'
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.4.0
   hooks:

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -12,10 +12,10 @@ build:
   tools:
     python: "mambaforge-4.10"
   jobs:
-    pre_install:
-      - pip install llvmlite~=0.38 --ignore-installed
     pre_build:
-      - sphinx-apidoc -o docs/ --private --module-first xclim xclim/testing/tests
+      - 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-build -b linkcheck docs/ _build/linkcheck
 
 conda:

diff --git a/.github/CONTRIBUTING.rst → CONTRIBUTING.rst b/.github/CONTRIBUTING.rst → CONTRIBUTING.rst
diff --git a/HISTORY.rst b/HISTORY.rst
@@ -2,6 +2,19 @@
 History
 =======
 
+0.42.0 (unreleased)
+-------------------
+Contributors to this version: Trevor James Smith (:user:`Zeitsperre`).
+
+Internal changes
+^^^^^^^^^^^^^^^^
+* Documentation adjustments. (:issue:`1305`, :pull:`1308`):
+    * The CONTRIBUTING page has been moved to the top level of the repository.
+    * Information concerning the licensing of xclim is clearly indicated in README.
+    * `sphinx-autodoc-typehints` is now used to simplify call signatures generated in documentation.
+    * The SDBA module API is now found with the rest of the User API documentation.
+* Removed `Mapping` abstract base class types in call signatures (`dict` variables were always expected). (:pull:`1308`).
+
 0.41.0 (2023-02-28)
 -------------------
 Contributors to this version: Trevor James Smith (:user:`Zeitsperre`), Pascal Bourgault (:user:`aulemahal`), Ludwig Lierhammer (:user:`ludwiglierhammer`), Éric Dupuis (:user:`coxipi`).

diff --git a/Makefile b/Makefile
@@ -81,6 +81,11 @@ coverage: ## check code coverage quickly with the default Python
 autodoc: clean-docs ## create sphinx-apidoc files:
 	sphinx-apidoc -o docs/ --private --module-first xclim xclim/testing/tests
 
+autodoc-noindex: clean-docs ## create sphinx-apidoc files but without indexes 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
+
 linkcheck: autodoc ## run checks over all external links found throughout the documentation
 	$(MAKE) -C docs linkcheck
 
@@ -90,6 +95,12 @@ ifndef READTHEDOCS
 	$(BROWSER) docs/_build/html/index.html
 endif
 
+docs-noindex: autodoc-noindex ## generate Sphinx HTML documentation, including API docs, but without indexes for for indices and indicators
+	$(MAKE) -C docs html
+ifndef READTHEDOCS
+	$(BROWSER) docs/_build/html/index.html
+endif
+
 servedocs: docs ## compile the docs watching for changes
 	watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D .
 

diff --git a/README.rst b/README.rst
@@ -54,13 +54,21 @@ xclim is in active development and is being used in production by climate servic
 * If you would like to contribute code or documentation (which is greatly appreciated!), check out the `Contributing Guidelines`_ before you begin!
 
 .. _issue tracker: https://github.com/Ouranosinc/xclim/issues
-.. _Contributing Guidelines: https://github.com/Ouranosinc/xclim/blob/master/.github/CONTRIBUTING.rst
+.. _Contributing Guidelines: https://github.com/Ouranosinc/xclim/blob/master/CONTRIBUTING.rst
 
 How to cite this library
 ------------------------
 If you wish to cite xclim in a research publication, we kindly ask that you use the bibliographical reference information available through `Zenodo`_
 
-.. _Zenodo: https://doi.org/10.5281/zenodo.2795043
+.. _Zenodo: https://doi.org/10.5281/zenodo.2795043S
+
+License
+-------
+This is free software: you can redistribute it and/or modify it under the terms of the `Apache License 2.0`_. A copy of this license is provided in the code repository (`LICENSE`_).
+
+
+.. _Apache License 2.0: https://opensource.org/license/apache-2-0/
+.. _LICENSE: https://github.com/Ouranosinc/xclim/blob/master/LICENSE
 
 Credits
 -------

diff --git a/docs/analogues.rst b/docs/analogues.rst
@@ -1,40 +1,64 @@
 Spatial Analogues
 =================
 
-.. automodule:: xclim.analog
-   :members: spatial_analogs
-   :noindex:
+Spatial analogues are maps showing which areas have a present-day climate that is analogous to the future climate of a
+given place. This type of map can be useful for climate adaptation to see how well regions are coping today under
+specific climate conditions. For example, officials from a city located in a temperate region that may be expecting more
+heatwaves in the future can learn from the experience of another city where heatwaves are a common occurrence,
+leading to more proactive intervention plans to better deal with new climate conditions.
 
+Spatial analogues are estimated by comparing the distribution of climate indices computed at the target location over
+the future period with the distribution of the same climate indices computed over a reference period for multiple
+candidate regions. A number of methodological choices thus enter the computation:
 
-Analogue metrics API
---------------------
+    - Climate indices of interest,
+    - Metrics measuring the difference between both distributions,
+    - Reference data from which to compute the base indices,
+    - A future climate scenario to compute the target indices.
 
-.. autofunction:: xclim.analog.friedman_rafsky
-   :noindex:
+The climate indices chosen to compute the spatial analogues are usually annual values of indices relevant to the
+intended audience of these maps. For example, in the case of the wine grape industry, the climate indices examined could
+include the length of the frost-free season, growing degree-days, annual winter minimum temperature and annual number of
+very cold days :cite:p:`roy_probabilistic_2017`.
 
-.. autofunction:: xclim.analog.kldiv
-   :noindex:
+See :ref:`notebooks/analogs:Spatial Analogues examples`.
 
-.. autofunction:: xclim.analog.kolmogorov_smirnov
-   :noindex:
+Methods to compute the (dis)similarity between samples
+------------------------------------------------------
+This module implements all methods described in :cite:cts:`grenier_assessment_2013` to measure the dissimilarity between
+two samples, plus the Székely-Rizzo energy distance, some of these algorithms can be used to test whether two samples
+have been drawn from the same distribution. Here, they are used in finding areas with analogue climate conditions to a
+target climate:
 
-.. autofunction:: xclim.analog.nearest_neighbor
-   :noindex:
+ * Standardized Euclidean distance
+ * Nearest Neighbour distance
+ * Zech-Aslan energy statistic
+ * Székely-Rizzo energy distance
+ * Friedman-Rafsky runs statistic
+ * Kolmogorov-Smirnov statistic
+ * Kullback-Leibler divergence
 
-.. autofunction:: xclim.analog.seuclidean
-   :noindex:
+All methods accept arrays, the first is the reference (n, D) and the second is the candidate (m, D). Where the climate
+indicators vary along D and the distribution dimension along n or m. All methods output a single float. See their
+documentation in :ref:`analogues:Analogues Metrics API`.
 
-.. autofunction:: xclim.analog.szekely_rizzo
-   :noindex:
+.. warning::
 
-.. autofunction:: xclim.analog.zech_aslan
-   :noindex:
+   Some methods are scale-invariant and others are not. This is indicated in the docstring
+   of the methods as it can change the results significantly. In most cases, scale-invariance
+   is desirable and inputs may need to be scaled beforehand for scale-dependent methods.
 
-Utilities for developers
-------------------------
+.. rubric:: References
 
-.. autofunction:: xclim.analog.metric
-   :noindex:
+:cite:cts:`roy_probabilistic_2017`
+:cite:cts:`grenier_assessment_2013`
 
-.. autofunction:: xclim.analog.standardize
-   :noindex:
+Analogues Metrics API
+---------------------
+
+See: :ref:`spatial-analogues-api`
+
+Analogues Developer Functions
+-----------------------------
+
+See: :ref:`spatial-analogues-developer-api`