From 14de0aa1dbd9019d15c3893586a25e586dc94eea Mon Sep 17 00:00:00 2001
From: David Huard <huard.david@ouranos.ca>
Date: Tue, 12 Sep 2023 09:37:36 -0400
Subject: [PATCH 1/4] Add note in the docs about SKIP_NOTEBOOKS.

---
 CHANGES.rst      | 4 ++++
 CONTRIBUTING.rst | 2 ++
 2 files changed, 6 insertions(+)

diff --git a/CHANGES.rst b/CHANGES.rst
index c6d99980d..2b701ea54 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -6,6 +6,10 @@ v0.46.0
 --------------------
 Contributors to this version: Éric Dupuis (:user:`coxipi`).
 
+New features and enhancements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* Document `SKIP_NOTEBOOKS` flag to speed up documentation builds. (:issue:`1470`).
+
 Internal changes
 ^^^^^^^^^^^^^^^^
 * Change "degK" to "K" used to design Kelvin units. (:pull:`1475`).
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 33f030a88..75c3d32a6 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -165,6 +165,8 @@ Ready to contribute? Here's how to set up `xclim` for local development.
     # or, alternatively, to build the docs directly
     $ make docs
 
+Note that running the notebooks can take some time. Set the environment variable `SKIP_NOTEBOOKS` to 1 to skip this step.
+
 8. After clearing the previous checks, commit your changes and push your branch to GitHub::
 
     $ git add *

From f99760f05c2b615ed6787b544e1c2f7bbc09a940 Mon Sep 17 00:00:00 2001
From: Zeitsperre <10819524+Zeitsperre@users.noreply.github.com>
Date: Tue, 12 Sep 2023 19:06:03 -0400
Subject: [PATCH 2/4] more elaborate explanation on how to skipe notebooks,
 allow `SKIP_NOTEBOOKS` to be passed to tox environment

---
 CONTRIBUTING.rst | 6 +++++-
 tox.ini          | 2 +-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 75c3d32a6..32f88a8af 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -165,7 +165,11 @@ Ready to contribute? Here's how to set up `xclim` for local development.
     # or, alternatively, to build the docs directly
     $ make docs
 
-Note that running the notebooks can take some time. Set the environment variable `SKIP_NOTEBOOKS` to 1 to skip this step.
+.. note::
+
+    When building the documentation, the defaults behaviour is to run all notebooks. Due to their complexity, this is a very computationally demanding task.
+
+    In order to speed up documentation builds, setting a value for the environment variable "`SKIP_NOTEBOOKS`" (e.g. "`$ export SKIP_NOTEBOOKS=1`") will prevent the notebooks from being evaluated on all subsequent "`$ tox -e docs`" or "`$ make docs`" invocations.
 
 8. After clearing the previous checks, commit your changes and push your branch to GitHub::
 
diff --git a/tox.ini b/tox.ini
index dd8c18c2b..a08ddbc3b 100644
--- a/tox.ini
+++ b/tox.ini
@@ -42,7 +42,6 @@ commands_post =
 [testenv:docs]
 description = Build the documentation with makefile under {basepython}
 setenv =
-    !notebooks: SKIP_NOTEBOOKS = 1
     PYTHONPATH = {toxinidir}
     READTHEDOCS = 1
 commands_pre =
@@ -88,6 +87,7 @@ passenv =
     COVERALLS_*
     GITHUB_*
     LD_LIBRARY_PATH
+    SKIP_NOTEBOOKS
     XCLIM_*
 extras = dev
 deps =

From aa7a8563eb5e3bdaccf9355832531b1985b6c28f Mon Sep 17 00:00:00 2001
From: Zeitsperre <10819524+Zeitsperre@users.noreply.github.com>
Date: Tue, 12 Sep 2023 19:09:02 -0400
Subject: [PATCH 3/4] update CHANGES.rst

---
 CHANGES.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 2b701ea54..6b299bce5 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -2,13 +2,13 @@
 Changelog
 =========
 
-v0.46.0
+v0.46.0 (unreleased)
 --------------------
-Contributors to this version: Éric Dupuis (:user:`coxipi`).
+Contributors to this version: Éric Dupuis (:user:`coxipi`), David Huard (:user:`huard`).
 
 New features and enhancements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-* Document `SKIP_NOTEBOOKS` flag to speed up documentation builds. (:issue:`1470`).
+* Document `SKIP_NOTEBOOKS` flag to speed up documentation builds. (:issue:`1470`, :pull:`1476`).
 
 Internal changes
 ^^^^^^^^^^^^^^^^

From d3463e9c4402e52a51e2a60831094b63c52a9655 Mon Sep 17 00:00:00 2001
From: Zeitsperre <10819524+Zeitsperre@users.noreply.github.com>
Date: Tue, 12 Sep 2023 19:19:52 -0400
Subject: [PATCH 4/4] explain what mechanisms are at work and when to run the
 notebooks

---
 CONTRIBUTING.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 32f88a8af..412ab9663 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -167,7 +167,7 @@ Ready to contribute? Here's how to set up `xclim` for local development.
 
 .. note::
 
-    When building the documentation, the defaults behaviour is to run all notebooks. Due to their complexity, this is a very computationally demanding task.
+    When building the documentation, the default behaviour is to evaluate notebooks ('`nbsphinx_execute = "auto"`'), rather than simply parse the content ('`nbsphinx_execute = "never"`'). Due to their complexity, this is a very computationally demanding task and should only be performed when necessary (i.e.: when the notebooks have been modified).
 
     In order to speed up documentation builds, setting a value for the environment variable "`SKIP_NOTEBOOKS`" (e.g. "`$ export SKIP_NOTEBOOKS=1`") will prevent the notebooks from being evaluated on all subsequent "`$ tox -e docs`" or "`$ make docs`" invocations.