Use Furo documentation theme (#1731)

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

* Replaces the `sphinx-rtd-theme` for the `furo` documentation theme
* Adapts the `conf.py` to make use of specific variables for `furo`
* `pygments` themes and CSS overrides have been added to ensure adequate
contrast of documentation elements in both "dark" and "light" modes
* Adds alternate logos for the "dark" theme
* Updates the docstrings for `xclim/data/__init__.py`,
`xclim/core/locales.py`, `xclim/core/formatting.py`, and others
* Synchronizes tooling dependency versions (ruff, black, yamllint)
* `generate_indicator_docstring` has been adjusted to ensure that
information blocks (e.g. `Parameters`, `Returns`) always have newlines
between them and that call signature attributes are indented four (4)
spaces instead of two (2)
* The `pygments`-affected code blocks in `extendxclim.ipynb` have been
modified to produce nicer outputs

### Does this PR introduce a breaking change?

Yes. 
- The theme has been completely replaced with `furo`, which gives us a
dark mode for free as well as better navigation scroll bars when viewing
pages in landscape mode.
- Indicator docstrings have been modified to ensure that `Parameters`
items conform strictly to `numpy`-docstring format (indentations of four
spaces for attributes, changed from two spaces).

.gitignore

@@ -109,7 +109,7 @@ ENV/
 # autogenerated RestructuredText
 docs/apidoc/modules.rst
 docs/apidoc/xclim*.rst
-docs/indicators.json
+docs/_dynamic/indicators.json
 docs/variables.json
 
 .vscode

.pre-commit-config.yaml

@@ -33,7 +33,7 @@ repos:
       - id: yamllint
         args: [ '--config-file=.yamllint.yaml' ]
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 24.4.0
+    rev: 24.4.1
     hooks:
       - id: black
   - repo: https://github.com/PyCQA/isort
@@ -66,7 +66,7 @@ repos:
         args: [ '--py39-plus' ]
         additional_dependencies: [ 'pyupgrade==3.15.2' ]
       - id: nbqa-black
-        additional_dependencies: [ 'black==24.4.0' ]
+        additional_dependencies: [ 'black==24.4.1' ]
       - id: nbqa-isort
         additional_dependencies: [ 'isort==5.13.2' ]
   - repo: https://github.com/kynan/nbstripout
@@ -79,7 +79,7 @@ repos:
     rev: v0.3.9
     hooks:
       - id: blackdoc
-        additional_dependencies: [ 'black==24.4.0' ]
+        additional_dependencies: [ 'black==24.4.1' ]
         exclude: '(xclim/indices/__init__.py|docs/installation.rst)'
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.6

.zenodo.json

@@ -41,6 +41,11 @@
       "affiliation": "Ouranos, Montréal, Québec, Canada",
       "orcid": "0000-0003-3389-9406"
     },
