Merge pull request #229 from jpgill86/docs-install-and-update

Improve installation and updating documentation

README.rst

@@ -90,8 +90,8 @@ Data stores can be password protected and **neurotic** will prompt you for a
 user name and password. This makes it easy to share the **neurotic** experience
 with your colleagues! 🤪
 
-Installation
-------------
+Installing neurotic
+-------------------
 
 **neurotic** requires Python 3.6 or later.
 
@@ -100,8 +100,30 @@ Note that the latest release of one of **neurotic**'s dependencies, pyqtgraph
 dependency is installed via conda-forge (recommended method) (`details
 <https://github.com/jpgill86/neurotic/issues/129>`_).
 
-Recommended Method: conda-forge
-...............................
+Standalone Installers (recommended for beginners)
+.................................................
+
+Downloadable installers make installing **neurotic** easy for beginners. When
+available, they can be downloaded from the GitHub Releases page:
+
+    `👉 Download installers here (listed under "Assets") 👈`__
+
+    __ `GitHub Releases`_
+
+These installers are intended for users who do not want to independently
+install Python or conda just to use **neurotic**. They will install
+**neurotic** and everything it needs (including a fully contained Python
+environment) into a dedicated directory on your computer. On Windows, the
+installer will also create a Start Menu shortcut for launching the app.
+
+Because the process of building installers is not automated, installers may not
+be available for the latest releases for all platforms.
+
+For developers, a recipe for building new installers using `conda constructor`_
+is maintained here: `constructor recipe`_.
+
+Alternate Method: conda (recommended for Pythonistas)
+.....................................................
 
 conda_ users can install **neurotic** and all of its dependencies with one
 command::
@@ -120,61 +142,67 @@ The easiest way to install PyAV is using conda_::
 
     conda install -c conda-forge av
 
-Install the latest release version of **neurotic** from PyPI_ using ::
-
-    pip install -U neurotic
+Install **neurotic** from PyPI_ using ::
 
-or install the latest development version from GitHub_ using ::
+    pip install neurotic
 
-    pip install -U git+https://github.com/jpgill86/neurotic.git
+Updating neurotic
+-----------------
 
-Note that if you install the development version, you may also need the latest
-development version of ephyviewer_, which you can get using ::
+The recommended method of updating **neurotic** depends on the original method
+of installation.
 
-    pip install -U git+https://github.com/NeuralEnsemble/ephyviewer.git
+If you are unsure what method you used, updating using ``conda`` or ``pip`` is
+likely to work. Standalone installers may be safe too, though this could lead
+to having multiple version installed simultaneously.
 
-Alternate Method: Standalone Installers
-.......................................
+Updating with Standalone Installers
+...................................
 
-**This will be the simplest and most convenient installation method for many
-users**, especially those uncomfortable with managing Python environments, but
-there are a couple caveats.
+If you previously installed **neurotic** using a standalone installer, you may
+install a newer version using another installer, either into a different
+directory or by first uninstalling the old version. Installers can be
+downloaded from the GitHub Releases page:
 
-For users who do not want to independently install Python or conda just to use
-**neurotic**, traditional program installers exist. These will install
-**neurotic** and everything it needs (including a fully contained Python
-environment) into a dedicated directory on your computer. On Windows, the
-installer will also create a Start Menu shortcut for launching the app.
+    `👉 Download installers here (listed under "Assets") 👈`__
 
-If available, these installers can be found on the `GitHub Releases`_ page,
-listed under "Assets". However, because the process of building installers is
-not yet automated, they may not be available for the latest releases.
+    __ `GitHub Releases`_
 
-Installers are not generally recommended for users who already have a working
-Python environment and who are comfortable with ``conda``/``pip`` because the
-installers use more disk space and may be less straightforward to upgrade.
-Instead, the other methods described above are recommended.
+Alternatively, if a new installer is not currently available for your platform,
+or if you would just like a much faster method, you may use the command line
+tools provided by the installer (via the "Anaconda Prompt" on Windows, or the
+Terminal on macOS and Linux)::
 
-For developers, a recipe for building new installers using `conda constructor`_
-is maintained here: `constructor recipe`_.
+    conda update -c conda-forge neurotic
 
-Updating neurotic
-.................
+Updating with conda
+...................
 
