improve install instructions and intro text

README.rst

@@ -8,23 +8,13 @@ Birdwatcher
   :align: center
   :width: 720
 
-Birdwatcher is a Python computer vision library for analyzing animal behavior
-in a Python scientific computing environment.
-
-Birdwatcher should help you getting up and running quickly when building
-analysis code or tools for specific measurements. It provides high-level
-functionality that is common in video analysis, such as reading and writing
-videos into and from numpy arrays, applying processing algorithms such as
-background subtraction, morphological transformation, resizing, drawing on
-frames etc. Much of the underlying video and image processing is based on
-`FFmpeg <https://www.ffmpeg.org/>`__ and `OpenCV <https://opencv.org/>`__,
-but Birdwatcher is a lot easier to use for many tasks because its
-higher-level implementation of functionality as compared to these tools.
-
-Despite its name, Birdwatcher is not only for birds. We also successfully
-analyzed dog behavior, and it could be used on anything that moves. It is
-being used in our lab but still under heavy development, and should be
-considered alpha software.
+Birdwatcher is a Python computer vision library for analyzing animal behavior in a Python scientific computing environment.
+
+Birdwatcher should help you getting up and running quickly when building analysis code or tools for specific measurements. It provides functionality that is common in video analysis, such as reading and writing videos into and from numpy arrays, applying processing algorithms such as background subtraction, morphological transformation, resizing, drawing on frames etc. Much of the underlying video and image processing is based on `FFmpeg <https://www.ffmpeg.org/>`__ and `OpenCV <https://opencv.org/>`__, but Birdwatcher is easier to use for many tasks because its higher-level implementation of functionality.
+
+Users can use Birdwatcher to efficiently write code for behavioral analysis. If it targets common use cases, such analysis code can in turn become part of Birdwatcher . At the moment behavioral analysis is limited to movement/location detection of single animals.
+
+Despite its name, Birdwatcher is not only for birds. We also successfully analyzed dog behavior, and it could be used on anything that moves. It is being used in our lab but still under heavy development, and should be considered alpha software.
 
 Code can be found on GitHub: https://github.com/gbeckers/Birdwatcher .
 
@@ -43,28 +33,43 @@ Python 3 versions may also work.
 
 **User installation**
 
-1) We recommend using Anaconda for installation. Install Anaconda from https://www.anaconda.com/ .
+#. We recommend using Anaconda for installation. Install Anaconda from https://www.anaconda.com/ .
+
+#. Open Anaconda prompt in terminal.
+
+#. Create new environment for Birdwatcher (name is up to you, in example here 'mybirdwatcher'). We install Jupyter lab and ffmpeg at the same time:
+
+    .. code-block:: bash
+
+      $ conda create -n mybirdwatcher python=3.9 jupyterlab ffmpeg git
+
+#. Switch to this new environment:
+
+   Linux and MacOS:
+
+    .. code-block:: bash
+
+      $ source activate mybirdwatcher
 
-2) Open Anaconda prompt in terminal.
+   Windows:
 
-3) Create new environment for Birdwatcher (name is up to you, in example
-   here 'mybirdwatcher'). We install Jupter lab and ffmpeg at the same time::
+    .. code-block:: bash
 
-    $ conda create -n mybirdwatcher python=3.9 jupyterlab ffmpeg git
+      $ conda activate mybirdwatcher
 
-4) Switch to this new environment:
+#. Install Birdwatcher:
 
-   Linux and MacOS::
+   Stable latest official release from PyPi:
 
-    $ source activate mybirdwatcher
+    .. code-block:: bash
 
-   Windows::
+      $ pip install Birdwatcher
 
-    $ conda activate mybirdwatcher
+   If instead you want the latest version of the git master branch from, use:
 
-5) Install Birdwatcher master branch from git repo::
+    .. code-block:: bash
 
-    $ pip install git+https://github.com/gbeckers/birdwatcher@master
+      $ pip install git+https://github.com/gbeckers/birdwatcher@master
 
 
 **Dependencies**
