update docs

docs/conf.py

@@ -73,7 +73,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.2'
+version = '1.4'
 # The full version, including alpha/beta/rc tags.
 release = '1.4.0.dev1'
 

docs/index.rst

@@ -3,14 +3,17 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-|DeDop3| Tool Documentation
-===========================
+|DeDop3| - a User Configurable Tool for Processing Delay Doppler Altimeter Data
+=============================================================================
 
-
-Contents:
+.. figure:: _static/figures/dedop-studio-frontpage.png
+   :scale: 50%
+   :align: center
 
 .. toctree::
-   :maxdepth: 2
+   :caption: Table of Contents
+   :maxdepth: 1
+   :numbered:
 
    introduction
    quickstart

docs/quickstart.rst

@@ -6,21 +6,12 @@
 Quick Start
 ===========
 
-
-The DeDop tool set currently comprises only the *DeDop Shell* - a command-line interface to the Delay Doppler Processor
-(DPP).
-
 This chapter is a tutorial for users new to the DeDop Shell.
 
-Before you start
-================
-
-If you haven't installed DeDop yet, please refer to :doc:`user_manual/um_setup`.
+Refer to :doc:`user_manual/um_setup` for installing DeDop.
 
-During installation, a new menu entry or desktop shortcut named **DeDop Shell** should have been created.
-If you click it, a new terminal window should open up. If you can't see a menu entry nor a desktop shortcut
-open the ``bin`` (Unix and Darwin/OS X) or ``Scripts`` (Windows) directory of your DeDop installation directory.
-The you should find a ``dedop-shell`` script. Click this instead of a missing menu entry / desktop shortcut.
+Using DeDop Shell
+=================
 
 In the new terminal window, type::
 
@@ -33,8 +24,9 @@ to list the available DeDop sub-commands. You can get help on sub-commands as we
 
 .. _processing_l1a_l1b:
 
+-----------------------
 Processing a L1A to L1B
-=======================
+-----------------------
 
 To perform L1A to L1B processing using the Delay Doppler Processor (DDP) you need to add one or more L1A
 input files to your current DeDop *workspace*::
@@ -83,8 +75,9 @@ To generate a directory of figure images, run the script with a directory name o
     $ python inspect-script.py some/path/L1B_default.nc inspect-out dir
 
 
+------------------------------------
 Changing the processor configuration
-====================================
+------------------------------------
 
 From the last steps above, the current DDP configuration should be still ``default``. Verify::
 

docs/user_manual/um_setup.rst

@@ -2,53 +2,75 @@
 Setup
 ======
 
-DeDop Shell Installation
-=========================
+DeDop Core Installation
+========================
 
 From Binaries
 --------------
 
-DeDop is distributed as pre-compiled binaries which can be retrieved from `here <https://github.com/DeDop/dedop-core/releases/tag/v1.2.0>`_.
-For the windows Windows platforms there is a dedicated installer executable. For Mac OS and Unixes a ZIP file is provided.
-All platform distributions have a bundled Python interpreter, that's also the reason why they are quite large in size
-(roughly 300 megabytes). As mentioned before, this package also contains DeDop processor and DeDop webapi.
+DeDop Core is distributed as pre-compiled binaries which can be retrieved from `here <https://github.com/DeDop/dedop-core/releases/tag/v1.3.0>`_.
+For the windows Windows platforms there is a dedicated installer executable. For MacOS and Unix a shell script file is
+provided. All platform distributions have a bundled Python interpreter, which makes it rather large in size
+(roughly 300-400 MB). As mentioned before, this package also contains DeDop processor and DeDop webapi. To install DeDop
+Core in Windows, double click the ``exe`` file.
 
-After installing (on Windows) / unpacking (on Unixes) you find an executable file named `dedop-shell` in the
-installation's root directory. Running it brings up the *DeDop Shell*.
+In MacOS, run the following commands::
+
+    chmod u+x DeDop-core-1.x.x-MacOSX-x86_64.sh
+    ./DeDop-core-1.x.x-MacOSX-x86_64.sh
+
+In Unix, run the following commands::
+
+    chmod u+x DeDop-core-1.x.x-Linux-x86_64.sh
+    ./DeDop-core-1.x.x-Linux-x86_64.sh
+
+During installation, you will be requested the installation location as well as a preference to add this location to
+your PATH. When unsure, just follow the default (no).
+
+Run the following command to start DeDop Shell::
+
+    <dedop_core_installation_dir>\Scripts\dedop-shell.bat   # Windows
+    <dedop_core_installation_dir>/bin/dedop-shell.command   # MacOS
+    <dedop_core_installation_dir>/bin/dedop-shell.sh        # Unix
 
 From Source
 ------------
 
 DeDop is programmed in Python so you first need to setup a suitable Python environment.
-We recommend using a `Miniconda <http://conda.pydata.org/miniconda.html>`_ Python3 environment, so
-you don't need to install the DeDop library dependencies in your default Python.
+We recommend using a `Miniconda <http://conda.pydata.org/miniconda.html>`_ Python3 environment to create an isolated
+environment that is independent from the default Python in your machine. Refer to `this page <https://conda.io/docs/user-guide/install/index.html>`_
+for the instruction on how to install Miniconda on your machine. It is recommended to install Miniconda with Python 3.x
+since DeDop Core uses Python 3.
 
-First, checkout the DeDop source code from GitHub::
+To install DeDop Core from source, first you need to checkout the DeDop Core GitHub repository::
 
     git clone https://github.com/DeDop/dedop-core.git
 
 Step into the newly created source directory::
 
     cd dedop-core
 
