first try at configuring references

.readthedocs.yml

@@ -18,7 +18,7 @@ build:
     pre_install:
       # FIXME: This is a workaround to install xclim v0.53, which is not released.
       - mamba install -y -n base -c conda-forge "xclim=0.52.2"
-      - pip install git+https://github.com/Ouranosinc/xclim.git@main
+      - python -m pip install git+https://github.com/Ouranosinc/xclim.git@main
     pre_build:
       - sphinx-apidoc -o docs/apidoc --private --module-first src/xsdba
       - sphinx-build -M gettext docs docs/_build

docs/conf.py

@@ -22,8 +22,18 @@
 
 sys.path.insert(0, os.path.abspath('..'))
 
+import xarray
+from pybtex.plugin import register_plugin
+from pybtex.style.formatting.alpha import Style as AlphaStyle
+from pybtex.style.labels import BaseLabelStyle
+
+xarray.DataArray.__module__ = "xarray"
+xarray.Dataset.__module__ = "xarray"
+xarray.CFTimeIndex.__module__ = "xarray"
+
 import xsdba
 
+
 # -- General configuration ---------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -37,8 +47,10 @@
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.extlinks',
     "sphinx.ext.intersphinx",
-    'sphinx.ext.viewcode',
+    "sphinx.ext.napoleon",
     'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+    "sphinxcontrib.bibtex",
     'sphinx_codeautolink',
     'sphinx_copybutton',
 ]
@@ -54,6 +66,24 @@
     "special-members": False,
 }
 
+
+# Bibliography stuff
+# a simple label style which uses the bibtex keys for labels
+class XCLabelStyle(BaseLabelStyle):
+    def format_labels(self, sorted_entries):
+        for entry in sorted_entries:
+            yield entry.key
+
+
+class XCStyle(AlphaStyle):
+    default_label_style = XCLabelStyle
+
+
+register_plugin("pybtex.style.formatting", "xcstyle", XCStyle)
+bibtex_bibfiles = ["references.bib"]
+bibtex_default_style = "xcstyle"
+bibtex_reference_style = "author_year"
+
 intersphinx_mapping = {
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
 }

docs/index.rst

@@ -8,6 +8,7 @@ Welcome to xsdba's documentation!
    readme
    installation
    usage
+   xsdba
    contributing
    releasing
    authors

docs/xsdba.rst

@@ -4,9 +4,7 @@ Bias Adjustment and Downscaling Algorithms
 
 The `xsdba` 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``),
-any bias-adjustment method would be applied by first estimating the adjustment factors between the historical simulation
-and the observation series, and then applying these factors to `sim`, which could be a future simulation:
+Given a reference time series (`ref`), historical simulations (`hist`) and simulations to be adjusted (`sim`), any bias-adjustment method would be applied by first estimating the adjustment factors between the historical simulation and the observation series, and then applying these factors to `sim``, which could be a future simulation:
 
 .. code-block:: python
 
@@ -31,16 +29,18 @@ Modular Approach
 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:`xsdba.processing` or :py:mod:`xsdba.detrending`)
+- preprocessing on `ref`, `hist` and `sim` (using methods in :py:mod:`xsdba.processing` or :py:mod:`xsdba.detrending`)
 - creating and training the adjustment object ``Adj = Adjustment.train(obs, sim, **kwargs)`` (from :py:mod:`xsdba.adjustment`)
 - adjustment ``scen = Adj.adjust(sim, **kwargs)``
-- post-processing on ``scen`` (for example: re-trending)
+- post-processing on `scen` (for example: re-trending)
 
 ..
+
     TODO : Find a way to link API below, and those later in the file.
-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 <sdba-user-api>`.
+
+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 <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.
@@ -57,6 +57,7 @@ for each day of the year but across all realizations of an ensemble : ``group =
 In a conventional empirical quantile mapping (EQM), this will compute the quantiles for each day of year and all realizations together, yielding a single set of adjustment factors for all realizations.
 
 .. warning::
+
     If grouping according to the day of the year is needed, the :py:mod:`xsdba.calendar` submodule contains useful
     tools to manage the different calendars that the input data can have. By default, if 2 different calendars are
     passed, the adjustment factors will always be interpolated to the largest range of day of the years but this can

environment-docs.yml

@@ -11,5 +11,6 @@ dependencies:
   - sphinx-codeautolink
   - sphinx-copybutton
   - sphinx-intl
+  - sphinxcontrib-bibtex
   - sphinxcontrib-napoleon
   - typer >=0.12.3

src/xsdba/__init__.py

@@ -20,13 +20,13 @@
 
 from __future__ import annotations
 
-import importlib
+import importlib.util
 import warnings
 
 from . import adjustment, base, detrending, processing, testing, units, utils
 
 xclim_installed = importlib.util.find_spec("xclim") is not None
-if xclim_installed:
+if not xclim_installed:
     warnings.warn(
         "Sub-modules `properties` and `measures` depend on `xclim`. Run `pip install xsdba['extras']` to install it."
     )