Merge pull request #1403 from OceanParcels/installation_on_docs

Adding installation instructions to documentation

README.md

@@ -22,10 +22,10 @@ The manuscript detailing the performance of Parcels v2.4 is available at [Comput
 
 ### Further information
 
-See [oceanparcels.org](http://oceanparcels.org/) for further information about [installing](http://oceanparcels.org/#installing) and [running](http://oceanparcels.org/#tutorials) the Parcels code, as well as extended [documentation](https://parcels.readthedocs.io) of the methods and classes.
+See [oceanparcels.org](http://oceanparcels.org/) for further information about [installing](https://docs.oceanparcels.org/en/latest/installation.html) and [running](https://docs.oceanparcels.org/en/latest/documentation.html) the Parcels code, as well as extended [documentation](https://docs.oceanparcels.org/en/latest/reference.html) of the methods and classes.
 
 
-### Launch Parcels Tutorials on mybinder.org
+### Launch Parcels Tutorials on [mybinder.org](https://mybinder.org/v2/gh/OceanParcels/parcels/master?labpath=docs%2Fexamples%2Fparcels_tutorial.ipynb)
 
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/OceanParcels/parcels/master?labpath=docs%2Fexamples%2Fparcels_tutorial.ipynb)
 [![unit-tests](https://github.com/OceanParcels/parcels/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/OceanParcels/parcels/actions/workflows/unit-tests.yml)

docs/contributing.md

@@ -5,21 +5,12 @@ Even if you don't want to contribute directly to the codebase, getting involved
 
 This document outlines some guidelines for contributing to the parcels codebase. If you have any questions or suggestions for how we can improve this document, please let us know.
 
-## Getting Started
-
-To get started contributing to parcels, you'll need to do a few things:
-
-1. [Fork our repository](https://github.com/OceanParcels/parcels/fork) on GitHub.
 
-2. Clone your fork of the repository to your local machine, and `cd` into your project folder.
-
-3. Install [Anaconda](https://www.anaconda.com/download) (if you haven't already).
-
-4. Install the development Anaconda environment by installing from the environment file corresponding to your OS (`environment_py3_linux.yml`, `environment_py3_osx.yml` or `environment_py3_win.yml`) then activate it. E.g. on Linux: `conda env create -f environment_py3_linux.yml` then `conda activate py3_parcels`.
+## Getting Started
 
-5. Install your local copy of parcels in editable mode by running `pip install -e .`.
+To get started contributing to parcels, you'll need to install the developer version of Parcels following [our installation instructions](installation.rst#installation-for-developers). This will install the latest version of Parcels from the `master` branch of the repository.
 
-6. **Optional:** Setup `pre-commit` hooks by running `pre-commit install`. This ensures that code is formatted correctly before you commit it.
+**Optional:** Setup `pre-commit` hooks by running `pre-commit install`. This ensures that code is formatted correctly before you commit it.
 
 
 ## Making Changes

docs/index.rst

@@ -2,14 +2,15 @@ Parcels documentation
 ===================================
 
 Welcome to the documentation of Parcels.
-Here you'll find tutorials, documentation, and the API reference for Parcels. You can browse the documentation for older versions by using the version switcher in the left sidebar.
+Here you'll find `installation instructions <installation.rst>`_, `tutorials and documentation <documentation.rst>`_, and the `API reference <reference.rst>`_ for Parcels. You can browse the documentation for older versions by using the version switcher in the left sidebar.
 
 .. toctree::
    :maxdepth: 2
    :hidden:
 
    Home <self>
-   Tutorials and documentation <documentation>
+   Installation <installation>
+   Tutorials & Documentation <documentation>
    API reference <reference>
    Contributing <contributing>
    OceanParcels website <https://oceanparcels.org/>

docs/installation.rst

@@ -0,0 +1,72 @@
+Basic installation
+==================
+
+The simplest way to install the Parcels code is to use Anaconda and the `Parcels conda-forge package <https://anaconda.org/conda-forge/parcels>`_ with the latest release of Parcels. This package will automatically install all the requirements for a fully functional installation of Parcels. This is the “batteries-included” solution probably suitable for most users.
+
+If you want to install the latest development version of Parcels and work with features that have not yet been officially released, you can follow the instructions for a `developer installation <#installation-for-developers>`_.
+
+The steps below are the installation instructions for Linux, macOS and Windows.
+
+**Step 1:** Install Anaconda's Miniconda following the steps at https://conda.io/docs/user-guide/install/, making sure to select the Python-3 version. If you're on Linux /macOS, the following assumes that you installed Miniconda to your home directory.
+
+**Step 2:** Start a terminal (Linux / macOS) or the Anaconda prompt (Windows). Activate the ``base`` environment of your Miniconda and create an environment containing Parcels, all its essential dependencies, and the nice-to-have cartopy and jupyter packages:
+
+.. code-block:: bash
+
+    conda activate base
+    conda create -n parcels -c conda-forge parcels cartopy jupyter
+
+.. note::
+
+    For some of the examples, ``pytest`` also needs to be installed. This can be quickly done with ``conda install -n parcels pytest`` which installs ``pytest`` directly into the newly created ``parcels`` environment.
+
+**Step 3:** Activate the newly created Parcels environment:
+
+.. code-block:: bash
+
+    conda activate parcels
+
+**Step 4:** Download `a zipped copy <https://docs.oceanparcels.org/en/latest/_downloads/307c382eb1813dc691e8a80d6c0098f7/parcels_tutorials.zip>`_ of the Parcels tutorials and examples and unzip it.
+
+**Step 5:** Go to the unzipped folder and run one of the examples to validate that you have a working Parcels setup:
+
+.. code-block:: bash
+
+  python example_peninsula.py --fieldset 100 100
+
+.. note::
+  If you are on macOS and get a compilation error, you may need to accept the Apple xcode license ``xcode-select --install``. If this does not solve the compilation error, you may want to try running ``export CC=gcc``. If the compilation error remains, you may want to check `this solution <https://stackoverflow.com/a/58323411/5172570>`_.
+
+*Optionally:* if you want to run all the examples and tutorials, start Jupyter and open the tutorial notebooks:
+
+.. code-block:: bash
+
+  jupyter notebook
+
+
+.. note::
+
+  The next time you start a terminal and want to work with Parcels, activate the environment with:
+
+  .. code-block:: bash
+
+    conda activate parcels
+
+
+Installation for developers
+===========================
+
+If you would prefer to have a development installation of Parcels (i.e., where the code can be actively editted), you can do so by cloning the Parcels repo, installing dependencies using the environment file (which includes Python, netCDF tooling, a C compiler, and various Python packages), and then installing Parcels in an editable mode such that changes to the cloned code can be tested during development.
+
+.. code-block:: bash
+
+  git clone https://github.com/OceanParcels/parcels.git
+  cd parcels
+  conda env create -f environment_py3_<OS>.yml  # where <OS> is either linux, osx or win
+
+Then activate the environment and install Parcels in editable mode:
+
+.. code-block:: bash
+
+  conda activate parcels
+  pip install --no-build-isolation --no-deps -e .

docs/reference/code_generation.rst

@@ -2,14 +2,14 @@ C Code Generation
 =================
 
 parcels.compilation.codegenerator module
---------------------------
+----------------------------------------
 
 .. automodule:: parcels.compilation.codegenerator
     :members:
     :show-inheritance: yes
 
 parcels.compilation.codecompiler module
---------------------------
+---------------------------------------
 
 .. automodule:: parcels.compilation.codecompiler
     :members:

environment_py3_linux.yml

@@ -1,4 +1,4 @@
-name: py3_parcels
+name: parcels
 channels:
   - conda-forge
 dependencies:

environment_py3_osx.yml

@@ -1,4 +1,4 @@
-name: py3_parcels
+name: parcels
 channels:
   - conda-forge
 dependencies:

environment_py3_win.yml

@@ -1,4 +1,4 @@
-name: py3_parcels
+name: parcels
 channels:
   - conda-forge
 dependencies: