📝 DOC: Improve Installation Instructions (#567)

- Improve installation instructions

---------

Co-authored-by: John Pocock <[email protected]>
Co-authored-by: Mostafa Jahanifar <[email protected]>

Author: 3 people

README.md

@@ -85,7 +85,7 @@ tiatoolbox supports various features through command line. For more information,
 
 Prepare a computer as a convenient platform for further development of the Python package `tiatoolbox` and related programs as follows.
 
-1. Install [pre-requisite software](https://tia-toolbox.readthedocs.io/en/latest/installation.html)
+1. Install [pre-requisite software](https://tia-toolbox.readthedocs.io/en/latest/installation.html#prerequisites)
 1. Open a terminal window<br/>
 
 ```sh
@@ -107,16 +107,16 @@ Prepare a computer as a convenient platform for further development of the Pytho
 5. Create virtual environment for TIAToolbox using
 
 ```sh
-    $ conda env create -f requirements.dev.conda.yml # for linux/mac only.
+    $ conda create -n tiatoolbox-dev python=3.8 # select version of your choice
     $ conda activate tiatoolbox-dev
+    $ pip install -r requirements_dev.txt
 ```
 
 or
 
 ```sh
-    $ conda create -n tiatoolbox-dev python=3.8 # select version of your choice
+    $ conda env create -f requirements.dev.conda.yml # for linux/mac only.
     $ conda activate tiatoolbox-dev
-    $ pip install -r requirements_dev.txt
 ```
 
 6. To use the packages installed in the environment, run the command:

docs/installation.rst

@@ -4,30 +4,26 @@ Installation
 ************
 
 Prerequisites
---------------
+=============
 The prerequisites for tiatoolbox installation are OpenSlide binaries and OpenJpeg version 2.3.0 or above.
 Please follow the instructions below to install prerequisite software according to the platform you are using.
 
-Using Anaconda (Recommended)
-============================
-
-After `installing Anaconda <https://docs.anaconda.com/anaconda/install/index.html>`_ (or miniconda), you can install TIA toolbox using the following command:
+Linux (Ubuntu)
+--------------
+On Linux the prerequisite software can be installed using the command
 
 .. code-block:: console
 
-    $ conda install -c conda-forge tiatoolbox
-
-Please note that conda-forge installation support is limited on Windows as openslide binaries are not supported on official conda channels. An alternate way to install using conda on Windows could be to install it in `WSL2 with CUDA support <https://docs.microsoft.com/en-us/windows/ai/directml/gpu-cuda-in-wsl>`_. In some cases, WSL2 runs faster on Python codes and therefore we **recommend** this option.
-
-Alternative Method
-==================
+    $ apt-get -y install libopenjp2-7-dev libopenjp2-tools openslide-tools
 
-If you cannot use Anaconda or are having trouble with it, you can try an alternative install method. We will install prerequisite binary packages and then use pip (the Python package manager) to install python dependencies.
+The same command is used when working on the Colab or Kaggle platforms.
+When working on Google Colab, we remove the packages ``datascience`` and ``albumentations`` because they conflict
+and produce an error message.
 
-Windows
-^^^^^^^
+Windows (10+)
+-------------------
 1. Download OpenSlide binaries from `this page <https://openslide.org/download/>`_. Extract the folder and add ``bin`` and ``lib`` subdirectories to
-Windows `system path <https://docs.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ee537574(v=office.14)>`_.
+Windows `system path <https://docs.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ee537574(v=office.14)>`_. If you are using a conda environment you can also copy ``bin`` and ``lib`` subdirectories to ``[Anaconda Installation Path]/envs/[tiatoolbox-environment]/Library/``.
 
 2. Install OpenJPEG. The easiest way is to install OpenJpeg is through conda
 using
@@ -36,73 +32,83 @@ using
 
     C:\> conda install -c conda-forge openjpeg
 
-3. Install
-TIAToolbox.
-
-.. code-block:: console
-
-    C:\> pip install tiatoolbox
-
-Linux (Ubuntu)
-^^^^^^^^^^^^^^
-On Linux the prerequisite software can be installed using the command
-
-.. code-block:: console
-
-    $ apt-get -y install libopenjp2-7-dev libopenjp2-tools openslide-tools
-
-The same command is used when working on the Colab or Kaggle platforms.
-When working on Google Colab, we remove the packages ``datascience`` and ``albumentations`` because they conflict
-and produce an error message.
-
 macOS
-^^^^^
+-----
 
 On macOS there are two popular package managers, `homebrew`_ and `macports`_.
 
 .. _homebrew: https://brew.sh/
 .. _macports: https://www.macports.org/
 
 Homebrew
-""""""""
+^^^^^^^^
 
 .. code-block:: console
 
     $ brew install openjpeg openslide
 
 MacPorts
-""""""""
+^^^^^^^^
 
 .. code-block:: console
 
     $ port install openjpeg openslide
 
 
-Stable release
---------------
+Installing Stable Release
+=========================
 
 Please note that TIAToolbox is tested for python version 3.8, 3.9 and 3.10.
-To install TIA Toolbox, run this command in your terminal after you have installed the prerequisite software:
+
+Recommended
+-----------
+To install TIAToolbox, run this command in your terminal after you have installed the prerequisite software:
 
 .. code-block:: console
 
     $ pip install tiatoolbox
 
 This is the preferred method to install TIA Toolbox, as it will always install the most recent stable release.
 
+Upgrade
+-------
+
 To upgrade an existing version of tiatoolbox to the latest stable release, run this command in your terminal:
 
 .. code-block:: console
 
     $ pip install --ignore-installed --upgrade tiatoolbox
 
+Without Dependencies
+--------------------
+
+If you already have setup a Python environment with all the pre-requisite software and dependencies installed and you would like to keep the existing versions of these dependencies, run this command in your terminal:
+
+.. code-block:: console
+
+    $ pip install --no-deps tiatoolbox
+
 If you don't have `pip`_ installed, this `Python installation guide`_ can guide
 you through the process.
 
 .. _pip: https://pip.pypa.io
 .. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
 
 
+Alternative Method(s)
+=====================
+
+Using Anaconda
+--------------
+
+After installing `Anaconda <https://docs.anaconda.com/anaconda/install/index.html>`_ (or `miniconda <https://docs.conda.io/en/latest/miniconda.html>`_ / `mamba <https://mamba.readthedocs.io/en/latest/user_guide/mamba.html#mamba-vs-conda-clis>`_), you can install TIAToolbox using the following command:
+
+.. code-block:: console
+
+    $ conda install -c conda-forge tiatoolbox
+
+Please note that conda-forge installation support is limited on Windows as openslide binaries are not supported on official conda channels. An alternate way to install using conda on Windows could be to install it in `WSL2 with CUDA support <https://docs.microsoft.com/en-us/windows/ai/directml/gpu-cuda-in-wsl>`_. In some cases, WSL2 runs faster on Python codes and therefore we **recommend** this option.
+
 From sources
 ------------
 
@@ -131,22 +137,24 @@ Once you have a copy of the source, you can install it with:
 .. _tarball: https://github.com/TissueImageAnalytics/tiatoolbox/tarball/master
 
 Using Docker
-============
+------------
 
 To run TIA toolbox in an isolated environment, use our `Docker image <https://github.com/tissueimageanalytics/tiatoolbox-docker/pkgs/container/tiatoolbox>`_ . We host different Dockerfiles in our github repository `tiatoolbox-docker <https://github.com/TissueImageAnalytics/tiatoolbox-docker>`_. Please report any issues related to the docker image in the repository `tiatoolbox-docker <https://github.com/TissueImageAnalytics/tiatoolbox-docker>`_.
 
 After `installing Docker <https://docs.docker.com/get-docker/>`_ (or Docker Desktop), you can use our TIA toolbox image in 3 different ways.
 
-Use the pre-built docker image
+Use the Pre-Built Docker Image
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-1. Pull the image from the Github Container Registry
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+TIAToolbox provides pre-built docker containers which can be downloaded using the instructions below:
+
+1. Pull the Image From Github Container Registry
+""""""""""""""""""""""""""""""""""""""""""""""""""""
 .. code-block:: console
 
     $ docker pull ghcr.io/tissueimageanalytics/tiatoolbox:latest
 
-2. Use the pre-built Docker image as a base image in a Dockerfile
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+2. Use the Pre-Built Docker Image as a Base Image in a Dockerfile
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .. code-block:: console
 
     $ FROM ghcr.io/tissueimageanalytics/tiatoolbox:latest