Contributing and overall doc comments (#1308)

### What kind of change does this PR introduce?

* 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.
* `HISTORY.rst` has been renamed `CHANGES.rst`, to follow `dask`-like conventions.
* Hyperlink targets for individual `indices` and `indicators` now point to their entries under `API` or `Indices`.
* Module-level docstrings have migrated from the library scripts directly into the documentation RestructuredText files.
* The documentation now includes a page explaining the reasons for developing `xclim` and a section briefly detailing similar and related projects.
* Markdown explanations in some Jupyter Notebooks have been edited for clarity
* Removed `Mapping` abstract base class types in call signatures (`dict` variables were always expected). 

### Does this PR introduce a breaking change?

Yes. The docs have been completely reorganized.

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,7 +5,7 @@
     - This PR fixes #xyz
 - [ ] Tests for the changes have been added (for bug fixes / features)
   - [ ] (If applicable) Documentation has been added / updated (for bug fixes / features)
-- [ ] HISTORY.rst has been updated (with summary of main changes)
+- [ ] CHANGES.rst has been updated (with summary of main changes)
   - [ ] Link to issue (:issue:`number`) and pull request (:pull:`number`) has been added
 
 ### What kind of change does this PR introduce?

.github/workflows/bump-version.yml

@@ -7,7 +7,7 @@ on:
     paths-ignore:
       - .*
       - .github/**.yml
-      - HISTORY.rst
+      - CHANGES.rst
       - Makefile
       - docs/**.ipynb
       - docs/**.py

.github/workflows/codeql-analysis.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - master
     paths-ignore:
-      - HISTORY.rst
+      - CHANGES.rst
       - Makefile
       - pyproject.toml
       - requirements_upstream.txt

.github/workflows/main.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - master
     paths-ignore:
-      - HISTORY.rst
+      - CHANGES.rst
       - README.rst
       - pyproject.toml
       - setup.cfg

.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:

.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:

HISTORY.rst → CHANGES.rst

@@ -1,6 +1,6 @@
-=======
-History
-=======
+=========
+Changelog
+=========
 
 0.42.0 (unreleased)
 -------------------
@@ -9,6 +9,17 @@ Contributors to this version: Trevor James Smith (:user:`Zeitsperre`).
 Internal changes
 ^^^^^^^^^^^^^^^^
 * Added `xclim` to the `ouranos Zenodo community <https://zenodo.org/communities/ouranos/>`_ . (:pull:`1313`).
+* Significant 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.
+    * `HISTORY.rst` has been renamed `CHANGES.rst`, to follow `dask`-like conventions.
+    * Hyperlink targets for individual `indices` and `indicators` now point to their entries under `API` or `Indices`.
+    * Module-level docstrings have migrated from the library scripts directly into the documentation RestructuredText files.
+    * The documentation now includes a page explaining the reasons for developing `xclim` and a section briefly detailing similar and related projects.
+    * Markdown explanations in some Jupyter Notebooks have been edited for clarity
+* Removed `Mapping` abstract base class types in call signatures (`dict` variables were always expected). (:pull:`1308`).
 
 0.41.0 (2023-02-28)
 -------------------

Makefile

@@ -78,13 +78,18 @@ coverage: ## check code coverage quickly with the default Python
 	coverage html
 	$(BROWSER) htmlcov/index.html
 
-autodoc: clean-docs ## create sphinx-apidoc files:
+autodoc-obsolete: clean-docs ## create sphinx-apidoc files (obsolete)
 	sphinx-apidoc -o docs/ --private --module-first xclim xclim/testing/tests
 
-linkcheck: autodoc ## run checks over all external links found throughout the documentation
+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
+
+linkcheck: autodoc-custom-index ## run checks over all external links found throughout the documentation
 	$(MAKE) -C docs linkcheck
 
-docs: autodoc ## generate Sphinx HTML documentation, including API docs
+docs: autodoc-custom-index ## 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

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
 -------

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 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 the distributions of indices,
+    - 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, as well as 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`