[general][doc] rearanging the sections for documentation and added installation instruction

doc/beat/index.rst

@@ -27,12 +27,37 @@
  BEAT
 ======
 
-This user guide contains information about BEAT core components, defining
-experiments, toolchains and user algorithms among others.
+The BEAT is a system for computing and certifying results for
+software-based data-driven workflows that can be sub-divided functionally (into
+processing blocks). The user provides the
+description of data formats, algorithms, data flows (also known as toolchains)
+and experimental details (parameters), which are used to
+produce beautiful results, easily exportable into computer graphics or tables
+for scientific reports.
+
+The BEAT system can be used locally that gives freedom to the user for developing
+new algorithms or on a web-based platform with higher processing power. The platform takes all burden of hosting data and software
+away from users by providing a capable computing farm that handles both aspects
+graciously. Data is kept sequestered inside the platform. 
+
+The BEAT is intended as a fundamental building-block in `Reproducible Research`_,
+allowing academic and industrial parties to prescribe system behavior and have
+it reproducible through software, hardware and staff generations. Here are some
+known applications:
+
+* Challenges and competitions on defined data, protocols and workflow
+  components;
+* Study group exercises and exams;
+* Support to publication submission;
+* System and algorithm performance optimization;
+* Reproduction of experiments through communities;
+* Support for industry-academy relationship.
+
 
 
 .. toctree::
 
+    install
     introduction
     dataformats
     algorithms
@@ -41,9 +66,6 @@ experiments, toolchains and user algorithms among others.
     experiments
     databases
     io
-    backend_api
-    develop
-    api
 
 
 Indices and tables

doc/beat/install.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _beat-installation:
+
+
+==============
+ Installation Instructions
+==============
+
+The BEAT is available as conda packages for linux and MacOS for locall usage. 
+
+#.  Please install `conda`_ (miniconda is preferred) and get familiar with it.
+#.  Make sure you have an up-to-date `conda`_ installation (conda 4.4 and above
+    is needed) with the **correct configuration** by running the commands
+    below:
+
+    .. code:: sh
+
+       $ conda update -n base conda
+       $ conda config --set show_channel_urls True
+
+#.  Create an environment for BEAT:
+
+    .. code:: sh
+
+       $ conda create --name beat_py3 --override-channels \
+         -c https://www.idiap.ch/software/beat/conda -c defaults \
+         python=3 bob beat.core beat.cmdline beat.backend.python beat.editor
+       $ conda activate beat_py3
+       $ conda config --env --add channels defaults
+       $ conda config --env --add channels https://www.idiap.ch/software/bob/conda
+       $ conda config --env --add channels https://www.idiap.ch/software/beat/conda
+
+#.	Install other packages that you need in that environement:
+    .. code:: sh
+
+       $ conda install bob.ip.base bob.db.atnt ..
+
+#. The BEAT commands, ``beat`` and ``beat editor serve``, should be available.
+
+**Repeat the last three steps for every conda environment that you create for
+BEAT.**
+
+You are almost ready to design your experiment in BEAT. There are a few more requirements.
+
+Requirements
+------------
+
+#. Working internet connection
+#. Firefox or Chrome browser
+#. Docker installed and available to the current user (not strictly necessary)
+
+
+

doc/beat/introduction.rst

@@ -21,7 +21,7 @@
 .. with the BEAT platform. If not, see http://www.gnu.org/licenses/.          ..
 
 
-.. _beat-core-introduction:
+.. _beat-introduction:
 
 =============
 Introduction

[Amir MOHAMMADI]

@zmostaani you have to make sure the = signs are as many as the title

[Zohreh MOSTAANI]

I'll fix it. Thanks.

[André Anjos]

Actually, they have to be two longer (one in each side) for double-sided titles like these.

[Flavio TARSETTI]

André is correct to raise this one.

Have a look here https://gitlab.idiap.ch/beat/beat.core/blob/master/doc/algorithms.rst

There's this one extra = at the end up and down for double-sided titles for the "Algorithms" title

Don't forget to add them. It was nightmare adding them on all beat.* packages when I started working on this doc package to make sure sphinx doesn't have any issue with the doc generation...

Good luck 👍🏻

[Zohreh MOSTAANI]

Thanks for letting me know.