-If you installed **neurotic** from conda-forge, you can update it using ::
+If you installed **neurotic** with `conda`_, you can update to the latest
+release using ::
 
     conda update -c conda-forge neurotic
 
-If you installed **neurotic** using ``pip``, use ::
+Updating with pip
+.................
+
+If you installed **neurotic** using ``pip``, you can update to the latest
+release available on PyPI_ using ::
 
     pip install -U neurotic
 
-If you installed **neurotic** using a standalone installer, you can try ::
+Development Version
+...................
 
-    conda update -c conda-forge neurotic
+If you are interested in trying new, unreleased features of **neurotic**, you
+may install the latest development version from GitHub_ using ::
+
+    pip install -U git+https://github.com/jpgill86/neurotic.git
 
-but uninstalling and reinstalling using a newer installer may work just as
-well.
+Note that if you install the development version, you may also need the latest
+development version of ephyviewer_, which you can get using ::
+
+    pip install -U git+https://github.com/NeuralEnsemble/ephyviewer.git
 
 Getting Started
 ---------------

docs/index.rst

@@ -23,6 +23,7 @@ at the same datasets!
 
    overview
    install
+   update
    gettingstarted
    metadata
    api

docs/install.rst

@@ -1,7 +1,7 @@
 .. _installation:
 
-Installation
-============
+Installing neurotic
+===================
 
 **neurotic** requires Python 3.6 or later.
 
@@ -10,10 +10,34 @@ Note that the latest release of one of **neurotic**'s dependencies, pyqtgraph
 dependency is installed via conda-forge (recommended method) (:issue:`details
 <129>`).
 
-.. _installation-conda-forge:
+.. _installation-installers:
+
+Standalone Installers (recommended for beginners)
+-------------------------------------------------
+
+Downloadable installers make installing **neurotic** easy for beginners. When
+available, they can be downloaded from the GitHub Releases page:
+
+    `👉 Download installers here (listed under "Assets") 👈`__
+
+    __ `GitHub Releases`_
+
+These installers are intended for users who do not want to independently
+install Python or conda just to use **neurotic**. They will install
+**neurotic** and everything it needs (including a fully contained Python
+environment) into a dedicated directory on your computer. On Windows, the
+installer will also create a Start Menu shortcut for launching the app.
+
+Because the process of building installers is not automated, installers may not
+be available for the latest releases for all platforms.
 
-Recommended Method: conda-forge
--------------------------------
+For developers, a recipe for building new installers using `conda constructor`_
+is maintained here: `constructor recipe`_.
+
+.. _installation-conda:
+
+Alternate Method: conda (recommended for Pythonistas)
+-----------------------------------------------------
 
 conda_ users can install **neurotic** and all of its dependencies with one
 command::
@@ -34,65 +58,9 @@ The easiest way to install PyAV is using conda_::
 
     conda install -c conda-forge av
 
-Install the latest release version of **neurotic** from PyPI_ using ::
-
-    pip install -U neurotic
-
-or install the latest development version from GitHub_ using ::
-
-    pip install -U git+https://github.com/jpgill86/neurotic.git
-
-Note that if you install the development version, you may also need the latest
-development version of ephyviewer_, which you can get using ::
-
-    pip install -U git+https://github.com/NeuralEnsemble/ephyviewer.git
-
-.. _installation-installers:
-
-Alternate Method: Standalone Installers
----------------------------------------
-
-**This will be the simplest and most convenient installation method for many
-users**, especially those uncomfortable with managing Python environments, but
-there are a couple caveats.
-
-For users who do not want to independently install Python or conda just to use
-**neurotic**, traditional program installers exist. These will install
-**neurotic** and everything it needs (including a fully contained Python
-environment) into a dedicated directory on your computer. On Windows, the
-installer will also create a Start Menu shortcut for launching the app.
-
-If available, these installers can be found on the `GitHub Releases`_ page,
-listed under "Assets". However, because the process of building installers is
-not yet automated, they may not be available for the latest releases.
-
-Installers are not generally recommended for users who already have a working
-Python environment and who are comfortable with ``conda``/``pip`` because the
-installers use more disk space and may be less straightforward to upgrade.
-Instead, the other methods described above are recommended.
-
-For developers, a recipe for building new installers using `conda constructor`_
-is maintained here: `constructor recipe`_.
-
-.. _installation-updating:
-
-Updating neurotic
------------------
-
-If you installed **neurotic** from conda-forge, you can update it using ::
-
-    conda update -c conda-forge neurotic
-
-If you installed **neurotic** using ``pip``, use ::
-
-    pip install -U neurotic
-
-If you installed **neurotic** using a standalone installer, you can try ::
-
-    conda update -c conda-forge neurotic
+Install **neurotic** from PyPI_ using ::
 
