Ouranosinc · Zeitsperre · May 2, 2024 · Apr 25, 2024 · Apr 25, 2024 · Apr 25, 2024
diff --git a/.gitignore b/.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

diff --git a/.pre-commit-config.yaml b/.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

diff --git a/Makefile b/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/*

diff --git a/README.rst b/README.rst
@@ -1,6 +1,6 @@
-======================================
-xclim: Climate services library |logo|
-======================================
+===============================================================
+xclim: Climate services library |logo| |logo-dark| |logo-light|
+===============================================================
 
 +----------------------------+-----------------------------------------------------+
 | Versions                   | |pypi| |conda| |versions|                           |
@@ -187,6 +187,17 @@ This package was created with Cookiecutter_ and the `audreyfeldroy/cookiecutter-
 .. |logo| image:: https://raw.githubusercontent.com/Ouranosinc/xclim/main/docs/logos/xclim-logo-small.png
         :target: https://github.com/Ouranosinc/xclim
         :alt: Xclim
+        :class: xclim-logo-small no-theme
+
+.. |logo-light| image:: logos/empty.png
+        :target: https://github.com/Ouranosinc/xclim
+        :alt:
+        :class: xclim-logo-small only-light-inline
+
+.. |logo-dark| image:: 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

diff --git a/docs/Makefile b/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 2 --re-ignore "$(BUILDDIR)|apidoc|_dynamic/indicators.json|variables.json|__pycache__" "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/indsearch.js b/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]) => {

diff --git a/docs/_static/style.css b/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 {
@@ -38,7 +38,7 @@ td.name {
 }
 
 tr:nth-child(even) {
-  background-color: #dddddd;
+  background-color: var(--color-table-border);
 }
 
 dd {
@@ -102,3 +102,64 @@ code > .indName {
 #incVirtModLbl {
     display: inline;
 }
+
+/* extend furo for inline ".only-dark" elements */
+body .only-dark-inline,
+body .only-light-inline {
+  display: none !important;
+}
+
+body[data-theme="dark"] .only-dark-inline,
+body[data-theme="light"] .only-light-inline {
+    display: inline !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;
+    }
+  }
+}
+
+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-content-foreground);
+}
diff --git a/docs/_templates/layout.html → docs/_templates/base.html b/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/minisearch@6.3.0/dist/umd/index.min.js"></script>
   <script type="text/javascript" src="./_static/indsearch.js"></script>

diff --git a/docs/api.rst b/docs/api.rst
@@ -2,11 +2,6 @@
 API
 ===
 
-.. contents:: Table of Contents
-   :depth: 1
-   :local:
-   :backlinks: none
-
 Indicators
 ==========
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -65,7 +65,8 @@
 
 # Dump indicators to json. The json is added to the html output (html_extra_path)
 # It is read by _static/indsearch.js to populate the table in indicators.rst
-with open("indicators.json", "w") as f:
+os.makedirs("_dynamic", exist_ok=True)
+with open("_dynamic/indicators.json", "w") as f:
     json.dump(indicators, f)
 
 
@@ -104,7 +105,6 @@
     "sphinx_codeautolink",
     "sphinx_copybutton",
     "sphinx_mdinclude",
-    "sphinx_rtd_theme",
 ]
 
 autodoc_typehints = "description"
@@ -272,8 +272,9 @@ class XCStyle(AlphaStyle):
     "**.ipynb_checkpoints",
 ]
 
-# The name of the Pygments (syntax highlighting) style to use.
+# The name of the Pygments (syntax highlighting) style to use for light and dark themes.
 pygments_style = "sphinx"
