Merge pull request #31 from force-h2020/doc/update-install

DOC: Include missing updates from PR #27

docs/source/using/command_line.rst

@@ -1,13 +1,15 @@
 Using the Command Line
 ======================
 
-Both the BDSS and the Workflow Manager can be invoked from the command line whilst
-running a bash shell in the  ``force-py36`` Enthought Deployment Manager (EDM)
-environment.
+.. _cli-ref:
+
+Both the BDSS and the Workflow Manager can be invoked from the command line whilst in the
+:ref:`BDSS runtime environment <bdss-environment-ref>`.
+For example, if the runtime environment is ``force-py36``,
 
 .. code-block:: console
 
-    # enter a shell running the environment
+    # enter the environment
     $ edm shell -e force-py36
 
     # execute the workflow
@@ -23,12 +25,14 @@ The ``force_bdss`` command initiates the BDSS MCO runner, and therefore must be
 that contains optimization instructions. The ``force_wfmanager`` command initiates the Workflow Manager
 GUI, and therefore can start up with a default empty workflow, since it provides additional UI features to
 create, modify and export workflows.
+
 The ``force_bdss`` can also be invoked using the ``--evaluate`` flag, which switches the application from
 'optimize' to 'evaluate' mode and performs a single point evaluation of the workflow only. This functionality
 was designed to allow an external process (or program) to control the optimization procedure, whilst the
 system itself continues to be represented as a FORCE BDSS workflow. This is considered an 'advanced'
 feature of the BDSS framework, and so will be explored in a later extension to the main tutorial.
-EDM also supports running commands from outside a shell, using the ``edm run`` command.
+
+EDM also supports running commands from outside an environment, using the ``edm run`` command.
 
 .. code-block:: console
 

docs/source/using/installation.rst

@@ -31,40 +31,108 @@ If you instead already have an EDM installation and a default environment, perfo
 
 Verify that your shell prompt now contains the string "``(edm)``".
 You are now in your default EDM environment, and we assume this environment to be the bootstrap environment.
-The BDSS software will not be installed in this environment, but in a separate one. The following
-commands however must be executed from the bootstrap environment.
+Installation
+============
+
+The BDSS, the Workflow Manager and all plugins can be cloned from the
+`Force 2020 github respositories <https://github.com/force-h2020>`_.
+For the BDSS and Workflow Manager,
+
+.. code-block:: console
 
-Installation of the force BDSS runtime environment is performed with the
-following command. This should be done from the directory containing the ``force-bdss`` folder (named
-``Force-Project`` in this example)
+    git clone https://github.com/force-h2020/force-bdss
+    git clone https://github.com/force-h2020/force-wfmanager
+
+This tutorial uses the Enthought-Example and Nevergrad plugins as examples,
 
 .. code-block:: console
 
-    ~/Force-Project (edm)$ cd force-bdss
-    ~/Force-Project/force-bdss (edm)$ python -m ci build-env
+    git clone https://github.com/force-h2020/force-bdss-plugin-enthought-example
+    git clone https://github.com/force-h2020/force-bdss-plugin-nevergrad
+
 
-This will create another edm environment called ``force-py36``.
-Do not enter this environment. 
+Enthought Deployment Manager
+----------------------------
 
-To install the BDSS
+The BDSS, the Workflow Manager and plugins must be installed through the `Enthought Deployment
+Manager (EDM) <https://www.enthought.com/enthought-deployment-manager/>`_, a python
+virtual environment and package manager. For new users it is worth examining EDM's
+`documentation <http://docs.enthought.com/edm/>`_.
+
+To install EDM, follow the instructions specific to your operating system
+`,here <https://docs.enthought.com/edm/installation.html>`_.
+
+
+The Bootstrap Environment
+-------------------------
+
+Once EDM is installed create a 'bootstrap' environment from which you can install
+the BDSS, Workflow Manager and plugins,
 
 .. code-block:: console
 
-    ~/Force-Project/force-bdss (edm)$ python -m ci install
-    ~/Force-Project/force-bdss (edm)$ cd ..
-    
-To install the workflow manager
+    edm install -e bootstrap -y click setuptools
+
+Note that 'bootstrap' can be replaced by any name to the same effect. Now you can enter
+``bootstrap`` with,
 
 .. code-block:: console
 
-    ~/Force-Project (edm)$ cd force-wfmanager
-    ~/Force-Project/force-wfmanager (edm)$ python -m ci install
-    ~/Force-Project/force-wfmanager (edm)$ cd ..
+    edm shell -e bootstrap
 