-but uninstalling and reinstalling using a newer installer may work just as
-well.
+    pip install neurotic
 
 
 .. _conda:              https://docs.conda.io/projects/conda/en/latest/user-guide/install/

docs/releases/1.2.0.rst

@@ -9,8 +9,8 @@ neurotic 1.2.0
 Neo's :mod:`neo.io` classes thanks to two new metadata parameters: ``io_class``
 and ``io_args``. See :ref:`config-metadata-neo-io` for details.
 
-**neurotic** is now available on conda-forge! See
-:ref:`installation-conda-forge` for details on how to install.
+**neurotic** is now available on conda-forge! See :ref:`installation-conda` for
+details on how to install.
 
 Improvements
 ------------

docs/update.rst

@@ -0,0 +1,72 @@
+.. _updating:
+
+Updating neurotic
+=================
+
+The recommended method of updating **neurotic** depends on the original method
+of installation.
+
+If you are unsure what method you used, updating using ``conda`` or ``pip`` is
+likely to work. Standalone installers may be safe too, though this could lead
+to having multiple version installed simultaneously.
+
+.. _updating-installers:
+
+Updating with Standalone Installers
+-----------------------------------
+
+If you previously installed **neurotic** using a standalone installer, you may
+install a newer version using another installer, either into a different
+directory or by first uninstalling the old version. Installers can be
+downloaded from the GitHub Releases page:
+
+    `👉 Download installers here (listed under "Assets") 👈`__
+
+    __ `GitHub Releases`_
+
+Alternatively, if a new installer is not currently available for your platform,
+or if you would just like a much faster method, you may use the command line
+tools provided by the installer (via the "Anaconda Prompt" on Windows, or the
+Terminal on macOS and Linux)::
+
+    conda update -c conda-forge neurotic
+
+.. _updating-conda:
+
+Updating with conda
+-------------------
+
+If you installed **neurotic** with `conda`_, you can update to the latest
+release using ::
+
+    conda update -c conda-forge neurotic
+
+.. _updating-pip:
+
+Updating with pip
+-----------------
+
+If you installed **neurotic** using ``pip``, you can update to the latest
+release available on PyPI_ using ::
+
+    pip install -U neurotic
+
+Development Version
+-------------------
+
+If you are interested in trying new, unreleased features of **neurotic**, you
+may install the latest development version from GitHub_ using ::
+
+    pip install -U git+https://github.com/jpgill86/neurotic.git
+
+Note that if you install the development version, you may also need the latest
+development version of ephyviewer_, which you can get using ::
+
+    pip install -U git+https://github.com/NeuralEnsemble/ephyviewer.git
+
+
+.. _conda:              https://docs.conda.io/projects/conda/en/latest/user-guide/install/
+.. _ephyviewer:         https://github.com/NeuralEnsemble/ephyviewer
+.. _GitHub:             https://github.com/jpgill86/neurotic
+.. _GitHub Releases:    https://github.com/jpgill86/neurotic/releases
+.. _PyPI:               https://pypi.org/project/neurotic

neurotic/gui/standalone.py

@@ -272,7 +272,7 @@ def create_menus(self):
         do_show_check_for_updates.triggered.connect(self.show_check_for_updates)
 
         do_open_update_docs = help_menu.addAction('How to update')
-        do_open_update_docs.triggered.connect(lambda: open_url('https://neurotic.readthedocs.io/en/latest/install.html#updating-neurotic'))
+        do_open_update_docs.triggered.connect(lambda: open_url('https://neurotic.readthedocs.io/en/latest/update.html'))
 
         do_open_issues = help_menu.addAction('Report issues')
         do_open_issues.triggered.connect(lambda: open_url('https://github.com/jpgill86/neurotic/issues'))