+pygments_dark_style = "monokai"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
@@ -283,31 +284,50 @@ class XCStyle(AlphaStyle):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_title = "XClim Official Documentation"
-html_short_title = "XClim"
-
-html_theme = "sphinx_rtd_theme"
-
-html_extra_path = ["indicators.json", "variables.json"]
-
-# Theme options are theme-specific and customize the look and feel of a
-# theme further.  For a list of options available for each theme, see the
-# documentation.
-#
-html_theme_options = {"logo_only": True, "style_external_links": True}
+html_title = "xclim Official Documentation"
+html_short_title = "xclim"
+
+html_theme = "furo"
+html_extra_path = ["variables.json"]
+
+# Theme options are theme-specific and customize the look and feel of a theme further.
+# For a list of options available for each theme, see the documentation.
+html_theme_options = {
+    "light_logo": "xclim-logo-light.png",
+    "dark_logo": "xclim-logo-dark.png",
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/Ouranosinc/xclim",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,  # noqa: E501
+            "class": "",
+        },
+    ],
+}
 
 html_sidebars = {
-    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
+    "**": [
+        "sidebar/scroll-start.html",
+        "sidebar/brand.html",
+        "sidebar/search.html",
+        "sidebar/navigation.html",
+        "sidebar/ethical-ads.html",
+        "sidebar/scroll-end.html",
+    ]
 }
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = "logos/xclim-logo.png"
+# html_logo = "logos/xclim-logo.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+html_static_path = ["_dynamic", "logos", "_static"]
 
 # -- Options for HTMLHelp output ---------------------------------------
 
@@ -317,7 +337,7 @@ class XCStyle(AlphaStyle):
 # -- Options for LaTeX output ------------------------------------------
 
 latex_engine = "pdflatex"
-latex_logo = "logos/xclim-logo.png"
+latex_logo = "logos/xclim-logo-light.png"
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
@@ -379,4 +399,4 @@ class XCStyle(AlphaStyle):
 
 
 def setup(app):
-    app.add_css_file("_static/style.css")
+    app.add_css_file("style.css")
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -114,9 +114,9 @@ From sources
 ------------
 
 .. warning::
-    For Python3.11+ users: Many of the required scientific libraries do not currently have wheels that support the latest
-    python. In order to ensure that installation of xclim doesn't fail, we suggest installing the `Cython` module
-    before installing xclim in order to compile necessary libraries from source packages.
+    While `xclim` strives to be compatible with latest releases and development versions of upstream libraries, many of the required base libraries (`numpy`, `scipy`, `numba`, etc.) may lag by several months before supporting the latest minor releases of Python.
+
+    In order to ensure that installation of `xclim` doesn't fail, we suggest installing the `Cython` module before installing `xclim` in order to compile necessary libraries from their source packages, if required.
 
 The sources for xclim can be downloaded from the `Github repo`_.
 

diff --git a/docs/logos/empty.png b/docs/logos/empty.png
diff --git a/docs/logos/xclim-logo-dark.png b/docs/logos/xclim-logo-dark.png
diff --git a/docs/logos/xclim-logo.png → docs/logos/xclim-logo-light.png b/docs/logos/xclim-logo.png → docs/logos/xclim-logo-light.png
diff --git a/docs/logos/xclim-logo-small-dark.png b/docs/logos/xclim-logo-small-dark.png
diff --git a/docs/logos/xclim-logo-small.png → docs/logos/xclim-logo-small-light.png b/docs/logos/xclim-logo-small.png → docs/logos/xclim-logo-small-light.png
diff --git a/environment.yml b/environment.yml
@@ -29,7 +29,7 @@ dependencies:
   - flox
   - lmoments3  # Required for some Jupyter notebooks
   # Testing and development dependencies
-  - black ==24.1.1
+  - black ==24.4.1
   - blackdoc ==0.3.9
   - bump-my-version >=0.17.1
   - cairosvg
@@ -40,6 +40,7 @@ dependencies:
   - flake8
   - flake8-rst-docstrings
   - flit
+  - furo >=2023.9.10
   - h5netcdf
   - ipykernel
   - ipython
@@ -62,17 +63,18 @@ dependencies:
   - pytest-cov
   - pytest-socket
   - pytest-xdist >=3.2
-  - ruff >=0.2.0
+  - ruff >=0.3.0
   - sphinx
+  - sphinx-autobuild >=2024.4.16
   - sphinx-autodoc-typehints
   - sphinx-codeautolink
   - sphinx-copybutton
   - sphinx-mdinclude
-  - sphinx-rtd-theme >=1.0
   - sphinxcontrib-bibtex
   - tokenize-rt
   - tox >=4.0
 #  - tox-conda  # Will be added when a tox@v4.0+ compatible plugin is released.
+  - vulture # ==2.11  # The conda-forge version is out of date.
   - xdoctest
   - yamllint
   - pip