-and (optional, but recommended), the example plugins
+and your shell prompt is prefixed with ``(bootstrap)``.
+
+
+The BDSS Runtime Environment
+----------------------------
+
+.. _bdss-environment-ref:
+
+Although repositories (BDSS, etc) are installed *from* the ``bootstrap`` environment, they are
+installed *into* a separate environment, within which the BDSS and the Workflow Manager will
+actually run. Thus this environment has also to be created before installation. To do this
+first cd into the cloned force-bdss respository,
 
 .. code-block:: console
 
-    ~/Force-Project (edm)$ cd force-bdss-plugin-enthought-example
+    ~/Force-Project (bootstrap)$ cd force-bdss
+
+and then,
+
+.. code-block:: console
+
+    ~/Force-Project/force-bdss (bootstrap)$ python -m ci build-env
+
+This creates a environment called ``force-pyXX``, where ``XX`` refers to the python version that
+the environment runs (e.g. ``force-py36`` for python 3.6) . You will now see it in the list of EDM environments,
+
+.. code-block:: console
+
+    (bootstrap)$ edm environments list
+
+    >> * bootstrap     cpython  3.6.9+2  win_x86_64  msvc2015  ~\.edm\envs\bootstrap
+    >>   force-py36    cpython  3.6.9+2  win_x86_64  msvc2015  ~.edm\envs\force-pyXX
+
+To run BDSS from the command line see :ref:`Using the Command Line <cli-ref>`.
+
+
+Repository Installation
+-----------------------
+
+From the ``bootstrap`` environment (not ``force-pyXX``!), for each respository in turn,
+cd into its directory and then install it with ``python -m ci install``. i.e.,
+
+.. code-block:: console
+
+    ~/Force-Project/force-bdss (bootstrap)$ python -m ci install
+
+    ~/Force-Project/force-bdss (bootstrap)$ cd ../force-wfmanager
+    ~/Force-Project/force-wfmanager (bootstrap)$ python -m ci install
+
+    ~/Force-Project/force-wfmanager (bootstrap)$ cd ../force-bdss-plugin-enthought-example
     ~/Force-Project/force-bdss-plugin-enthought-example (edm)$ python -m ci install
-    ~/Force-Project/force-bdss-plugin-enthought-example (edm)$ cd ..
+
+    ~/Force-Project/force-wfmanager (bootstrap)$ cd ../force-bdss-plugin-nevergrad
+    ~/Force-Project/force-bdss-plugin-nevergrad (bootstrap)$ python -m ci install
+
+    ...etc

docs/source/using/using.rst

@@ -30,7 +30,7 @@ to the BDSS and the Workflow Manager or otherwise have a specific meaning within
 
 
         Installation <installation>
-        Views <views>
+        Starting the Workflow Manager <views>
         Setup the Workflow <wf_setup>
         Run the Workflow <wf_run>
         Using the Command Line <command_line>

docs/source/using/views.rst

@@ -1,20 +1,45 @@
+Starting the Workflow Manager
+=============================
+
+The Workflow Manager can be started from within the ``bootstrap`` environment with,
+
+.. code-block:: console
+
+    (bootstrap)$ edm run -e force-pyXX -- force_wfmanager
+
+where force-pyXX is the :ref:`BDSS runtime environment <bdss-environment-ref>`.
+Alternatively one can enter the runtime environment, e.g. ``force-py36``,
+
+.. code-block:: console
+
+    (bootstrap)$ edm shell -e force-py36
+
+and then,
+
+.. code-block:: console
+
+    (force-py36)(bootstrap)$ force_wfmanager
+
 Views
-=====
+-----
 
-The Workflow Manager has two "views":
+The Workflow Manager has two major UI components or "views":
 
 ``Setup Workflow``
     For constructing the workflow, selecting parameters and KPIs and selecting
     an optimizer.
 
+.. figure:: images/setup_view.png
+    :align: center
+    :scale: 60 %
+
 ``View Results``
     For viewing the results of an optimization.
 
-You can switch between the views with the top-left button in the tool-bar: the label
-of this button will change accordingly.
-
-.. figure:: images/setup_workflow.png
+.. figure:: images/results_view.png
     :align: center
+    :scale: 60 %
 
-.. figure:: images/view_results.png
-    :align: center
+You can switch between the views with the top-left button in the tool-bar: the label
+of this button will change accordingly. We will consider the two views, in turn, over the
+next two topics.