-After installing Miniconda, open a terminal window and create an isolated Python environment with all the required
-dependencies as listed in `environment.yml` and *activate* it. Type::
+After installing Miniconda, open a terminal window and create ``dedop`` environment with all the required
+dependencies as listed in `environment.yml` by typing::
+
+    <miniconda_installation_dir>/bin/conda env create --file environment.yml
 
-    conda env create --file environment.yml
-    source activate dedop  # Linux, MacOS
-    activate dedop         # Windows
+To activate this environment, type::
+
+    source <miniconda_installation_dir>/bin/activate dedop      # Linux, MacOS
+    <miniconda_installation_dir>\Scripts\activate dedop         # Windows
 
 Install DeDop in the Python environment `dedop`::
 
-    python setup.py develop
+    python setup.py install
 
-After installing from source, you should be able to run the DeDop Shell, try::
+After the installation is finished, start DeDop Shell by typing::
 
     dedop --help
 
 If you plan to run DeDop Studio, please run the following command::
 
-    dedop-webapi
+    dedop-webapi --version
 
 This is necessary to trigger the creation of `~/.dedop/<version_num>/dedop-location` file. In the installation from binary,
 this is not required because at the end of the installation, this file is automatically created.
@@ -57,41 +79,47 @@ this is not required because at the end of the installation, this file is automa
 DeDop Studio Installation
 ==========================
 
-As illustrated in :ref:`this diagram<dedop_diagram>`, DeDop studio is dependent on DeDop core in performing any processing duties.
-For this reason, make sure that DeDop core has been installed in your computer before performing DeDop studio installation.
-Failure to do that will result in the DeDop studio failing to startup.
+As illustrated in :ref:`this diagram<dedop_diagram>`, DeDop Studio is dependent on DeDop Core in performing any processing
+tasks. For this reason, make sure that DeDop Core has been installed in your computer before performing DeDop Studio
+installation. Failure to do that will result in the DeDop studio failing to startup.
 
 From Binaries
 --------------
 
 DeDop is distributed as pre-compiled binaries which can be retrieved from
-`DeDop Studio release page <https://github.com/DeDop/dedop-studio/releases/tag/v1.2.0>`_.
-For the windows Windows platforms there is an easy one-click installer executable. For Mac OS, the installer is available
-as dmg file and zip file, while for Unix, the installer is availble as tar.gz, zip, and AppImage files. Please make sure that
-you have already installed DeDop-core before starting the DeDop-studio installation. More information about this can be found
-:ref:`in this section <studio_intro>`.
+`DeDop Studio release page <https://github.com/DeDop/dedop-studio/releases/tag/v1.3.0>`_.
+For the windows Windows platforms there is an easy one-click installer executable. For MacOS, the installer is available
+as dmg file and zip file, while for Unix, the installer is available as tar.gz, zip, and AppImage files. All DeDop Studio
+installers (except  the Unix tar.gz and zip files) are light-weight and executed by double clicking them. They don’t
+require any extra user input.
 
-Please note that in Windows, you may need to accept the warning at the beginning in regards to installing a third-party software.
-Similarly in MacOS, you may need to enable an installation of third-party software: More information about it can be found
-`in Gatekeeper page <https://support.apple.com/en-us/HT202491>`_.
+Please note that in Windows, you may need to accept the warning at the beginning in regards to installing a third-party
+software. Similarly in MacOS, you may need to allow installation of apps downloaded from `App Store and identified developers`.
+More information about it can be found `in Gatekeeper page <https://support.apple.com/en-us/HT202491>`_.
 
 After the installation has been completed, you will find an executable file named `DeDop-Studio`, which you can search using
 start menu (Windows) or Spotlight (MacOS).
 
 From Source
 ------------
 
+---------------
 Pre-requisites
 ---------------
-- nodejs v6.9.1
-- npm v3.10.8
-- git
-- dedop-core
 
+The following software needs to be installed on your machine before you can start installing DeDop Studio from source:
+
+    - nodejs v6.9.1
+    - npm v3.10.8 (comes with nodejs)
+
+Go to `here <https://nodejs.org/en/download/releases/>`_ for downloading nodejs and go to
+`this page <https://nodejs.org/en/download/package-manager/>`_ for the installation guide.
+
+---------------
 How-to-install
 ---------------
 
-First of all, clone the dedop-core repository::
+Clone dedop-studio repository::
 
     git clone https://github.com/DeDop/dedop-studio.git
 
@@ -100,7 +128,17 @@ Do npm install::
     cd dedop-studio
     npm install
 
-Create a `dedop-config.js` and put the location of ``dedop-webapi.exe`` (Windows) or ``dedop-webapi`` (MacOS and Linux) under ``webAPIConfig`` field.
+Create a `dedop-config.js` inside `dedop-studio` directory and put the location of ``dedop-webapi.exe`` (Windows) or
+``dedop-webapi`` (MacOS and Linux) under ``webAPIConfig`` field. The location of ``dedop-webapi`` will be where the
+dedop environment is, eg.::
+
+    <miniconda_installation_dir>\envs\dedop\Scripts\dedop-webapi.exe    # Windows with installation from source
+    <miniconda_installation_dir>/envs/dedop/bin/dedop-webapi            # MacOS & Unix with installation from source
+
+    <dedop-core_installation_dir>\Scripts\dedop-webapi.exe              # Windows with installation from binary
+    <dedop-core_installation_dir>/bin/dedop-webapi                      # MacOS & Unix with installation from source
+
+
 More information about the can be found in ``dedop-config.template.js``. Sample values for ``webAPIConfig`` in different OS's are
 provided here::