diff --git a/docs/contributing/development/index.rst b/docs/contributing/development/index.rst index 3ad0131b325..41f6d264785 100644 --- a/docs/contributing/development/index.rst +++ b/docs/contributing/development/index.rst @@ -1,3 +1,5 @@ +.. _developer_guidelines: + ****************** Developer Workflow ****************** diff --git a/docs/installation.rst b/docs/installation.rst index cc3fd79ecd6..f98bd15d80d 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -4,84 +4,99 @@ Installation ************ -Before installing TARDIS, please check its :ref:`requirements -`. We provide :ref:`instructions ` for installing TARDIS using -Anaconda. Once you have installed TARDIS, check out the "Input/Output" section (in sidebar) for instructions -regarding how to perform simple TARDIS calculations. -.. _requirements_label: +.. warning:: + + - TARDIS is only supported on macOS and GNU/Linux. Windows users can run TARDIS + from our official Docker image (*coming soon*), `WSL `_ + or a Virtual Machine. + - TARDIS packages and dependencies are distributed only through the `conda `_ + package management system, therefore installation requires `Anaconda `_ + or `Miniconda `_ + to be installed on your system. -.. note:: - - TARDIS is only compatible with Python >=3.6 - - TARDIS only supports MacOS and Linux. - - We strongly recommend installing TARDIS within an Anaconda environment and to always use the latest GitHub development version. +Install with lockfiles +====================== +Conda lockfiles are platform-specific dependency files that produce repeteable environments. +These files are generated on every new release. We strongly recommend installing TARDIS using +this method by following the steps described below. -Requirements -============ +1. Download the latest lockfile for your operating system from our + `releases section `_, or run + the following command while replacing ``{platform}`` with ``linux`` or ``osx`` as appropriate. -You can see a list of all the requirements of TARDIS in the `environment definition file `_. + :: -TARDIS is using Astropy's excellent installation helpers and thus uses similar -instructions to Astropy. + $ wget -q https://github.com/tardis-sn/tardis/releases/latest/download/conda-{platform}-64.lock -.. _anaconda_inst_label: +2. Create and activate the ``tardis`` environment. -Installing TARDIS with Anaconda -=============================== + :: -We highly recommend using the `Anaconda `_ Python environment to install TARDIS (or -any other scientific packages for that matter). Anaconda has the advantage of -being an isolated environment that can be set to be the default one, but by no -means will mess with your other environments. It will also work on computers -where ``root``-rights are not available. Use these `instructions -`_ to install Anaconda on your -machine. The next step is to create an environment for TARDIS that contains all -of the necessary packages (this ensures that TARDIS requirements won't clash -with any other Python installs on disc): + $ conda create --name tardis --file conda-{platform}-64.lock + $ conda activate tardis -First, download the `environment definition file `_ from: -:: +3. a. Non-developers can install the latest release from ``conda-forge`` with the ``--no-deps`` flag, - https://raw.githubusercontent.com/tardis-sn/tardis/master/tardis_env3.yml + :: -To create the environment, change to the directory that you downloaded the environment definition file and run: -:: + $ conda install tardis-sn --channel conda-forge --no-deps - conda env create -f tardis_env3.yml + or trying the most recent, unreleased changes from upstream. -Then to activate this environment simply do: -:: + :: - source activate tardis + $ pip install git+https://github.com/tardis-sn/tardis.git@master -or the new method: -:: + b. Instead, developers should `fork the repository `_, configure + GitHub to `work with SSH keys `_, + set up the `upstream remote `_, + and install the package in development mode. - conda activate tardis + :: + + $ git clone git@github.com:/tardis.git + $ cd tardis + $ git remote add upstream git@github.com:tardis-sn/tardis.git + $ git fetch upstream + $ git checkout upstream/master + $ pip install -e . + + .. note:: + + The complete developer guidelines can be found :ref:`here `. -and after you are done with TARDIS you can deactivate: -:: - conda deactivate +4. Once finished working, you can deactivate your environment. -One does not need to recreate the environment, but simply activate it every time -TARDIS is used. + :: -For TARDIS development purposes please follow the steps :ref:`here ` -until the step to install TARDIS in the development mode -``python setup.py develop``. Development guidelines for -TARDIS can be found `here `_. + $ conda deactivate + +You are ready! From now on, just activate the ``tardis`` environment before working with the +TARDIS package. + + +Install from package +==================== + +It's also possible to install TARDIS by pulling the `conda-forge package `_ +into a clean environment. However, we still encourage using lockfiles to ensure +reproducibility of scientific results. -To install TARDIS, it is recommended to first clone our repository and -then install TARDIS, as follows: :: - git clone https://github.com/tardis-sn/tardis.git - cd tardis - python setup.py install + $ conda create --name tardis-forge tardis-sn --channel conda-forge +Environment update +================== + +To update the environment after a new release, download the latest lockfile and run ``conda update``. + +:: + $ conda update --name tardis --file conda-{platform}-64.lock \ No newline at end of file