+    {
+      "name": "Gammon, Sarah",
+      "affiliation": "Ouranos, Montréal, Québec, Canada",
+      "orcid": "0009-0007-6082-9063"
+    },
     {
       "name": "Alegre, Raquel",
       "affiliation": "University College London, London, United Kingdom",

AUTHORS.rst

@@ -29,6 +29,7 @@ Contributors
 * David Caron `@davidcaron <https://github.com/davidcaron>`_
 * Carsten Ehbrecht <[email protected]> `@cehbrecht <https://github.com/cehbrecht>`_
 * Jeremy Fyke `@jeremyfyke <https://github.com/jeremyfyke>`_
+* Sarah Gammon <[email protected]> `@SarahG-579462 <https://github.com/SarahG-579462>`_
 * Tom Keel <[email protected]> `@Thomasjkeel <https://github.com/Thomasjkeel>`_
 * Marie-Pier Labonté <[email protected]> `@marielabonte <https://github.com/marielabonte>`_
 * Ludwig Lierhammer <[email protected]> `@ludwiglierhammer <https://github.com/ludwiglierhammer>`_

CHANGES.rst

@@ -13,9 +13,8 @@ Announcements
 New features and enhancements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 * Indicator ``xclim.atmos.potential_evapotranspiration`` and indice ``xclim.indices.potential_evapotranspiration`` now accept a new value (`DA02`) for argument `method` implementing potential evapotranspiration based on Droogers and Allen (2002). (:issue:`1710`, :pull:`1723`).
-* `ensemble_percentiles` now takes a `method` argument, accepting
-  'interpolated_inverted_cdf', 'hazen', 'weibull', 'linear'  (default),
-  'median_unbiased' and 'normal_unbiased'. (:issue:`1694`, :pull:`1732`).
+* ``xclim.ensembles.ensemble_percentiles`` now takes a `method` argument, accepting one of: `'interpolated_inverted_cdf'`, `'hazen'`, `'weibull'`, `'linear'` (default), `'median_unbiased'`, or `'normal_unbiased'`. (:issue:`1694`, :pull:`1732`).
+* The documentation now uses the `furo <https://github.com/pradyunsg/furo>`_ theme for Sphinx. This theme supports native "light" and "dark" modes, adaptive screen resolution, as well as provides a better navigation layout for pages housing long lists of entries (e.g. `indices`). (:issue:`1693`, :pull:`1731`).
 
 New indicators
 ^^^^^^^^^^^^^^
@@ -27,9 +26,10 @@ Breaking changes
 * The previously deprecated functions ``xclim.sdba.processing.construct_moving_yearly_window`` and ``xclim.sdba.processing.unpack_moving_yearly_window`` have been removed. These functions have been replaced by ``xclim.core.calendar.stack_periods`` and ``xclim.core.calendar.unstack_periods``. (:pull:`1717`).
 * The previously deprecated function ``xclim.ensembles.change_significance`` has been removed. (:pull:`1737`).
 * Indicators ``snw_season_length`` and ``snd_season_length`` have been modified, see above.
-* The `hargeaves85`/`hg85` method for the ``potential_evapotranspiration`` indicator and indice has been modified for precision and consistency with recent academic literature. (:issue:`1710`, :pull:`1723`).
+* The `'hargeaves85'`/`'hg85'` method for the ``potential_evapotranspiration`` indicator and indice has been modified for precision and consistency with recent academic literature. (:issue:`1710`, :pull:`1723`).
 * The `__getitem__` method of ``xclim.core.indicator.Parameter`` instances has been removed. Accessing members of ``Parameters`` now uniquely uses dot notation. (:pull:`1721`).
 * The obsolete function wrapper for generating Indicators ``xclim.core.utils.wrapped_partial`` has been removed. (:pull:`1721`).
+* The default documentation theme has changed from `sphinx-rtd-theme` to `furo`; Several modifications to the documentation configuration and CSS overrides have been made to accommodate the changes. `furo` is now a `docs` dependency. (:issue:`1693`, :pull:`1731`).
 
 Bug fixes
 ^^^^^^^^^
@@ -41,6 +41,7 @@ Bug fixes
 * ``make_criteria`` now skips columns with NaNs across all realizations. (:pull:`1713`).
 * Fixed bug QuantileDeltaMapping adjustment not working for seasonal grouping (:issue:`1704`, :pull:`1716`).
 * The codebase has been adjusted to address several (~400) `mypy`-related errors attributable to inaccurate function call signatures and variable name shadowing. (:issue:`1719`, :pull:`1721`).
+* ``xclim.core.formatting.generate_indicator_docstring`` has been modified to ensure that the `numpy`-docstrings of all Indicators are consistent in their formatting. (:pull:`1731`).
 
 Internal changes
 ^^^^^^^^^^^^^^^^
@@ -51,6 +52,9 @@ Internal changes
 * Added the `vulture` static code analysis tool for finding dead code to the development dependency list and linters (makefile, tox and pre-commit hooks). (:pull:`1717`).
 * Added error message when using `xclim.indices.stats.dist_method` with `nnlf` and included note in docstring. (:issue:`1683`, :pull:`1714`).
 * PEP8 rule `N802` is now enabled in the `ruff` formatter. Function names should follow `Snake case <https://en.wikipedia.org/wiki/Snake_case>`_, with rare exceptions. (:pull:`1721`).
+* Linting dependencies have been updated to the latest versions and made consistent across `environment.yml`, `pyproject.toml` and `tox.ini` files. (:pull:`1717`).
+* Code styling for the documentation now uses `sas` ("light" theme) and `lightbulb` ("dark" theme) in order to ensure adequate contrast for code blocks. (:pull:`1731`).
+* Added several CSS overrides related to the HTML elements generated by `xarray` in the notebook-sourced documentation. (:pull:`1731`).
 
 v0.48.2 (2024-02-26)
 --------------------

Makefile

@@ -55,7 +55,7 @@ clean-test: ## remove test and coverage artifacts
 lint: ## check style with flake8 and black
 	black --check xclim tests
 	isort --check xclim tests
-	ruff xclim tests
+	ruff check xclim tests
 	flake8 --config=.flake8 xclim tests
 	vulture xclim tests
 	nbqa black --check docs
@@ -101,8 +101,8 @@ ifndef READTHEDOCS
 	python -m http.server 54345 --directory docs/_build/html/
 endif
 
-servedocs: docs ## compile the docs watching for changes
-	watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D .
+servedocs: autodoc-custom-index ## generate Sphinx HTML documentation, including API docs, but without indexes for for indices and indicators, and watch for changes
+	$(MAKE) -C docs livehtml
 
 release: dist ## package and upload a release
 	flit publish dist/*

README.rst

@@ -1,6 +1,6 @@
-======================================
-xclim: Climate services library |logo|
-======================================
+===============================================================
+xclim: Climate services library |logo| |logo-dark| |logo-light|
+===============================================================
 
 +----------------------------+-----------------------------------------------------+
 | Versions                   | |pypi| |conda| |versions|                           |
@@ -184,9 +184,20 @@ This package was created with Cookiecutter_ and the `audreyfeldroy/cookiecutter-
         :target: https://github.com/psf/black
         :alt: Python Black
 
-.. |logo| image:: https://raw.githubusercontent.com/Ouranosinc/xclim/main/docs/logos/xclim-logo-small.png
+.. |logo| image:: https://raw.githubusercontent.com/Ouranosinc/xclim/main/docs/logos/xclim-logo-small-light.png
         :target: https://github.com/Ouranosinc/xclim
         :alt: Xclim
+        :class: xclim-logo-small no-theme
+
+.. |logo-light| image:: https://raw.githubusercontent.com/Ouranosinc/xclim/main/docs/logos/empty.png
+        :target: https://github.com/Ouranosinc/xclim
+        :alt:
+        :class: xclim-logo-small only-light-inline
+
+.. |logo-dark| image:: https://raw.githubusercontent.com/Ouranosinc/xclim/main/docs/logos/empty.png
+        :target: https://github.com/Ouranosinc/xclim
+        :alt:
+        :class: xclim-logo-small only-dark-inline
 
 .. |pre-commit| image:: https://results.pre-commit.ci/badge/github/Ouranosinc/xclim/main.svg
         :target: https://results.pre-commit.ci/latest/github/Ouranosinc/xclim/main

docs/Makefile

@@ -2,8 +2,8 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = python -msphinx
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
 SPHINXPROJ    = xclim
 SOURCEDIR     = .
 BUILDDIR      = _build
@@ -18,3 +18,6 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+livehtml:
+	sphinx-autobuild --port 54345 --open-browser --delay 3 --re-ignore "$(BUILDDIR)|apidoc|Makefile|_dynamic/indicators.json|variables.json|__pycache__" "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/indsearch.js

@@ -26,7 +26,7 @@ let miniSearch = new MiniSearch({
 });
 
 // Populate search object with complete list of indicators
-fetch('indicators.json')
+fetch('_static/indicators.json')
   .then(data => data.json())
   .then(data => {
     indicators = Object.entries(data).map(([k, v]) => {
@@ -68,7 +68,7 @@ function makeVariableList(ind) {
         /* kv[0] is the variable name, kv[1] is the variable description. */
         /* Convert kv[1] to a string literal */
         const text = escapeHTML(kv[1]);
-        const tooltip = `<button class="indVarname" title="${text}" alt="${text}">${kv[0]}</button>`;
+        const tooltip = `<button class="indVarname" title="${text}" alt="${text}"><code>${kv[0]}</code></button>`;
         return tooltip
     }).join('');
 }

