diff --git a/CHANGES.rst b/CHANGES.rst index 741a29299..fe21033d9 100644 --- a/CHANGES.rst +++ b/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 `_ 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 ^^^^^^^^^ diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index e56b96ed5..d3762e58c 100644 --- a/CONTRIBUTING.rst +++ b/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 * diff --git a/tox.ini b/tox.ini index 155efb572..82bf7aed5 100644 --- a/tox.ini +++ b/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 =