Contributing and overall doc comments

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

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`).

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/api.rst

@@ -2,9 +2,16 @@
 API
 ===
 
-The API of the statistical downscaling and bias adjustment module (sdba) is documented :ref:`on this page <sdba:SDBA User API>`.
-The API of the ``cfchecks``, ``datachecks``, ``missing`` and ``dataflags`` modules are in :ref:`checks:Health Checks`.
-Finally, the API of the translating tools is on the :ref:`internationalization:Internationalization` page.
+.. note::
+
+    The API of the ``cfchecks``, ``datachecks``, ``missing`` and ``dataflags`` modules are located under :ref:`checks:Health Checks`.
+
+    The API for the translation tools can be found within :ref:`internationalization:Internationalization`.
+
+.. contents:: Table of Contents
+   :depth: 1
+   :local:
+   :backlinks: none
 
 Indicators
 ==========
@@ -17,6 +24,7 @@ Indices
 =======
 
 .. toctree::
+   :maxdepth: 3
 
    indices
 
@@ -33,16 +41,19 @@ Ensembles module
 .. Use of autofunction is so that paths do not include private modules.
 .. autofunction:: xclim.ensembles.kkz_reduce_ensemble
     :noindex:
+
 .. autofunction:: xclim.ensembles.kmeans_reduce_ensemble
     :noindex:
+
 .. autofunction:: xclim.ensembles.plot_rsqprofile
     :noindex:
 
 .. automodule:: xclim.ensembles._robustness
-    :noindeX:
+    :noindex:
 
 .. autofunction:: xclim.ensembles.change_significance
     :noindex:
+
 .. autofunction:: xclim.ensembles.robustness_coefficient
     :noindex:
 
@@ -64,6 +75,82 @@ Unit Handling module
    :show-inheritance:
    :noindex:
 
+.. _sdba-user-api:
+
+SDBA module
+===========
+
+.. automodule:: xclim.sdba.adjustment
+   :members:
+   :exclude-members: BaseAdjustment
+   :special-members:
+   :show-inheritance:
+   :noindex:
+
+.. automodule:: xclim.sdba.processing
+   :members:
+   :noindex:
+
+.. automodule:: xclim.sdba.detrending
+   :members:
+   :show-inheritance:
+   :exclude-members: BaseDetrend
+   :noindex:
+
+.. automodule:: xclim.sdba.utils
+   :members:
+   :noindex:
+
+.. autoclass:: xclim.sdba.base.Grouper
+   :members:
+   :class-doc-from: init
+   :noindex:
+
+.. automodule:: xclim.sdba.nbutils
+   :members:
+   :noindex:
+
+.. automodule:: xclim.sdba.loess
+   :members:
+   :noindex:
+
+.. automodule:: xclim.sdba.properties
+   :members:
+   :exclude-members: StatisticalProperty
+   :noindex:
+
+.. automodule:: xclim.sdba.measures
+   :members:
+   :exclude-members: StatisticalMeasure
+   :noindex:
+
+SDBA Developer tools
+--------------------
+
+.. automodule:: xclim.sdba.base
+   :members:
+   :show-inheritance:
+   :exclude-members: Grouper
+   :noindex:
+
+.. autoclass:: xclim.sdba.detrending.BaseDetrend
+   :members:
+   :noindex:
+
+.. autoclass:: xclim.sdba.adjustment.TrainAdjust
+   :members:
+   :noindex:
+
+.. autoclass:: xclim.sdba.adjustment.Adjust
+   :members:
+   :noindex:
+
+.. autofunction:: xclim.sdba.properties.StatisticalProperty
+   :noindex:
+
+.. autofunction:: xclim.sdba.measures.StatisticalMeasure
+   :noindex:
+
 Other Utilities
 ===============
 

docs/conf.py

@@ -108,6 +108,7 @@ def _indicator_table(module):
     "autodoc_indicator",
     "sphinxcontrib.bibtex",
     "sphinxcontrib.cairosvgconverter",
+    "sphinx_autodoc_typehints",
     "sphinx_codeautolink",
     "sphinx_copybutton",
     "sphinx_rtd_theme",

docs/contributing.rst

@@ -1 +1 @@
-.. include:: ../.github/CONTRIBUTING.rst
+.. include:: ../CONTRIBUTING.rst

docs/sdba.rst

@@ -2,7 +2,6 @@
 Bias Adjustment and Downscaling Algorithms
 ==========================================
 
-
 The `xclim.sdba` submodule provides a collection of bias-adjustment methods meant to correct for systematic biases found in climate model simulations relative to observations.
 Almost all adjustment algorithms conform to the `train` - `adjust` scheme, meaning that adjustment factors are first estimated on training data sets, then applied in a distinct step to the data to be adjusted.
 Given a reference time series (ref), historical simulations (hist) and simulations to be adjusted (sim),
@@ -29,8 +28,7 @@ series, and possibly reduce the number of quantile bins that needs to be used.
 
 Modular Approach
 ================
-
-The module atempts to adopt a modular approach instead of implementing published and named methods directly.
+The module attempts to adopt a modular approach instead of implementing published and named methods directly.
 A generic bias adjustment process is laid out as follows:
 
 - preprocessing on ``ref``, ``hist`` and ``sim`` (using methods in :py:mod:`xclim.sdba.processing` or :py:mod:`xclim.sdba.detrending`)
@@ -40,7 +38,7 @@ A generic bias adjustment process is laid out as follows:
 
 The train-adjust approach allows to inspect the trained adjustment object. The training information is stored in
 the underlying `Adj.ds` dataset and usually has a `af` variable with the adjustment factors. Its layout and the
-other available variables vary between the different algorithm, refer to :ref:`Adjustment methods <sdbauserapi>`.
+other available variables vary between the different algorithm, refer to :ref:`Adjustment methods <sdba-user-api>`.
 
 Parameters needed by the training and the adjustment are saved to the ``Adj.ds`` dataset as a `adj_params` attribute.
 Parameters passed to the `adjust` call are written to the history attribute in the output scenario DataArray.
@@ -49,7 +47,6 @@ Parameters passed to the `adjust` call are written to the history attribute in t
 
 Grouping
 ========
-
 For basic time period grouping (months, day of year, season), passing a string to the methods needing it is sufficient.
 Most methods acting on grouped data also accept a `window` int argument to pad the groups with data from adjacent ones.
 Units of `window` are the sampling frequency of the main grouping dimension (usually `time`). For more complex grouping,
@@ -63,27 +60,22 @@ In a conventionnal empirical quantile mapping (EQM), this will compute the quant
     passed, the adjustment factors will always be interpolated to the largest range of day of the years but this can
     lead to strange values, so we recommend converting the data beforehand to a common calendar.
 
-
 Application in multivariate settings
 ====================================
-
 When applying univariate adjustment methods to multiple variables, some strategies are recommended to avoid introducing unrealistic artifacts in adjusted outputs.
 
 Minimum and maximum temperature
 -------------------------------
-
 When adjusting both minimum and maximum temperature, adjustment factors sometimes yield minimum temperatures larger than the maximum temperature on the same day, which of course, is nonsensical.
 One way to avoid this is to first adjust maximum temperature using an additive adjustment, then adjust the diurnal temperature range (DTR) using a multiplicative adjustment, and then determine minimum temperature by subtracting DTR from the maximum temperature :cite:p:`thrasher_technical_2012,agbazo_characterizing_2020`.
 
 Relative and specific humidity
 ------------------------------
-
 When adjusting both relative and specific humidity, we want to preserve the relationship between both.
 To do this, :cite:t:`grenier_two_2018` suggests to first adjust the relative humidity using a multiplicative factor, ensure values are within 0-100%, then apply an additive adjustment factor to the surface pressure before estimating the specific humidity from thermodynamic relationships.
 
 Radiation and precipitation
----------------------------
-
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 In theory, short wave radiation should be capped when precipitation is not zero, but there is as of yet no mechanism proposed to do that, see :cite:t:`hoffmann_meteorologically_2012`.
 
 Usage examples
@@ -92,7 +84,6 @@ The usage of this module is documented in two example notebooks: `SDBA <notebook
 
 Discussion topics
 =================
