Regroup/expand installation instructions (#5)

* detail user and dev installation separately, move tutorial section

PET packages can be installed directly from GitHub, installation can highlight
this possibility for advanced users, removing the need to clone the repository
if one just want to incorporate PET in their project.

* move tutorial installation instructions to main README

This should make it more straightforward for a new user to find the
installation instructions.

* make windows note as a warning

Author: jennan

README.md

@@ -11,60 +11,94 @@
 > to change in the next few months.
 >
 
-# New User Information
+# Getting Started
 
-Guidelines for new users still need to be developed. For those looking to get started, follow the installation instructions below in this README, and then head to the tutorial sub-package to get going.
+Guidelines for new users still need to be developed.
+For new users, we recommend following the instructions in the [Tutorials](#tutorials) section of this README.
+Installation instructions are intended for users already familiar with the project.
 
-When this repository is ready for wider use, the intention is to release PyEarthTools on PyPI and conda-forge.
+# Installation
+
+## Repository Layout
 
-# Repository Layout
+This is a so-called monorepo. `PyEarthTools` comprises multiple, modular packages within a shared namespace that inter-operate in order to provide the overall functionality of the framework. It is not necessary to install all of them, and it is envisioned that many users are likely to want only some parts of the framework. As such, each sub-package is a fully independent Python package, with its own requirements and its own installation process. Each of these sub-packages lies in the [`packages`](packages/) subdirectory.
 
-This is a so-called monorepo. PyEarthTools comprises multiple, modular packages within a shared namespace that inter-operate in order to provide the overall functionality of the framework. It is not necessary to install all of them, and it is envisioned that many users are likely to want only some parts of the framework. As such, each sub-package is a fully independent Python package, with its own requirements and its own installation process.
+## User installation
 
-Each of these sub-packages lies in the 'packages' subdirectory. Developers of `PyEarthTools` will most likely want to check out the entire monorepo and work on changesets which may span sub-packages. Each sub-package is versioned separately, so bugfixes or updates in a single sub-package can be performed independently without requiring a new release of the entire ecosystem. 
+Each of PyEarthTools package can be installed separately using `pip`, directly from GitHub.
+For example, to install the `pyearthtools-utils` package, use:
 
-For simplicity, the instructions here explain how to check out the whole codebase and install everything for a developer context. 
+```
+pip install git+https://github.com/ACCESS-Community-Hub/PyEarthTools.git#subdirectory=packages/utils
+```
 
+Other available packages are `pyearthtools-data`, `pyearthtools-pipeline` and `pyearthtools-training`, that can be installed as follows:
 
-# Installation
+```
+pip install git+https://github.com/ACCESS-Community-Hub/PyEarthTools.git#subdirectory=packages/data
+pip install git+https://github.com/ACCESS-Community-Hub/PyEarthTools.git#subdirectory=packages/pipeline
+pip install git+https://github.com/ACCESS-Community-Hub/PyEarthTools.git#subdirectory=packages/training
+```
+
+> [!NOTE]
+> When this repository is ready for wider use, the intention is to release `PyEarthTools` on PyPI and conda-forge.
 
-First clone the repository using the `develop` branch:
+## Developer installation
+
+Developers of `PyEarthTools` will most likely want to check out the entire monorepo and work on changesets which may span sub-packages. Each sub-package is versioned separately, so bugfixes or updates in a single sub-package can be performed independently without requiring a new release of the entire ecosystem. 
+
+First clone this repository:
 
 ```
-git clone [email protected]:ACCESS-Community-Hub/PyEarthTools.git
-cd pyearthtools
+git clone https://github.com/ACCESS-Community-Hub/PyEarthTools.git
 ```
 
-Then create a Python virtual environment:
+and install all packages in "editable" mode with
 
 ```
-python3 -m venv venv
-venv/bin/activate
+cd PyEarthTools
+pip install -r requirements-dev.txt
 ```
 
-or a Conda environment to install all dependencies:
+> [!WARNING]
+> We do recommend using a Python virtual environment or a Conda environment when developing, to isolate this installation from the rest of your system.
+
+
+# Tutorials
+
+For new users, we recommend running the tutorials first, to see `PyEarthTools` in action and get familiar with it.
+
+The following instructions assume that you have access to [Conda](https://docs.conda.io/projects/conda/en/latest/index.html) on your system.
+
+> [!WARNING]
+> These instructions have been tested on Linux and macOS. We have not tested them on **Windows**.
+> We welcome any contribution to improve this situation 🙂.
+
+First clone this repository and switch to the tutorials folder:
 
 ```
-conda create -p ./venv -y python=3.11
-conda activate ./venv
+git clone https://github.com/ACCESS-Community-Hub/PyEarthTools.git
+cd PyEarthTools/packages/tutorial
 ```
 
-And install all dependencies via pip:
+Then create a Conda environment to install all dependencies:
 
 ```
-pip install -r requirements-dev.txt
+conda env create -f environment.yml -p ./venv
 ```
 
-You can run some of the tests to check that your installation worked:
+Next, to run the example [notebooks](PyEarthTools/packages/tutorial/nbook/), you can either
+
+- start a JupyterLab instance
 
 ```
-pytest packages/data/tests/
+conda activate ./venv
+jupyter lab
 ```
 
-To run example [notebooks from the tutorial package](packages/tutorial/nbook), you may need to also install a Jupyter kernel for your environment:
+- or install a Jupyter kernel to use in a pre-existing JupyterLab installation
 
 ```
-# from the activate virtual or conda environment
-pip install ipykernel
-python -m ipykernel install --user --name pyearthtools
+conda activate ./venv
+python -m ipykernel install --user --name PET-tutorial
 ```

packages/tutorial/README.md

@@ -1,30 +1,5 @@
 # PyEarthTools tutorials
 
-First clone this repository:
+Tutorial material to get started with `PyEarthTools`.
 
-```
-git clone https://github.com/ACCESS-Community-Hub/PyEarthTools.git
-cd PyEarthTools/packages/tutorial
-```
-
-Then create a Conda environment to install all dependencies:
-
-```
-conda env create -f environment.yml -p ./venv
-```
-
-To run the example [notebooks](nbook/), you can either
-
-- start a JupyterLab instance
-
-```
-conda activate ./venv
-jupyter lab
-```
-
-- or install a Jupyter kernel to use in a pre-existing JupyterLab installation
-
-```
-conda activate ./venv
-python -m ipykernel install --user --name PET-tutorial
-```
+See the main [README](../../README.md#tutorials) for instructions.

requirements-dev.txt

@@ -1,4 +1,5 @@
 -e packages/utils
 -e packages/data
--e packages/tutorial/
+-e packages/training
 -e packages/pipeline
+-e packages/tutorial