docs/_static/style.css

@@ -1,4 +1,4 @@
-@import url("theme.css");
+@import url("styles/furo.css");
 
 .wy-side-nav-search>a img.logo,
 .wy-side-nav-search .wy-dropdown>a img.logo {
@@ -37,8 +37,16 @@ td.name {
     font-weight: 500;
 }
 
-tr:nth-child(even) {
-  background-color: #dddddd;
+body div tr:nth-child(even),
+body div.rendered_html tbody tr:nth-child(even) {
+  background-color: var(--color-background-table-rows-even);
+  color: var(--color-text-table-rows-even);
+}
+
+body div tr:nth-child(odd),
+body div.rendered_html tbody tr:nth-child(odd) {
+  background-color: var(--color-background-table-rows-odd);
+  color: var(--color-text-table-rows-odd);
 }
 
 dd {
@@ -75,7 +83,8 @@ ul.simple li {
 .indElem {
  margin: 10px;
  padding: 10px;
- background-color: #ddd;
+ background-color: var(--color-indicator-background);
+ color: var(--color-indicator-text);
  border-radius: 10px;
 }
 
@@ -84,21 +93,99 @@ ul.simple li {
 }
 
 code > .indName {
-  background-color: #ccc;
+  background-color: var(--color-indicator-background);
+  color: var(--color-indicator-text);
 }
 
 .indVarname {
   border-radius: 10px;
+  background-color: var(--color-indicator-widget-background);
+  color: var(--color-indicator-widget-text);
+  border: solid 1px var(--color-indicator-widget-text);
+  margin-right: 3px;
+  margin-bottom: 3px;
+  line-height: 24px;
+  cursor: help;
 }
 
 /* Rounded corners for keyword labels: */
 .keywordlabel {
     border-radius: 10px;
     padding: 5px;
     margin: 5px;
-    background-color: #ddd;
+    background-color: var(--color-indicator-widget-background);
+    color: var(--color-indicator-widget-text);
+    border: solid 1px var(--color-indicator-widget-text);
+    line-height: 24px;
+
 }
 
 #incVirtModLbl {
     display: inline;
 }
+
+/* extend furo for inline ".only-dark" elements */
+body .only-dark-inline,
+body .only-light-inline {
+  display: none !important;
+}
+
+@media not print {
+  body[data-theme="dark"] .only-dark-inline,
+  body[data-theme="light"] .only-light-inline {
+    display: inline !important;
+  }
+  @media (prefers-color-scheme: dark) {
+    body:not([data-theme="light"]) .only-dark-inline{
+      display: inline !important;
+    }
+  }
+  @media (prefers-color-scheme: light) {
+    body:not([data-theme="dark"]) .only-light-inline{
+      display: inline !important;
+    }
+  }
+}
+
+@media print {
+  .only-light-inline{
+    display: inline !important;
+  }
+  .only-dark-inline{
+    display: none !important;
+  }
+}
+
+img.xclim-logo-small.only-dark-inline {
+    width: 91px;
+    height: 103px;
+    margin: 0;
+    padding: 0;
+    background-color: transparent;
+    background-repeat: no-repeat;
+    border-image-width: 0px;
+    border: none;
+    border-image-width: 0px;
+    background-image: url("xclim-logo-small-dark.png");
+}
+
+img.xclim-logo-small.only-light-inline {
+    width: 91px;
+    height: 103px;
+    margin: 0;
+    padding: 0;
+    background-color: transparent;
+    background-repeat: no-repeat;
+    border: none;
+    border-image-width: 0px;
+    background-image: url("xclim-logo-small-light.png");
+}
+
+img.xclim-logo-small.no-theme {
+  display: none;
+  width: 0px;
+}
+
+button.copybtn.copybtn svg {
+  stroke: var(--color-copybutton);
+}

docs/_static/xarray.css

@@ -0,0 +1,13 @@
+
+/* default xarray theme, this is taken from the injected css that xarray uses.
+However, we change it so that it updates in the body, instead of :root, so that it updates with the theme.*/
+html, body {
+  --xr-font-color0: var(--jp-content-font-color0, rgba(0, 0, 0, 1));
+  --xr-font-color2: var(--jp-content-font-color2, rgba(0, 0, 0, 0.54));
+  --xr-font-color3: var(--jp-content-font-color3, rgba(0, 0, 0, 0.38));
+  --xr-border-color: var(--jp-border-color2, #e0e0e0);
+  --xr-disabled-color: var(--jp-layout-color3, #bdbdbd);
+  --xr-background-color: var(--jp-layout-color0, white);
+  --xr-background-color-row-even: var(--jp-layout-color1, white);
+  --xr-background-color-row-odd: var(--jp-layout-color2, #eeeeee);
+}

docs/_templates/layout.html → docs/_templates/base.html

@@ -1,4 +1,4 @@
-{% extends "!layout.html" %}
+{% extends "!base.html" %}
 {% set css_files = css_files + ["_static/style.css"] %}
 
 <!-- Injection of the scripts for generating the indicators page data.
@@ -7,7 +7,7 @@
 	breaks MiniSearch if loaded first.
 -->
 
-{% block scripts %}
+{% block site_meta %}
 {% if "indicators" in sourcename %}
   <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/umd/index.min.js"></script>
   <script type="text/javascript" src="./_static/indsearch.js"></script>

docs/api.rst

@@ -2,11 +2,6 @@
 API
 ===
 
-.. contents:: Table of Contents
-   :depth: 1
-   :local:
-   :backlinks: none
-
 Indicators
 ==========