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/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 diff --git a/docs/iris/src/installing.rst b/docs/iris/src/installing.rst index faa46afa50..9b8a647f0d 100644 --- a/docs/iris/src/installing.rst +++ b/docs/iris/src/installing.rst @@ -1,6 +1,97 @@ .. _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 (users) +------------------------------ + +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 (devs) +----------------------------- + +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 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 + 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/scitools/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.