@@ -91,7 +96,7 @@ install it yourself (https://www.ffmpeg.org/).
 Run notebooks tutorial
 ----------------------
 
-To quickly learn the fundamentals of Birdwatcher, please walk through our notebooks. First, you need to download the notebooks and example videos. Then, navigate to the directory of the notebooks and activate the 'mybirdwatcher' environment. Type `jupyter lab` which opens in your browser. You can now open the notebooks and run the tutorial.
+To quickly learn the fundamentals of Birdwatcher, please walk through our notebooks. First, you need to download the notebooks and example videos from github. Then, navigate to the directory of the notebooks and activate the 'mybirdwatcher' environment. Type `jupyter lab` which opens in your browser. You can now open the notebooks and run the tutorial.
 
 
 Test

docs/index.rst

@@ -9,27 +9,17 @@ Birdwatcher
 |Github CI Status| |PyPi version| |Docs Status| |Repo Status|
 |Codecov status|
 
-.. image:: images/banner.gif
+.. image:: docs/images/banner.gif
   :align: center
   :width: 720
 
-Birdwatcher is a Python computer vision library for analyzing animal behavior
-in a Python scientific computing environment.
+Birdwatcher is a Python computer vision library for analyzing animal behavior in a Python scientific computing environment.
 
-Birdwatcher should help you getting up and running quickly when building
-analysis code or tools for specific measurements. It provides high-level
-functionality that is common in video analysis, such as reading and writing
-videos into and from numpy arrays, applying processing algorithms such as
-background subtraction, morphological transformation, resizing, drawing on
-frames etc. Much of the underlying video and image processing is based on
-`FFmpeg <https://www.ffmpeg.org/>`__ and `OpenCV <https://opencv.org/>`__,
-but Birdwatcher is a lot easier to use for many tasks because its
-higher-level implementation of functionality as compared to these tools.
+Birdwatcher should help you getting up and running quickly when building analysis code or tools for specific measurements. It provides functionality that is common in video analysis, such as reading and writing videos into and from numpy arrays, applying processing algorithms such as background subtraction, morphological transformation, resizing, drawing on frames etc. Much of the underlying video and image processing is based on `FFmpeg <https://www.ffmpeg.org/>`__ and `OpenCV <https://opencv.org/>`__, but Birdwatcher is easier to use for many tasks because its higher-level implementation of functionality.
 
-Despite its name, Birdwatcher is not only for birds. We also successfully
-analyzed dog behavior, and it could be used on anything that moves. It is
-being used in our lab but still under heavy development, and should be
-considered alpha software.
+Users can use Birdwatcher to efficiently write code for behavioral analysis. If it targets common use cases, such analysis code can in turn become part of Birdwatcher . At the moment behavioral analysis is limited to movement/location detection of single animals.
+
+Despite its name, Birdwatcher is not only for birds. We also successfully analyzed dog behavior, and it could be used on anything that moves. It is being used in our lab but still under heavy development, and should be considered alpha software.
 
 Code can be found on GitHub: https://github.com/gbeckers/Birdwatcher .
 
@@ -41,6 +31,7 @@ Utrecht University. It is open source, freely available under the `New BSD Licen
 
 
 
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:

docs/installation.rst

@@ -4,36 +4,48 @@ Installation
 
 .. contents:: :local:
 
-Installation Birdwatcher package
---------------------------------
-
 Birdwatcher officially supports Python 3.9 or higher, but older
 Python 3 versions may also work.
 
 **User installation**
 
-1) We recommend using Anaconda for installation. Install Anaconda from https://www.anaconda.com/ .
+#. We recommend using Anaconda for installation. Install Anaconda from https://www.anaconda.com/ .
+
+#. Open Anaconda prompt in terminal.
+
+#. Create new environment for Birdwatcher (name is up to you, in example here 'mybirdwatcher'). We install Jupyter lab and ffmpeg at the same time:
+
+    .. code-block:: bash
+
+      $ conda create -n mybirdwatcher python=3.9 jupyterlab ffmpeg git
+
+#. Switch to this new environment:
+
+   Linux and MacOS:
+
+    .. code-block:: bash
+
+      $ source activate mybirdwatcher
 
-2) Open Anaconda prompt in terminal.
+   Windows:
 
-3) Create new environment for Birdwatcher (name is up to you, in example
-   here 'mybirdwatcher'). We install Jupter lab and ffmpeg at the same time::
+    .. code-block:: bash
 
-    $ conda create -n mybirdwatcher python=3.9 jupyterlab ffmpeg
+      $ conda activate mybirdwatcher
 
-4) Switch to this new environment:
+#. Install Birdwatcher:
 
-   Linux and MacOS::
+   Stable latest official release from PyPi:
 
-    $ source activate mybirdwatcher
+    .. code-block:: bash
 
-   Windows::
+      $ pip install Birdwatcher
 
-    $ conda activate mybirdwatcher
+   If instead you want the latest version of the git master branch from, use:
 
-5) Install Birdwatcher master branch from git repo::
+    .. code-block:: bash
 
-    $ pip install git+https://github.com/gbeckers/birdwatcher@master
+      $ pip install git+https://github.com/gbeckers/birdwatcher@master
 
 
 **Dependencies**
@@ -53,5 +65,5 @@ It further depends on:
 
 - ffmpeg (including ffprobe)
 
-If you do not use the conda way above to install it, you need to
+If you do not use the conda way above to install ffmpeg, you need to
 install it yourself (https://www.ffmpeg.org/).