Streamline installation update

.github/workflows/python-app.yml

@@ -27,7 +27,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -r requirements-dev.txt
+        pip install -r requirements.txt
     - name: Test with pytest
       run: |
         # editable is necessary as pytest will run against the installed

README.md

@@ -18,14 +18,29 @@ Tutorial Gallery: [available here](https://pyearthtools.readthedocs.io/en/latest
 
 **Here is the quickest way to install the complete framework and get started:**
 
-From within a suitable [virtual environment](https://pyearthtools.readthedocs.io/en/latest/installation.html#virtual-environments), run the following commands:
+We strongly recommend using either a Conda or Python [virtual environment](https://pyearthtools.readthedocs.io/en/latest/installation.html#virtual-environments).
+
+Run the following commands to install PyEarthTools in a Conda environment:
+```shell
+git clone git@github.com:ACCESS-Community-Hub/PyEarthTools.git
+conda create -y -p ./venv python graphviz
+conda activate ./venv
+pip install -r requirements.txt
+cd notebooks
+jupyter lab
 ```
+
+Alternatively, run the following commands to install PyEarthTools in a Python virtual environment:
+```shell
 git clone git@github.com:ACCESS-Community-Hub/PyEarthTools.git
-pip install -r requirements-dev.txt
-conda install graphviz
+python3 -m venv ./venv
+source venv/bin/activate
+pip install -r requirements.txt
 cd notebooks
 jupyter lab
 ```
+> [!TIP]
+> (Optional) Install [Graphviz](https://graphviz.org/download/) (not installable via pip) to display pipelines.
 
 PyEarthTools comprises multiple sub-packages which may be installed and used separately. See the [installation guide](https://pyearthtools.readthedocs.io/en/latest/installation.html) for more details.
 

docs/conf.py

@@ -30,11 +30,14 @@
     "sphinx.ext.napoleon",
     "nbsphinx",
     "sphinx_gallery.load_style",
+    "sphinx_design",
+    "sphinx_togglebutton",
 ]
 source_suffix = [".rst", ".md"]
 
 myst_enable_extensions = [
     "substitution",
+    "colon_fence",
 ]
 
 templates_path = ["_templates"]

docs/index.md

@@ -30,14 +30,36 @@ Tutorial Gallery: [available here](./notebooks/Gallery)
 
 **Here is the quickest way to install the complete framework and get started:**
 
-From within a suitable [virtual environment](installation.md#virtual-environments), run the following commands:
+We strongly recommend using either a Conda or Python [virtual environment](installation.md#virtual-environments).
+
+:::::{tab-set}
+::::{tab-item} Conda environment
+Run the following commands to install PyEarthTools in a Conda environment:
+```shell
+git clone git@github.com:ACCESS-Community-Hub/PyEarthTools.git
+conda create -y -p ./venv python graphviz
+conda activate ./venv
+pip install -r requirements.txt
+cd notebooks
+jupyter lab
 ```
+::::
+::::{tab-item} Python virtual environment
+Run the following commands to install PyEarthTools in a Python virtual environment:
+```shell
 git clone git@github.com:ACCESS-Community-Hub/PyEarthTools.git
-pip install -r requirements-dev.txt
-conda install graphviz
+python3 -m venv ./venv
+source venv/bin/activate
+pip install -r requirements.txt
 cd notebooks
 jupyter lab
 ```
+:::{admonition} Optional dependencies
+:class: tip
+Install [Graphviz](https://graphviz.org/download/) (not installable via pip) to display pipelines.
+:::
+::::
+:::::
 
 PyEarthTools comprises multiple sub-packages which may be installed and used separately. See the [installation guide](installation.md) for more details.
 

docs/installation.md

@@ -2,88 +2,57 @@
 
 This page describes different ways to install PyEathTools depending on intended usage:
 
-- run tutorials content (recommended for new users),
+- users or developers at [NCI](https://nci.org.au/),
+- install all PyEarthTools packages and tutorials (recommended for new users),
 - install PyEarthTools packages as dependencies in your Python project,
 - install PyEarthTools in developer mode in order to contribute.
 
 These installation instructions have been tested on Linux, maxOS and Windows. If you encounter any difficulties, please [raise an issue](https://github.com/ACCESS-Community-Hub/PyEarthTools/issues).
 
-## Virtual Environments
-
-Users installing PyEarthTools for themselves (such as on their own workstation or laptop) are recommended to use a virtual environment.
-
-Virtual environments are isolated, dedicated copies of Python, which are separate from the version of Python which may be present and used by other software or your operating system. Using a virtual environment avoids the need for `root` or `Administrator` access, and also lowers the risk of corrupting the system if there are any problems with the installation. Industry standard practice for software development is to use virtual environments in this way.
-
-We recommend using `conda` to create a virtual environment.
-
-You can also use `virtualenv` (also referred to as `pipenv` and `venv`) to create a virtual environment. However, if you use `virtualenv` you will most likely want to manually install `graphviz`. While there is a package called `graphviz` in pip, it only supplies Python wrappers around the core package which must be installed separately. Note, `graphviz` is used for the display of pipelines, but is not core to PyEarthTools functionality, so choosing not to install `graphviz` should not result in unhandled exceptions. Additionally, if you wish to build your own copy of the documentation locally you will also need to manually install `pandoc`.  
-
-Users in shared computing environments (as is common in HPC and other research facilities) may or may not be able to use virtual environments easily, regardless of the choice between `conda` and `virtualenv`, and you may need to use or set up a `modules` environment.  
-
-## Creating a Virtual Environment 
-
-**We recommend using `conda` to create a virtual environment.**
-
-Here is a command to create and activate a new virtual environment with *conda*:
-```py
-conda create --name <my-env> python
-conda activate <my-env>
-```
-
-Here is a command to create and activate a new virtual environment with *conda*, into a specified directory (often required when on shared computing facilities):
-```py
-conda create -p <path_to_environment> python
-conda activate -p <path_to_environment>
-```
-
-You can also use `virtualenv` to create a virtual environment, but please see the [virtual environments](#virtual-environments) section above for information about dependencies you may then wish to install manually.
-
-Here is a command to create and activate a new virtual environment with *venv*:
-```py
-python -m venv <path_to_environment>
-source <path_to_environment>/bin/activate
-```
-
-These approaches will all create a new virtual environment, with the Python interpreter installed, but no additional packages yet.
-
 ## Using or Developing PyEarthTools at NCI
 
 Many of the users of PyEarthTools work on the NCI supercomputing environment. Users here should request access to project code `dk92`. The modules environment `/g/data/dk92/apps/Modules/modulefiles` can then be specified, and the module `pet/2025.05` can be used (noting this module name will change with each new update). This will make the most recent update of PyEarthTools available. 
 
 For developers of PyEarthTools at NCI, this is the recommended approach, not a virtual environment. Users can then use `pip install -e` to check out the latest code from the repository, and Python will install the development packages into a userspace install directory.
 
-
 ## Installation of PyEarthTools (including tutorials)
 
-This section details how to install PyEarthTools to be able run notebooks from the [](notebooks/Gallery.ipynb). It assumes that users want to run PyEarthTools but don't wish to change its core code.
+This section details how to install PyEarthTools to be able run notebooks from the [](notebooks/Gallery.ipynb). This installation procedure uses a Conda environment (see the corresponding [section](#virtual-environments) for more information about virtual environments).
 
 First, make sure to have [Git](https://git-scm.com/) and [Conda](https://conda-forge.org/download/) installed on your system.
 
 Then, clone the PyEarthTools repository:
 
-```
+```shell
 git clone https://github.com/ACCESS-Community-Hub/PyEarthTools.git
 cd PyEarthTools
 ```
 
-and create a Conda environment to install tutorials dependencies:
+Create a Conda environment including Python and Graphviz, and activate it:
 
-```
-conda env create -f tutorials.yml -p ./venv
+```shell
+conda create -y -p ./venv python graphviz
+conda activate ./venv
 ```
 
-You can start a JupyterLab instance to run the example notebooks:
+Next, install PyEarthTools and all its dependencies:
 
+```shell
+pip install -r requirements.txt
 ```
-conda run -p ./venv --no-capture-output jupyter-lab notebooks/
+
+Finally, start a JupyterLab instance to run the example notebooks:
+
+```shell
+jupyter-lab notebooks/
 ```
 
 ````{Note}
 Alternatively, you can install a Jupyter kernel to run notebooks in a pre-existing JupyterLab installation:
 
-```
-conda run -p ./venv --no-capture-output \
-    python -m ipykernel install --user --name PET-tutorial
+```shell
+# after activating the Conda environment
+python -m ipykernel install --user --name PET-tutorial
 ```
 
 See the [IPython documentation](https://ipython.readthedocs.io/en/stable/install/kernel_install.html) for additional information regarding the IPython kernel installation.
@@ -98,15 +67,15 @@ It is not necessary to install all of them, and it is envisioned that many users
 Each PyEarthTools sub-package can be installed separately using `pip`, directly from GitHub.
 For example, to install the `utils` sub-package, use:
 
-```
+```shell
 pip install "pyearthtools[utils] @ git+https://github.com/ACCESS-Community-Hub/PyEarthTools.git"
 ```
 
 Other available sub-packages are `data`, `pipeline`, `training`, `tutorial` and `zoo`.
 
 To install all PyEarthTools packages, including all their optional dependencies, use:
 
-```
+```shell
 pip install "pyearthtools[all] @ git+https://github.com/ACCESS-Community-Hub/PyEarthTools.git"
 ```
 
@@ -124,20 +93,74 @@ Each sub-package is versioned separately, so bugfixes or updates in a single sub
 
 First clone the PyEarthTools repository:
 
-```
+```shell
 git clone https://github.com/ACCESS-Community-Hub/PyEarthTools.git
 cd PyEarthTools
 ```
 
-and install all packages in "editable" mode with
-
+Create a [Virtual Environment](#virtual-environments) and activate it.
+::::{tab-set}
+:::{tab-item} Conda environment
+```shell
+conda create -y -p ./venv python graphviz
+conda activate ./venv
 ```
-pip install -r requirements-dev.txt
+:::
+:::{tab-item} Python virtual environment
+```shell
+python3 -m venv ./venv
+source venv/bin/activate
 ```
+:::
+::::
 
-or install a specific package `<package-name>` in editable mode using
+Then install all packages in "editable" mode with
 
+```shell
+pip install -r requirements.txt
 ```
+
+or install a specific package `<package-name>` in editable mode using
+
+```shell
 pip install -e packages/<package-name>
 ```
 
+## Virtual Environments
+
+Users installing PyEarthTools for themselves (such as on their own workstation or laptop) are recommended to use a virtual environment.
+
+Virtual environments are isolated, dedicated copies of Python, which are separate from the version of Python which may be present and used by other software or your operating system. Using a virtual environment avoids the need for `root` or `Administrator` access, and also lowers the risk of corrupting the system if there are any problems with the installation. Industry standard practice for software development is to use virtual environments in this way.
+
+We recommend using `conda` to create a virtual environment.
+
+You can also use `virtualenv` (also referred to as `pipenv` and `venv`) to create a virtual environment. However, if you use `virtualenv` you will most likely want to manually install `graphviz`. While there is a package called `graphviz` in pip, it only supplies Python wrappers around the core package which must be installed separately. Note, `graphviz` is used for the display of pipelines, but is not core to PyEarthTools functionality, so choosing not to install `graphviz` should not result in unhandled exceptions. Additionally, if you wish to build your own copy of the documentation locally you will also need to manually install `pandoc`.
+
+Users in shared computing environments (as is common in HPC and other research facilities) may or may not be able to use virtual environments easily, regardless of the choice between `conda` and `virtualenv`, and you may need to use or set up a `modules` environment.
+
+:::{admonition} Creating a Virtual Environment
+
+**We recommend using `conda` to create a virtual environment.**
+
+Here is a command to create and activate a new virtual environment with *conda*:
+```shell
+conda create --name <my-env> python
+conda activate <my-env>
+```
+
+Here is a command to create and activate a new virtual environment with *conda*, into a specified directory (often required when on shared computing facilities):
+```shell
+conda create -p <path_to_environment> python
+conda activate -p <path_to_environment>
+```
+
+You can also use `virtualenv` to create a virtual environment, but please see the [virtual environments](#virtual-environments) section above for information about dependencies you may then wish to install manually.
+
+Here is a command to create and activate a new virtual environment with *venv*:
+```shell
+python -m venv <path_to_environment>
+source <path_to_environment>/bin/activate
+```
+
+These approaches will all create a new virtual environment, with the Python interpreter installed, but no additional packages yet.
+:::

docs/newuser.md

@@ -4,15 +4,36 @@ Welcome new user! This document will continue to be updated based on user feedba
 
 ## Installation
 
-From within a suitable [virtual environment](installation.md#virtual-environments), run the following commands:
+We strongly recommend using either a Conda or Python [virtual environment](installation.md#virtual-environments).
 
+:::::{tab-set}
+::::{tab-item} Conda environment
+Run the following commands to install PyEarthTools in a Conda environment:
+```shell
+git clone git@github.com:ACCESS-Community-Hub/PyEarthTools.git
+conda create -y -p ./venv python graphviz
+conda activate ./venv
+pip install -r requirements.txt
+cd notebooks
+jupyter lab
 ```
+::::
+::::{tab-item} Python virtual environment
+Run the following commands to install PyEarthTools in a Python virtual environment:
+```shell
 git clone git@github.com:ACCESS-Community-Hub/PyEarthTools.git
-pip install -r requirements-dev.txt
-conda install graphviz
+python3 -m venv ./venv
+source venv/bin/activate
+pip install -r requirements.txt
 cd notebooks
 jupyter lab
 ```
+:::{admonition} Optional dependencies
+:class: tip
+Install [Graphviz](https://graphviz.org/download/) (not installable via pip) to display pipelines.
+:::
+::::
+:::::
 
 For other installation options, please refer to the [installation guide](installation.md).
 

pyproject.toml

@@ -73,7 +73,9 @@ docs = [
   "scipy",
   "bottleneck",
   "nbsphinx",
-  "sphinx_gallery"
+  "sphinx_gallery",
+  "sphinx-design",
+  "sphinx-togglebutton",
 ]
 
 [project.urls]