Merge pull request #21 from TravisWheelerLab/installation-instructions

more installation procedure changes

RELEASE_NOTES.md

@@ -1,4 +1,4 @@
 Changes for this version of DIPLOMAT:
-- added installation troubleshooting procedure to docs
-- added installation verification procedure to docs
-- created a zenodo record for sample data and models.
+- updated installation procedure to include updating pip
+- added quotes around the editable installation path + options for zsh compatibility 
+- change order of installation instructions to prioritize DIPLOMAT-SLEAP

diplomat/__init__.py

@@ -2,7 +2,7 @@
 A tool providing multi-animal tracking capabilities on top of other Deep learning based tracking software.
 """
 
-__version__ = "0.1.12"
+__version__ = "0.1.12.1"
 # Can be used by functions to determine if diplomat was invoked through it's CLI interface.
 CLI_RUN = False
 

docs/source/installation.rst

@@ -22,6 +22,63 @@ and install process that is consistent across platforms. To install Miniforge:
 Installing DIPLOMAT
 -------------------
 
+With Support for SLEAP Projects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Using Mamba or Conda
+~~~~~~~~~~~~~~~~~~~~
+
+Once you have a mamba installed, you'll want to open a terminal and type one of these two commands:
+
+.. code-block:: sh
+
+    # Install diplomat with GPU support...
+    mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP.yaml
+    # Install diplomat with CPU support only...
+    mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP-CPU.yaml
+
+.. hint::
+
+    Both running and installing diplomat requires access to a terminal. To access one:
+
+    **Windows:** Open the start menu and search for *Miniforge Prompt*.
+
+    **Linux:** Press :kbd:`CTRL` + :kbd:`ALT` + :kbd:`T`. This will open a terminal window.
+
+    **Mac:** Select the search icon in the top right corner of the screen to open Spotlight, and
+    then search for *Terminal*.
+
+Once done, simply activate the brand new environment.
+
+.. code-block:: sh
+
+    mamba activate DIPLOMAT-SLEAP
+
+From here, the ``diplomat`` command will be available from the command line.
+
+Using PIP
+~~~~~~~~~
+
+If you are using an alternative package for managing python environments, you can install
+DIPLOMAT with SLEAP support by simply using pip, using one of the two commands below:
+
+NOTE: SLEAP is known to have installation issues on Windows when attempting to use pip. If you're
+trying to install DIPLOMAT with SLEAP support on Windows, prefer using the mamba/miniforge method above.
+
+.. code-block:: sh
+
+    # Install DIPLOMAT with SLEAP with GUI support.
+    pip install diplomat-track[sleap, gui]
+    # Install DIPLOMAT with SLEAP without UI support.
+    pip install diplomat-track[sleap]
+
+Troubleshooting for DIPLOMAT-SLEAP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the Mamba method fails to install DIPLOMAT and SLEAP, or if DIPLOMAT does not run after installation, 
+you may need to downgrade the numpy version manually. 
+Activate the mamba environment with ``mamba activate DIPLOMAT-SLEAP``, then downgrade numpy with ``pip install numpy<1.23.0``. 
+
 With Support for DeepLabCut Projects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -98,8 +155,10 @@ as Miniforge.
     venv/scripts/Activate
     ## Activate the venv on Mac/Linux.
     source venv/bin/activate
+    # Update PIP
+    python -m pip install --upgrade pip
     # Finally, install DIPLOMAT and DLC. The installation may take several minutes to complete.
-    python -m pip install -e .[dlc,gui] --ignore-installed
+    python -m pip install -e ".[dlc,gui]" --ignore-installed
     # Verify that the installation was successful. The following command should output the current version number.
     diplomat --version
 
@@ -109,63 +168,6 @@ it, and copy the .dll file to the torch libraries folder of your virtual environ
 should be located at ``.\venv\lib\site-packages\torch\lib`` within the DIPLOMAT directory. 
 If you named your virtual environment something other than ``venv``, change the path accordingly.
 
-With Support for SLEAP Projects
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Using Mamba or Conda
-~~~~~~~~~~~~~~~~~~~~
-
-Once you have a mamba installed, you'll want to open a terminal and type one of these two commands:
-
-.. code-block:: sh
-
-    # Install diplomat with GPU support...
-    mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP.yaml
-    # Install diplomat with CPU support only...
-    mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP-CPU.yaml
-
-.. hint::
-
-    Both running and installing diplomat requires access to a terminal. To access one:
-
-    **Windows:** Open the start menu and search for *Miniforge Prompt*.
-
-    **Linux:** Press :kbd:`CTRL` + :kbd:`ALT` + :kbd:`T`. This will open a terminal window.
-
-    **Mac:** Select the search icon in the top right corner of the screen to open Spotlight, and
-    then search for *Terminal*.
-
-Once done, simply activate the brand new environment.
-
-.. code-block:: sh
-
-    mamba activate DIPLOMAT-SLEAP
-
-From here, the ``diplomat`` command will be available from the command line.
-
-Using PIP
-~~~~~~~~~
-
-If you are using an alternative package for managing python environments, you can install
-DIPLOMAT with SLEAP support by simply using pip, using one of the two commands below:
-
-NOTE: SLEAP is known to have installation issues on Windows when attempting to use pip. If you're
-trying to install DIPLOMAT with SLEAP support on Windows, prefer using the mamba/miniforge method above.
-
-.. code-block:: sh
-
-    # Install DIPLOMAT with SLEAP with GUI support.
-    pip install diplomat-track[sleap, gui]
-    # Install DIPLOMAT with SLEAP without UI support.
-    pip install diplomat-track[sleap]
-
-Troubleshooting for DIPLOMAT-SLEAP
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If the Mamba method fails to install DIPLOMAT and SLEAP, you may need to downgrade the 
-numpy version manually. Activate the mamba environment with ``mamba activate DIPLOMAT-SLEAP``,
-then downgrade numpy with ``pip install numpy<1.23.0``. 
-
 Verifying the DIPLOMAT installation
 -----------------------------------