@@ -12,8 +12,8 @@ There are two options for running the tests:
1212 the tests or use ``python `` interactively to investigate any issues. See
1313 :ref: `test manual env `.
1414
15- * Use ``nox ``. This will automatically generate an environment and run test
16- sessions consistent with our GitHub continuous integration. See :ref: `using nox `.
15+ * Use ``tox ``. This will automatically generate an environment and run test
16+ sessions consistent with our GitHub continuous integration. See :ref: `using tox `.
1717
1818.. _test manual env :
1919
@@ -101,97 +101,84 @@ using the commands ``python test_mapping.py -h`` or
101101``python test_mapping.py --help ``.
102102
103103.. tip :: A useful command line option to use is ``-d``. This will display
104- matplotlib _ figures as the tests are run. For example::
104+ ` matplotlib_ ` figures as the tests are run. For example::
105105
106106 python test_mapping.py -d
107107
108- .. _using nox :
108+ .. _using tox :
109109
110- Using Nox for Testing Iris
110+ Using tox for Testing Iris
111111==========================
112112
113- The `nox `_ tool has for adopted for automated testing on `Iris GitHub Actions `_
113+ The `tox `_ tool has been adopted for automated testing on `Iris GitHub Actions `_
114114and also locally on the command-line for developers.
115115
116- `nox `_ is similar to `tox `_, but instead leverages the expressiveness and power of a Python
117- configuration file rather than an `.ini ` style file. As with `tox `_, `nox `_ can use `virtualenv `_
118- to create isolated Python environments, but in addition also supports `conda `_ as a testing
119- environment backend.
116+ `tox `_ uses `virtualenv `_ to create isolated Python environments and is
117+ configured within a tox.ini file.
120118
121-
122- Where is Nox Used?
119+ Where is tox Used?
123120------------------
124121
125- Iris uses `nox `_ as a convenience to fully automate the process of executing the Iris tests, but also
126- automates the process of:
122+ Iris uses `tox `_ as a convenience to fully automate the process of:
127123
128- * building the documentation and executing the doc-tests
129- * building the documentation gallery
124+ * executing the Iris tests,
125+ * building the documentation,
126+ * executing the doc-tests,
127+ * executing the gallery tests, and
130128* running the documentation URL link check
131129
132- You can perform all of these tasks manually yourself, however the onus is on you to first ensure
133- that all of the required package dependencies are installed and available in the testing environment.
130+ You can perform all of these tasks manually yourself, however the onus is on you
131+ to first ensure that all of the required package dependencies are installed and
132+ available in the testing environment.
134133
135- `Nox `_ has been configured to automatically do this for you, and provides a means to easily replicate
136- the remote testing behaviour of `Iris GitHub Actions `_ locally for the developer.
134+ `tox `_ has been configured to automatically do this for you, and provides a
135+ means to easily replicate the remote testing behaviour of `Iris GitHub Actions `_
136+ locally for the developer.
137137
138138
139- Installing Nox
139+ Installing tox
140140--------------
141141
142- We recommend installing `nox `_ using `conda `_. To install `nox `_ in a separate `conda `_ environment::
142+ We recommend installing `tox `_ using `conda `_. To install `tox `_ in a separate
143+ `conda `_ environment::
143144
144- conda create -n nox -c conda-forge nox
145- conda activate nox
145+ conda create -n tox -c conda-forge tox
146+ conda activate tox
146147
147- To install `nox `_ in an existing active `conda `_ environment::
148+ To install `tox `_ in an existing active `conda `_ environment::
148149
149- conda install -c conda-forge nox
150+ conda install -c conda-forge tox
150151
151- The `nox `_ package is also available on PyPI, however `nox `_ has been configured to use the `conda `_
152- backend for Iris, so an installation of `conda `_ must always be available.
152+ The `tox `_ package is also available on PyPI, however `tox `_ has been configured
153+ to use `conda `_ to create the testing environments and so an installation of
154+ `conda `_ must always be available.
153155
154156
155- Testing with Nox
157+ Testing with tox
156158----------------
157159
158- The `nox `_ configuration file `noxfile.py ` is available in the root ``iris `` project directory, and
159- defines all the `nox `_ sessions (i.e., tasks) that may be performed. `nox `_ must always be executed
160- from the ``iris `` root directory.
161-
162- To list the configured `nox `_ sessions for Iris::
163-
164- nox --list
165-
166- To run the Iris tests for all configured versions of Python::
160+ The `tox `_ configuration file `tox.ini ` is available in the root ``iris ``
161+ project directory, and defines all the `tox `_ test environments (i.e., tasks)
162+ that may be performed. `tox `_ must always be executed from the ``iris `` root
163+ directory.
167164
168- nox --session tests
165+ To list the configured ` tox `_ sessions for Iris::
169166
170- To build the Iris documentation specifically for Python 3.7::
167+ tox --listenvs-all
171168
172- nox --session doctest-3.7
169+ To run the Iris tests for Python 3.10::
173170
174- To run all the Iris ` nox `_ sessions::
171+ tox -e py310-tests
175172
176- nox
173+ To build the Iris documentation specifically for Python 3.10::
177174
178- For further `nox `_ command-line options::
179-
180- nox --help
181-
182- .. tip ::
183- For `nox `_ sessions that use the `conda `_ backend, you can use the ``-v `` or ``--verbose ``
184- flag to display the `nox `_ `conda `_ environment package details and environment info.
185- For example::
175+ tox -e py310-docs
186176
187- nox --session tests -- --verbose
177+ For further ` tox `_ command-line options::
188178
179+ tox --help
189180
190- .. note :: `nox `_ will cache its testing environments in the `.nox ` root ``iris`` project directory.
181+ .. note :: `tox `_ will cache its testing environments in the `.tox ` root ``iris`` project directory.
191182
192183
193- .. _setuptools : https://setuptools.readthedocs.io/en/latest/
194- .. _tox : https://tox.readthedocs.io/en/latest/
195- .. _virtualenv : https://virtualenv.pypa.io/en/latest/
196- .. _PyPI : https://pypi.org/project/nox/
197- .. _v41.5.0 : https://setuptools.readthedocs.io/en/latest/history.html#v41-5-0
184+ .. _virtualenv : https://virtualenv.pypa.io/en/latest/
0 commit comments