docs: richer user guide

* Enriches user guide to explain how one would go about making a research data
  analysis reproducible and runnable on REANA cloud.  (closes #85)

Signed-off-by: Tibor Simko <tibor.simko@cern.ch>

AUTHORS.rst

@@ -3,10 +3,11 @@ Authors
 
 The list of contributors in alphabetical order:
 
-- `Anton Khodak <https://orcid.org/0000-0003-3263-4553>`_ <anton.khodak@ukr.net>
-- `Diego Rodriguez <https://orcid.org/0000-0003-0649-2002>`_ <diego.rodriguez@cern.ch>
-- `Dinos Kousidis <https://orcid.org/0000-0002-4914-4289>`_ <dinos.kousidis@cern.ch>
-- `Harri Hirvonsalo <https://orcid.org/0000-0002-5503-510X>`_ <harri.hirvonsalo@cern.ch>
-- `Lukas Heinrich <https://orcid.org/0000-0002-4048-7584>`_ <lukas.heinrich@gmail.com>
-- `Michael R. Crusoe <https://orcid.org/0000-0002-2961-9670>`_ <mrc@commonwl.org>
-- `Tibor Simko <https://orcid.org/0000-0001-7202-5803>`_ <tibor.simko@cern.ch>
+- `Anton Khodak <https://orcid.org/0000-0003-3263-4553>`_
+- `Diego Rodriguez <https://orcid.org/0000-0003-0649-2002>`_
+- `Dinos Kousidis <https://orcid.org/0000-0002-4914-4289>`_
+- `Harri Hirvonsalo <https://orcid.org/0000-0002-5503-510X>`_
+- `Lukas Heinrich <https://orcid.org/0000-0002-4048-7584>`_
+- `Michael R. Crusoe <https://orcid.org/0000-0002-2961-9670>`_
+- `Sinclert Perez <https://www.linkedin.com/in/sinclert>`_
+- `Tibor Simko <https://orcid.org/0000-0001-7202-5803>`_

README.rst

@@ -5,14 +5,11 @@
 .. image:: https://img.shields.io/travis/reanahub/reana.svg
    :target: https://travis-ci.org/reanahub/reana
 
-.. image:: https://img.shields.io/coveralls/reanahub/reana.svg
-   :target: https://coveralls.io/r/reanahub/reana
-
 .. image:: https://readthedocs.org/projects/docs/badge/?version=latest
    :target: https://reana.readthedocs.io/en/latest/?badge=latest
 
-.. image:: https://badge.waffle.io/reanahub/reana.svg?label=Status%3A%20ready%20for%20work&title=Issues%20ready%20for%20work
-   :target: https://waffle.io/reanahub/reana
+.. image:: https://img.shields.io/coveralls/reanahub/reana.svg
+   :target: https://coveralls.io/r/reanahub/reana
 
 .. image:: https://badges.gitter.im/Join%20Chat.svg
    :target: https://gitter.im/reanahub/reana?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge
@@ -36,12 +33,12 @@ original publication.
 Features
 --------
 
-- help to structure research data analysis in reusable manner
+- structure research data analysis in reusable manner
 - instantiate computational workflows on remote clouds
 - rerun analyses with modified input data, parameters or code
 - support for several compute clouds (Kubernetes/OpenStack)
-- support for several workflow specifications (CWL, Yadage)
-- support for several shared storage systems (Ceph, EOS)
+- support for several workflow specifications (CWL, Serial, Yadage)
+- support for several shared storage systems (Ceph)
 - support for several container technologies (Docker)
 
 Useful links

docs/administratorguide.rst

@@ -194,7 +194,7 @@ script. The typical usage scenario goes as follows:
    $ reana-cluster init
    $ reana-cluster status
    $ # set environment variables for reana-client
-   $ eval $(reana-cluster env)
+   $ eval $(reana-cluster env --incude-admin-token) # if you are admin
 
 For more information, please see `REANA-Cluster's Getting started guide
 <http://reana-cluster.readthedocs.io/en/latest/gettingstarted.html>`_.

docs/gettingstarted.rst

@@ -9,32 +9,28 @@ three steps.
 Step One: Structure your analysis
 ---------------------------------
 
-Structure your research data analysis repository into "inputs", "code",
-"environments", "workflows" directories, following up the model of the
-:ref:`fourquestions`. Create ``reana.yaml`` describing your structure:
+Structure your research data analysis repository into input "data" and
+"parameters", runtime "code", computing "environments", and computational
+"workflows", following the model of the :ref:`fourquestions`. Create
+``reana.yaml`` describing your structure:
 
 .. code-block:: yaml
 
     version: 0.3.0
-    code:
-      files:
-      - code/mycode.py
     inputs:
       files:
-        - inputs/mydata.csv
+        - code/mycode.py
+        - data/mydata.csv
       parameters:
         myparameter: myvalue
-    environments:
-      - type: docker
-        image: johndoe/mypython:1.0
     workflow:
       type: cwl
       file: workflow/myworkflow.cwl
     outputs:
       files:
-      - outputs/myplot.png
+        - results/myplot.png
 
-(see :ref:`examples`)
+See and run some :ref:`examples`.
 
 Step Two: Install REANA cluster
 -------------------------------
@@ -65,14 +61,9 @@ You can also easily deploy your own REANA cloud instance by using the
    $ # set environment variables for reana-client
    $ eval $(reana-cluster env --incude-admin-token) # if you are admin
 
-.. warning::
-
-    We are using the ``--incude-admin-token`` in this case to make getting
-    started easier but this option should be used carefully and never shared
-    with regular users.
-
-(see `REANA-Cluster's Getting started guide
-<http://reana-cluster.readthedocs.io/en/latest/gettingstarted.html>`_)
+See `REANA-Cluster's Getting started guide
+<http://reana-cluster.readthedocs.io/en/latest/gettingstarted.html>`_ for more
+information.
 
 Step Three: Run REANA client
 ----------------------------
@@ -82,24 +73,26 @@ command line client:
 
 .. code-block:: console
 
-   $ # install reana-client
+   $ # install REANA client
    $ mkvirtualenv reana-client
    $ pip install reana-client
-   $ reana-client ping
    $ # create new workflow
-   $ export REANA_WORKON=$(reana-client create)
-   $ # upload runtime code and inputs
+   $ reana-client create -n my-analysis
+   $ export REANA_WORKON=my-analysis
+   $ # upload input code and data to the workspace
    $ reana-client upload
-   $ # start workflow and check progress
+   $ # start computational workflow
    $ reana-client start
+   $ # check its progress
    $ reana-client status
-   $ # list files
+   $ # list workspace files
    $ reana-client list
-   $ # download outputs
+   $ # download output results
    $ reana-client download
 
-(see `REANA-Client's Getting started guide
-<http://reana-client.readthedocs.io/en/latest/gettingstarted.html>`_)
+See `REANA-Client's Getting started guide
+<http://reana-client.readthedocs.io/en/latest/gettingstarted.html>`_ for more
+information.
 
 Next steps
 ----------