Add note in the docs about SKIP_NOTEBOOKS. (#1476)

CHANGES.rst

@@ -4,12 +4,13 @@ Changelog
 
 v0.46.0 (unreleased)
 --------------------
-Contributors to this version: Éric Dupuis (:user:`coxipi`), Trevor James Smith (:user:`Zeitsperre`).
+Contributors to this version: Éric Dupuis (:user:`coxipi`), Trevor James Smith (:user:`Zeitsperre`), David Huard (:user:`huard`).
 
 New features and enhancements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 * `xclim` now has a dedicated console command for prefetching testing data from `xclim-testdata` with branch options (e.g.: `$ xclim prefetch_testing_data --branch some_development_branch`). This command can be used to download the testing data to a local cache, which can then be used to run the testing suite without internet access or in "offline" mode. For more information, see the contributing documentation section for `Updating Testing Data`. (:issue:`1468`, :pull:`1473`).
 * The testing suite now offers a means of running tests in "offline" mode (using `pytest-socket <https://github.com/miketheman/pytest-socket>`_ to block external connections). This requires a local copy of `xclim-testdata` to be present in the user's home cache directory and for certain `pytest` options and markers to be set when invoked. For more information, see the contributing documentation section for `Running Tests in Offline Mode`. (:issue:`1468`, :pull:`1473`).
+* The `SKIP_NOTEBOOKS` flag to speed up docs builds is now documented. See the contributing documentation section `Get Started!` for details. (:issue:`1470`, :pull:`1476`).
 
 Bug fixes
 ^^^^^^^^^

CONTRIBUTING.rst

@@ -185,6 +185,12 @@ Ready to contribute? Here's how to set up `xclim` for local development.
     # or, alternatively, to build the docs directly
     $ make docs
 
+.. note::
+
+    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.
+
 8. After clearing the previous checks, commit your changes and push your branch to GitHub::
 
     $ git add *

tox.ini

@@ -46,7 +46,6 @@ commands_post =
 [testenv:docs]
 description = Build the documentation with makefile under {basepython}
 setenv =
-    !notebooks: SKIP_NOTEBOOKS = 1
     PYTHONPATH = {toxinidir}
     READTHEDOCS = 1
 commands_pre =
@@ -101,6 +100,7 @@ passenv =
     COVERALLS_*
     GITHUB_*
     LD_LIBRARY_PATH
+    SKIP_NOTEBOOKS
     XCLIM_*
 extras = dev
 deps =