From 5d0d0382f3fbdbb1be3fff950ee31b485a0dcb1e Mon Sep 17 00:00:00 2001 From: Bill Little Date: Sun, 24 Jan 2021 23:54:57 +0000 Subject: [PATCH 1/3] docs for nox --- .../contributing_running_tests.rst | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/docs/iris/src/developers_guide/contributing_running_tests.rst b/docs/iris/src/developers_guide/contributing_running_tests.rst index 3ac0ed905e..4a2079d29d 100644 --- a/docs/iris/src/developers_guide/contributing_running_tests.rst +++ b/docs/iris/src/developers_guide/contributing_running_tests.rst @@ -91,3 +91,73 @@ due to an experimental dependency not being present. All Python decorators that skip tests will be defined in ``lib/iris/tests/__init__.py`` with a function name with a prefix of ``skip_``. + + +Using Nox for Testing +===================== + +Iris has adopted the use of the `nox`_ tool for automated testing on `cirrus-ci`_, +and also locally on the command-line for developers. + +`nox`_ is similar to `tox`_, but instead leverages the expressiveness and power of a Python +configuration file rather than an `.ini` file. Additionally, `nox`_ also supports `conda`_ as +a testing environment backend, as well as `virtualenv`_. + +Where is Nox Used? +------------------ + +Iris uses `nox`_ as a convenience to fully automate the process of executing the Iris tests, building +the documentation, linting the code-base and ensuring the coding style conforms to `black`_. + +You can perform all of these tasks manually yourself, however the onus is on you to first ensure +that all of the required package dependencies are installed and available in the testing environment. + +`Nox`_ has been configured to automatically do this for you, and provides a means to easily replicate +the remote testing behaviour of `cirrus-ci`_ locally. + + +Installing Nox +-------------- + +We recommend installing `nox`_ using `conda`_:: + + conda create -n nox -c conda-forge nox + conda activate nox + +The `nox`_ package is also available on PyPI, however `nox`_ has been configured to use the `conda`_ +backend for Iris, so an installation of `conda`_ must always be available. + + +Testing with Nox +---------------- + +The `nox`_ configuration file `noxfile.py` is available in the root ``iris`` project directory, and +defines all the `nox`_ sessions (i.e., tasks) that may be performed. `nox`_ must always be executed +from the ``iris`` root directory. + +To list the configured `nox`_ sessions for Iris:: + + nox --list + +To run the Iris tests for all configured versions of Python:: + + nox --session tests + +To build the Iris documentation specifically for Python 3.7:: + + nox --session doctest-3.7 + +To run all the Iris `nox`_ sessions:: + + nox + +For further `nox`_ command-line options:: + + nox --help + + +.. _black: https://black.readthedocs.io/en/stable/ +.. _nox: https://nox.thea.codes/en/latest/ +.. _tox: https://tox.readthedocs.io/en/latest/ +.. _virtualenv: https://virtualenv.pypa.io/en/latest/ +.. _PyPI: https://pypi.org/project/nox/ From c1bb5e75f95d0fba3a42762733c72a661642aaec Mon Sep 17 00:00:00 2001 From: Bill Little Date: Mon, 25 Jan 2021 10:19:25 +0000 Subject: [PATCH 2/3] add titles, notices and additional detail --- .../contributing_running_tests.rst | 36 ++++++++++++++----- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/docs/iris/src/developers_guide/contributing_running_tests.rst b/docs/iris/src/developers_guide/contributing_running_tests.rst index 4a2079d29d..b09f9c1924 100644 --- a/docs/iris/src/developers_guide/contributing_running_tests.rst +++ b/docs/iris/src/developers_guide/contributing_running_tests.rst @@ -5,6 +5,11 @@ Running the Tests ***************** +Using setuptools for Testing Iris +================================= + +.. warning:: The `setuptools`_ ``test`` command was deprecated in `v41.5.0`_. See :ref:`using nox`. + A prerequisite of running the tests is to have the Python environment setup. For more information on this see :ref:`installing_from_source`. @@ -93,27 +98,38 @@ due to an experimental dependency not being present. ``skip_``. -Using Nox for Testing -===================== +.. _using nox: -Iris has adopted the use of the `nox`_ tool for automated testing on `cirrus-ci`_, +Using Nox for Testing Iris +========================== + +Iris has adopted the use of the `nox`_ tool for automated testing on `cirrus-ci`_ and also locally on the command-line for developers. `nox`_ is similar to `tox`_, but instead leverages the expressiveness and power of a Python -configuration file rather than an `.ini` file. Additionally, `nox`_ also supports `conda`_ as -a testing environment backend, as well as `virtualenv`_. +configuration file rather than an `.ini` style file. As with `tox`_, `nox`_ can use `virtualenv`_ +to create isolated Python environments, but in addition also supports `conda`_ as a testing +environment backend. + Where is Nox Used? ------------------ -Iris uses `nox`_ as a convenience to fully automate the process of executing the Iris tests, building -the documentation, linting the code-base and ensuring the coding style conforms to `black`_. +Iris uses `nox`_ as a convenience to fully automate the process of executing the Iris tests, but also +automates the process of: + +* building the documentation and executing the doc-tests +* building the documentation gallery +* running the documentation URL link check +* linting the code-base +* ensuring the code-base style conforms to the `black`_ standard + You can perform all of these tasks manually yourself, however the onus is on you to first ensure that all of the required package dependencies are installed and available in the testing environment. `Nox`_ has been configured to automatically do this for you, and provides a means to easily replicate -the remote testing behaviour of `cirrus-ci`_ locally. +the remote testing behaviour of `cirrus-ci`_ locally for the developer. Installing Nox @@ -155,9 +171,13 @@ For further `nox`_ command-line options:: nox --help +.. note:: `nox`_ will cache its testing environments in the `.nox` root ``iris`` project directory. + .. _black: https://black.readthedocs.io/en/stable/ .. _nox: https://nox.thea.codes/en/latest/ +.. _setuptools: https://setuptools.readthedocs.io/en/latest/ .. _tox: https://tox.readthedocs.io/en/latest/ .. _virtualenv: https://virtualenv.pypa.io/en/latest/ .. _PyPI: https://pypi.org/project/nox/ +.. _v41.5.0: https://setuptools.readthedocs.io/en/latest/history.html#v41-5-0 From d02ef32eb8504deee51349cb45b0962aafe92750 Mon Sep 17 00:00:00 2001 From: Bill Little Date: Mon, 25 Jan 2021 11:06:36 +0000 Subject: [PATCH 3/3] review actions --- .../src/developers_guide/contributing_running_tests.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/iris/src/developers_guide/contributing_running_tests.rst b/docs/iris/src/developers_guide/contributing_running_tests.rst index b09f9c1924..99ea4e831c 100644 --- a/docs/iris/src/developers_guide/contributing_running_tests.rst +++ b/docs/iris/src/developers_guide/contributing_running_tests.rst @@ -135,11 +135,15 @@ the remote testing behaviour of `cirrus-ci`_ locally for the developer. Installing Nox -------------- -We recommend installing `nox`_ using `conda`_:: +We recommend installing `nox`_ using `conda`_. To install `nox`_ in a separate `conda`_ environment:: conda create -n nox -c conda-forge nox conda activate nox +To install `nox`_ in an existing active `conda`_ environment:: + + conda install -c conda-forge nox + The `nox`_ package is also available on PyPI, however `nox`_ has been configured to use the `conda`_ backend for Iris, so an installation of `conda`_ must always be available.