From 3f8b64acb83b4209f281bbde2af285e49a3ce859 Mon Sep 17 00:00:00 2001 From: Tremain Knight <2108488+tkknight@users.noreply.github.com> Date: Fri, 4 Sep 2020 19:13:53 +0100 Subject: [PATCH 1/4] Updated the Iris install instructions --- INSTALL | 96 ------------------------------------ docs/iris/src/installing.rst | 91 +++++++++++++++++++++++++++++++++- 2 files changed, 89 insertions(+), 98 deletions(-) delete mode 100644 INSTALL diff --git a/INSTALL b/INSTALL deleted file mode 100644 index cf4c4d1bae..0000000000 --- a/INSTALL +++ /dev/null @@ -1,96 +0,0 @@ -You can either install Iris using the conda package manager or from source. - - -Installing using conda ----------------------- - -Iris is available using conda for the following platforms: - - * Linux 64-bit, - * Mac OSX 64-bit, and - * Windows 32-bit and 64-bit. - -To install Iris using conda, you must first download and install conda, -for example from http://conda.pydata.org/miniconda.html. - -Once conda is installed, you can install Iris using conda on any platform with -the following command:: - - conda install -c conda-forge iris - -If you wish to run any of the code in the gallery you will also -need the Iris sample data. This can also be installed using conda:: - - conda install -c conda-forge iris-sample-data - -Further documentation on using conda and the features it provides can be found -at http://conda.pydata.org/docs/intro.html. - - -Installing from source ----------------------- - -The latest Iris source release is available from -https://github.com/SciTools/iris. - -Iris makes use of a range of other libraries and python modules. These -dependencies must be in place before you can successfully install -Iris. Once you have satisfied the requirements detailed in the -``requirements`` directory, go to the root of Iris' and run:: - - pip install . - - -In-place build - an alternative for developers -============================================== -We are very keen to encourage contributions to Iris. For this type of -development activity an in-place build can be useful. Once you've cloned -the Iris git repository you can perform an in-place build with:: - - pip install -e . - - -Generating conda requirements -''''''''''''''''''''''''''''' - -Requirements for Iris are stored in the ``requirements`` directory in the root of the source repository. -It is possible to generate a requirements file suitable for use with conda:: - - python requirements/gen_conda_requirements.py > conda_requirements.txt - -This may then be installed with:: - - conda create -n my_iris_env --file conda_requirements.txt - -Alternatively, a full requirements file that includes all optional dependencies can be produced with:: - - python requirements/gen_conda_requirements.py --groups all > conda_requirements.txt - - -Running the tests -''''''''''''''''' - -In order to run the tests, you will need to use the `test` and `docs` groups (we include the `docs` group so that you can run the pull request tests locally). -Hence the commands change to:: - - python requirements/gen_conda_requirements.py --groups test docs > conda_requirements.txt - conda create -n my_iris_env -c conda-forge --file conda_requirements.txt - conda activate my_iris_env # or whatever other name you gave it - pip install -e . - -The tests can then be run with:: - - python setup.py test - - -Custom site configuration -========================= -The default site configuration values can be overridden by creating the file -``iris/etc/site.cfg``. For example, the following snippet can be used to -specify a non-standard location for your dot executable:: - - [System] - dot_path = /usr/bin/dot - -An example configuration file is available in ``iris/etc/site.cfg.template``. -See :py:func:`iris.config` for further configuration options. diff --git a/docs/iris/src/installing.rst b/docs/iris/src/installing.rst index faa46afa50..adaad60d77 100644 --- a/docs/iris/src/installing.rst +++ b/docs/iris/src/installing.rst @@ -1,6 +1,93 @@ .. _installing_iris: Installing Iris -*************** +=============== -.. include:: ../../../INSTALL +Iris is available using conda for the following platforms: + +* Linux 64-bit, +* Mac OSX 64-bit, and +* Windows 64-bit. + +.. note:: Iris currently supports and is tested against **Python 3.6** and + **Python 3.7**. + + +.. _installing_using_conda: + +Installing using conda +---------------------- + +To install Iris using conda, you must first download and install conda, +for example from https://docs.conda.io/en/latest/miniconda.html. + +Once conda is installed, you can install Iris using conda with the following +command:: + + conda install -c conda-forge iris + +If you wish to run any of the code in the gallery you will also +need the Iris sample data. This can also be installed using conda:: + + conda install -c conda-forge iris-sample-data + +Further documentation on using conda and the features it provides can be found +at https://conda.io/en/latest/index.html. + + +.. _installing_from_source: + +Installing from source +---------------------- + +The latest Iris source release is available from +https://github.com/SciTools/iris. + +For instructions on how to obtain the Iris project source from GitHub see +:ref:`forking` and :ref:`set-up-fork` for instructions. + +Once conda is installed, you can install Iris using conda and then activate +it. The example commands below assume you are in the root directory of your +local copy of Iris:: + + conda env create --file=requirements/ci/iris.yml + conda activate iris-dev + +The ``requirements/ci/iris.yml`` file used to create the conda environment +includes all the relevant dependencies that you need to code, test, and build +the documentation. If you wish to minimise your install you can remove any +unwanted packages from file file. + +.. note:: The ``requirements/ci/iris.yml`` file will always use the latest + tested Python version available. For all Python versions that + are supported view the contents of the `requirements/ci`_ directory. + +.. _requirements/ci: https://github.com/tkknight/iris/tree/master/requirements/ci + +Finally you need to run the command to configure your shell environment +to find your local Iris code:: + + python setup.py develop + + +Running the tests +----------------- + +To ensure your setup is configured correctly you can run the test suite using +the command:: + + python setup.py test + + +Custom site configuration +------------------------- + +The default site configuration values can be overridden by creating the file +``iris/etc/site.cfg``. For example, the following snippet can be used to +specify a non-standard location for your dot executable:: + + [System] + dot_path = /usr/bin/dot + +An example configuration file is available in ``iris/etc/site.cfg.template``. +See :py:func:`iris.config` for further configuration options. From d6bbaf140346e5a072ca87f4e5dfc5d1bb00f59e Mon Sep 17 00:00:00 2001 From: Tremain Knight <2108488+tkknight@users.noreply.github.com> Date: Sat, 5 Sep 2020 23:35:58 +0100 Subject: [PATCH 2/4] Renamed section titles and reworded paragraph. --- docs/iris/src/installing.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/iris/src/installing.rst b/docs/iris/src/installing.rst index adaad60d77..793ad324c0 100644 --- a/docs/iris/src/installing.rst +++ b/docs/iris/src/installing.rst @@ -15,8 +15,8 @@ Iris is available using conda for the following platforms: .. _installing_using_conda: -Installing using conda ----------------------- +Installing using conda (users) +------------------------------ To install Iris using conda, you must first download and install conda, for example from https://docs.conda.io/en/latest/miniconda.html. @@ -37,8 +37,8 @@ at https://conda.io/en/latest/index.html. .. _installing_from_source: -Installing from source ----------------------- +Installing from source (devs) +----------------------------- The latest Iris source release is available from https://github.com/SciTools/iris. @@ -54,9 +54,9 @@ local copy of Iris:: conda activate iris-dev The ``requirements/ci/iris.yml`` file used to create the conda environment -includes all the relevant dependencies that you need to code, test, and build -the documentation. If you wish to minimise your install you can remove any -unwanted packages from file file. +includes **all** the relevant dependencies that you need to **code**, **test**, +and **build** the documentation. If you wish to minimise your install you can +remove any unwanted packages from the requirements file. .. note:: The ``requirements/ci/iris.yml`` file will always use the latest tested Python version available. For all Python versions that From 9721f73d0c73cee14c93ab742e441fb284008566 Mon Sep 17 00:00:00 2001 From: Tremain Knight <2108488+tkknight@users.noreply.github.com> Date: Sun, 6 Sep 2020 16:35:41 +0100 Subject: [PATCH 3/4] Improved paragraph wording --- docs/iris/src/installing.rst | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/iris/src/installing.rst b/docs/iris/src/installing.rst index 793ad324c0..9b8a647f0d 100644 --- a/docs/iris/src/installing.rst +++ b/docs/iris/src/installing.rst @@ -53,16 +53,20 @@ local copy of Iris:: conda env create --file=requirements/ci/iris.yml conda activate iris-dev -The ``requirements/ci/iris.yml`` file used to create the conda environment -includes **all** the relevant dependencies that you need to **code**, **test**, -and **build** the documentation. If you wish to minimise your install you can -remove any unwanted packages from the requirements file. +The ``requirements/ci/iris.yml`` file defines the Iris development conda +environment *name* and all the relevant *top level* `conda-forge` package +dependencies that you need to **code**, **test**, and **build** the +documentation. If you wish to minimise the environment footprint, simply +remove any unwanted packages from the requirements file e.g., if you don't +intend to run the Iris tests locally or build the documentation, then remove +all the packages from the `testing` and `documentation` sections. .. note:: The ``requirements/ci/iris.yml`` file will always use the latest - tested Python version available. For all Python versions that - are supported view the contents of the `requirements/ci`_ directory. + Iris tested Python version available. For all Python versions that + are supported and tested against by Iris, view the contents of + the `requirements/ci`_ directory. -.. _requirements/ci: https://github.com/tkknight/iris/tree/master/requirements/ci +.. _requirements/ci: https://github.com/scitools/iris/tree/master/requirements/ci Finally you need to run the command to configure your shell environment to find your local Iris code:: From 7b2feb24d88e5745f02a5ecbf53a511df1996cba Mon Sep 17 00:00:00 2001 From: Tremain Knight <2108488+tkknight@users.noreply.github.com> Date: Tue, 8 Sep 2020 10:23:55 +0100 Subject: [PATCH 4/4] Removed references to INSTALL --- MANIFEST.in | 2 +- README.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/MANIFEST.in b/MANIFEST.in index efd0534863..6f6ec445a2 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,5 +1,5 @@ # Top-level files -include CHANGES COPYING COPYING.LESSER INSTALL +include CHANGES COPYING COPYING.LESSER # Files from setup.py package_data that are not automatically added to source distributions recursive-include lib/iris/tests/results *.cml *.cdl *.txt *.xml *.json diff --git a/README.md b/README.md index 469db4619a..6adf27d85b 100644 --- a/README.md +++ b/README.md @@ -103,7 +103,8 @@ The easiest way to install Iris is with [conda](https://conda.io/miniconda.html) conda install -c conda-forge iris Detailed instructions, including information on installing from source, -are available in [INSTALL](INSTALL). +are available in the +[documentation](https://scitools-iris.readthedocs.io/en/latest/installing.html). # Get in touch