diff --git a/docs/environments/ess.yml b/docs/environments/ess.yml new file mode 100644 index 000000000..913cbc5a7 --- /dev/null +++ b/docs/environments/ess.yml @@ -0,0 +1,17 @@ +name: ess + +channels: + - conda-forge + - scipp + - nodefaults + +dependencies: + - ess + - astropy + - matplotlib + - tifffile + - jupyterlab + - jupyterlab_widgets + - pythreejs + - scipy + - ipympl diff --git a/docs/getting-started/installation.rst b/docs/getting-started/installation.rst new file mode 100644 index 000000000..6751649de --- /dev/null +++ b/docs/getting-started/installation.rst @@ -0,0 +1,61 @@ +.. _installation: + +Installation +============ + +The easiest way to install ``ess`` is using `conda `_. +Packages from `Anaconda Cloud `_ are available for Linux, macOS, and Windows. +It is recommended to create an environment rather than installing individual packages. + +With the provided environment file +---------------------------------- + +1. Download :download:`ess.yml <../environments/ess.yml>`. +2. In a terminal run: + + .. code-block:: sh + + conda activate + conda env create -f ess.yml + conda activate ess + jupyter lab + +The ``conda activate`` ensures that you are in your ``base`` environment. +This will take a few minutes. +Above, replace ``ess.yml`` with the path to the download location you used to download the environment. +Open the link printed by Jupyter in a browser if it does not open automatically. + +If you have previously installed ``ess`` with conda we nevertheless recommend creating a fresh environment rather than trying to ``conda update``. +You may want to remove your old environment first, e.g., + +.. code-block:: sh + + conda activate + conda env remove -n ess + +and then proceed as per instructions above. +The ``conda activate`` ensures that you are in your ``base`` environment. + +Without the provided environment file +------------------------------------- + +To create a new conda environment with ``ess``: + +.. code-block:: sh + + conda create -n env_with_ess -c conda-forge -c scipp ess + +To add ``ess`` to an existing conda environment: + +.. code-block:: sh + + conda install -c conda-forge -c scipp ess + +.. note:: + Installing ``ess`` on Windows requires ``Microsoft Visual Studio 2019 C++ Runtime`` installed. + Visit `this page `_ for the up to date version of the library. + +After installation the modules ``ess``, ``scippneutron``, and ``scipp`` can be imported in Python. +Note that only the bare essential dependencies are installed. + +To update or remove ``ess`` use `conda update `_ and `conda remove `_. diff --git a/docs/index.rst b/docs/index.rst index 11900feb0..bc0b92508 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,6 +24,12 @@ This involves a "filtering" process, since scope and contribution guidelines are Documentation ============= +.. toctree:: + :maxdepth: 3 + :caption: Getting started + + getting-started/installation + .. toctree:: :maxdepth: 3 :caption: Instruments