-
 Some issues were also discussed on the Github repository. Most of these are still open questions, feel free to participate to the discussion!
 
 * Number quantiles to use in quantile mapping methods: :issue:`1162`
@@ -125,81 +116,11 @@ See the `sdba-advanced` notebook for more info on the reasons for this move.
 Other restrictions : ``map_blocks`` will remove any "auxiliary" coordinates before calling the wrapped function and will
 add them back on exit.
 
-.. _sdbauserapi:
-
-SDBA User API
-=============
-
-.. automodule:: xclim.sdba.adjustment
-   :members:
-   :exclude-members: BaseAdjustment
-   :special-members:
-   :show-inheritance:
-   :noindex:
-
-.. automodule:: xclim.sdba.processing
-   :members:
-   :noindex:
-
-.. automodule:: xclim.sdba.detrending
-   :members:
-   :show-inheritance:
-   :exclude-members: BaseDetrend
-   :noindex:
-
-.. automodule:: xclim.sdba.utils
-   :members:
-   :noindex:
-
-.. autoclass:: xclim.sdba.base.Grouper
-   :members:
-   :class-doc-from: init
-   :noindex:
-
-.. automodule:: xclim.sdba.nbutils
-   :members:
-   :noindex:
-
-.. automodule:: xclim.sdba.loess
-   :members:
-   :noindex:
-
-.. automodule:: xclim.sdba.properties
-   :members:
-   :exclude-members: StatisticalProperty
-   :noindex:
-
-.. automodule:: xclim.sdba.measures
-   :members:
-   :exclude-members: StatisticalMeasure
-   :noindex:
-
-Developer tools
-===============
-
-.. automodule:: xclim.sdba.base
-   :members:
-   :show-inheritance:
-   :exclude-members: Grouper
-   :noindex:
-
-.. autoclass:: xclim.sdba.detrending.BaseDetrend
-   :members:
-   :noindex:
-
-.. autoclass:: xclim.sdba.adjustment.TrainAdjust
-   :members:
-   :noindex:
-
-.. autoclass:: xclim.sdba.adjustment.Adjust
-   :members:
-   :noindex:
-
-.. autofunction:: xclim.sdba.properties.StatisticalProperty
-   :noindex:
-
-.. autofunction:: xclim.sdba.measures.StatisticalMeasure
-   :noindex:
+User API
+========
+
+See: :ref:`sdba-user-api`
+
 
 .. only:: html or text
 

environment.yml

@@ -52,6 +52,7 @@ dependencies:
     - pytest-cov
     - pytest-xdist>=3.2
     - sphinx
+    - sphinx-autodoc-typehints
     - sphinx-codeautolink
     - sphinx-copybutton
     - sphinx-rtd-theme>=1.0

pyproject.toml

@@ -83,6 +83,7 @@ dev = [
   "netCDF4 >=1.4",
   "pooch",
   "sphinx",
+  "sphinx-autodoc-typehints",
   "sphinx-codeautolink",
   "sphinx-copybutton",
   "sphinx-rtd-theme >=1.0",