[general][doc] Mostly edited or added text to change what is written for...

[general][doc] Mostly edited or added text to change what is written for platform to general beat system. Fixes on the titles. Edited the conf.py to fix the problem with command-output

doc/beat/algorithms.rst

@@ -3,7 +3,7 @@
 .. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/          ..
 .. Contact: beat.support@idiap.ch                                             ..
 ..                                                                            ..
-.. This file is part of the beat.core module of the BEAT platform.            ..
+.. This file is part of the beat.docs module of the BEAT platform.            ..
 ..                                                                            ..
 .. Commercial License Usage                                                   ..
 .. Licensees holding valid commercial BEAT licenses may use this file in      ..
@@ -21,7 +21,7 @@
 .. with the BEAT platform. If not, see http://www.gnu.org/licenses/.          ..
 
 
-.. _beat-core-algorithms:
+.. _beat-system-algorithms:
 
 ===========
 Algorithms
@@ -49,7 +49,7 @@ covers a huge range of possible scenarios.
 :numref:`beat-core-overview-block` displays the relationship between a
 processing block and its algorithm.
 
-.. _beat-core-overview-block:
+.. _beat-system-overview-block:
 .. figure:: ./img/block.*
 
    Relationship between a processing block and its algorithm
@@ -58,7 +58,7 @@ This section contains information on the definition of algorithm and
 its programmatic use on Python-based language bindings.
 
 
-.. _beat-core-algorithms-definition:
+.. _beat-system-algorithms-definition:
 
 Definition
 ----------
@@ -72,7 +72,7 @@ An algorithm is defined by two distinct components:
   data.
 
 
-.. _beat-core-algorithms-definition-json:
+.. _beat-system-algorithms-definition-json:
 
 JSON Declaration
 ................
@@ -127,7 +127,7 @@ The web client of the BEAT platform provides a graphical editor for algorithm,
 which simplifies its `JSON`_ declaration definition.
 
 
-.. _beat-core-algorithms-definition-analyzer:
+.. _beat-system-algorithms-definition-analyzer:
 
 Analyzer
 ........
@@ -191,7 +191,7 @@ generates an ROC curve as well as few other metrics.
     }
 
 
-.. _beat-core-algorithms-definition-code:
+.. _beat-system-algorithms-definition-code:
 
 Source Code
 ...........
@@ -207,12 +207,12 @@ To implement a new algorithm, one must write a class following a few
 conventions. In the following, examples of such classes are provided.
 
 
-.. _beat-core-algorithms-examples:
+.. _beat-system-algorithms-examples:
 
 Examples
 --------
 
-.. _beat-core-algorithms-examples-simple:
+.. _beat-system-algorithms-examples-simple:
 
 Simple algorithm (no parametrization)
 .....................................
@@ -240,7 +240,7 @@ The platform will call this method once per block of data available on the
 `synchronized` inputs of the block.
 
 
-.. _beat-core-algorithms-examples-parametrizable:
+.. _beat-system-algorithms-examples-parametrizable:
 
 Parametrizable algorithm
 ........................
@@ -283,12 +283,12 @@ When retrieving the value of the parameters, one must not assume that a value
 was provided for each parameter. This is why we may use a *try: ... except: ...*
 construct in the ``setup()`` method.
 
-.. _beat-core-algorithms-input:
+.. _beat-system-algorithms-input:
 
 Handling input data
 -------------------
 
-.. _beat-core-algorithms-input-inputlist:
+.. _beat-system-algorithms-input-inputlist:
 
 Input list
 ..........
@@ -321,7 +321,7 @@ Additionally, the following method is useable on a **list of inputs**:
     the inputs
 
 
-.. _beat-core-algorithms-input-input:
+.. _beat-system-algorithms-input-input:
 
 Input
 .....
@@ -348,7 +348,7 @@ Each input provides the following informations:
 The structure of the ``data`` object is dependent of the data format assigned to
 the input. Note that ``data`` can be *None*.
 
-.. _beat-core-algorithms-input-name:
+.. _beat-system-algorithms-input-name:
 
 Input naming
 ............
@@ -375,7 +375,7 @@ block. As long as the set of data types (on the inputs and outputs) is
 compatible for both the block and the algorithm, the algorithm can be used in
 the block.
 
-.. _beat-core-algorithms-input-naming:
+.. _beat-system-algorithms-input-naming:
 .. figure:: ./img/inputs-naming.*
 
    Different toolchains, but interchangeable algorithms
@@ -403,7 +403,7 @@ such as:
     }
 
 
-.. _beat-core-algorithms-input-synchronization:
+.. _beat-system-algorithms-input-synchronization:
 
 Inputs synchronization
 ......................
@@ -428,14 +428,14 @@ list of inputs has two attributes (``current_data_index`` and
 ``current_end_data_index``) that indicates the data indexes currently used by
 the synchronization mechanism of the platform.
 
-.. _beat-core-algorithms-input-synchronization-example:
+.. _beat-system-algorithms-input-synchronization-example:
 .. figure:: ./img/inputs-synchronization.*
    :width: 80%
 
    Synchronization example
 
 
-.. _beat-core-algorithms-input-unsynchronized:
+.. _beat-system-algorithms-input-unsynchronized:
 
 Additional input methods for unsynchronized channels
 ....................................................
@@ -541,7 +541,7 @@ keeps the others synchronized and iterate over all their data:
             return True
 
 
-.. _beat-core-algorithms-input-feedbackloop:
+.. _beat-system-algorithms-input-feedbackloop:
 
 Feedback inputs
 ...............
@@ -554,18 +554,18 @@ freely used by the algorithm.
 Those feedback inputs aren't yet implemented in the prototype of the platform.
 This will be addressed in a later version.
 
-.. _beat-core-algorithms-input-feedbackloop-example:
+.. _beat-system-algorithms-input-feedbackloop-example:
 .. figure:: ./img/feedback-loop.*
 
     Feedback loop
 
 
-.. _beat-core-algorithms-output:
+.. _beat-system-algorithms-output:
 
 Handling output data
 --------------------
 
-.. _beat-core-algorithms-output-outputlist:
+.. _beat-system-algorithms-output-outputlist:
 
 Output list
 ...........
@@ -591,7 +591,7 @@ or by iterating over the list:
         output.write(...)
 
 
-.. _beat-core-algorithms-output-output:
+.. _beat-system-algorithms-output-output:
 
 Output
 ......
@@ -623,7 +623,7 @@ We'll look at the usage of those methods through some examples in the following
 sections.
 
 
-.. _beat-core-algorithms-output-name:
+.. _beat-system-algorithms-output-name:
 
 Output naming
 .............
@@ -656,12 +656,12 @@ including them in the JSON declaration of the algorithm.
     }
 
 
-.. _beat-core-algorithms-output-example1:
+.. _beat-system-algorithms-output-example1:
 
 Example 1: Write one block of data for each received block of data
 ..................................................................
 
-.. _beat-core-algorithms-output-example1-figure:
+.. _beat-system-algorithms-output-example1-figure:
 .. figure:: ./img/outputs-example1.*
 
    Example 1: 6 images as input, 6 blocks of data produced
@@ -719,12 +719,12 @@ The structure of the ``data`` object is dependent of the data format assigned
 to the output.
 
 
-.. _beat-core-algorithms-output-example2:
+.. _beat-system-algorithms-output-example2:
 
 Example 2: Skip some blocks of data
 ...................................
 
-.. _beat-core-algorithms-output-example2-figure:
+.. _beat-system-algorithms-output-example2-figure:
 .. figure:: ./img/outputs-example2.*
 
    Example 2: 6 images as input, 4 blocks of data produced, 2 blocks of data
@@ -790,12 +790,12 @@ available.
             return True # or False
 
 
-.. _beat-core-algorithms-output-example3:
+.. _beat-system-algorithms-output-example3:
 
 Example 3: Write one block of data related to several received blocks of data
 .............................................................................
 
-.. _beat-core-algorithms-output-example3-figure:
+.. _beat-system-algorithms-output-example3-figure:
 .. figure:: ./img/outputs-example3.*
 
    Example 3: 6 images as input, 2 blocks of data produced

doc/beat/dataformats.rst

@@ -3,7 +3,7 @@
 .. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/          ..
 .. Contact: beat.support@idiap.ch                                             ..
 ..                                                                            ..
-.. This file is part of the beat.core module of the BEAT platform.            ..
+.. This file is part of the beat.docs module of the BEAT platform.            ..
 ..                                                                            ..
 .. Commercial License Usage                                                   ..
 .. Licensees holding valid commercial BEAT licenses may use this file in      ..
@@ -21,11 +21,11 @@
 .. with the BEAT platform. If not, see http://www.gnu.org/licenses/.          ..
 
 
-.. _beat-core-dataformats:
+.. _beat-system-dataformats:
 
-=============
-Data formats
-=============
+==============
+ Data formats
+==============
 
 Data formats formalize the interaction between algorithms and data sets, so
 they can communicate data in an orderly manner. All data formats produced or
@@ -61,7 +61,7 @@ region in an image:
 
 .. note::
 
-   We have chosen to define objects inside the BEAT platform using JSON
+   We have chosen to define objects inside the BEAT using JSON
    declarations as JSON files can be easily validated, transferred through
    web-based APIs and provide and easy to read format for local inspection.
 
@@ -103,21 +103,21 @@ informational purposes.
 
 Each field in a declaration has a well-defined type, which can be one of:
 
-  * a primitive, simple type (see :ref:`beat-core-dataformats-simple`)
-  * a directly nested object (see :ref:`beat-core-dataformats-complex`)
-  * another data format (see :ref:`beat-core-dataformats-aggregation`)
-  * an array (see :ref:`beat-core-dataformats-array`)
+  * a primitive, simple type (see :ref:`beat-system-dataformats-simple`)
+  * a directly nested object (see :ref:`beat-system-dataformats-complex`)
+  * another data format (see :ref:`beat-system-dataformats-aggregation`)
+  * an array (see :ref:`beat-system-dataformats-array`)
 
 A data format can also extend another one, as explained further down (see
-ref:`beat-core-dataformats-extension`).
+ref:`beat-system-dataformats-extension`).
 
 
-.. _beat-core-dataformats-simple:
+.. _beat-system-dataformats-simple:
 
 Simple types
 ------------
 
-The following primitive data types are available in the BEAT platform:
+The following primitive data types are available in the BEAT:
 
   * Integers: ``int8``, ``int16``, ``int32``, ``int64``
   * Unsigned integers: ``uint8``, ``uint16``, ``uint32``, ``uint64``
@@ -131,7 +131,7 @@ The following primitive data types are available in the BEAT platform:
    All primitive types are implemented using their :py:mod:`numpy`
    counterparts.
 
-When determining if a block of data corresponds to a data format, the platform
+When determining if a block of data corresponds to a data format, the system
 will check that the value of each field can safely (without loss of precision)
 be converted to the type declared by the data format. An error is generated if
 you fail to follow these requirements.
@@ -144,7 +144,7 @@ allow for a precision loss on your code, you must do it explicitly (`Zen of
 Python`_).
 
 
-.. _beat-core-dataformats-complex:
+.. _beat-system-dataformats-complex:
 
 Complex types
 -------------
@@ -166,7 +166,7 @@ The coordinates of a rectangular region in an image be represented like this:
     }
 
 
-.. _beat-core-dataformats-aggregation:
+.. _beat-system-dataformats-aggregation:
 
 Aggregation
 -----------
@@ -215,7 +215,7 @@ for describing a rectangle:
     }
 
 
-.. _beat-core-dataformats-array:
+.. _beat-system-dataformats-array:
 
 Arrays
 ------
@@ -281,14 +281,14 @@ the preceding one isn't fixed too):
 .. note::
 
    When determining if that a block of data corresponds to a data format
-   containing an array, the platform automatically checks that:
+   containing an array, the system automatically checks that:
 
      * the number of dimensions is correct
      * the size of each declared dimension that isn't 0 is correct
      * the type of each value in the array is correct
 
 
-.. _beat-core-dataformats-extension:
+.. _beat-system-dataformats-extension:
 
 Extensions
 ----------
@@ -311,7 +311,7 @@ extending the type ``user/rectangular_area/1`` defined earlier:
     }
 
 
-.. _beat-core-dataformats-usage:
+.. _beat-system-dataformats-usage:
 
 Python API
 ----------

doc/beat/experiments.rst

@@ -3,7 +3,7 @@
 .. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/          ..
 .. Contact: beat.support@idiap.ch                                             ..
 ..                                                                            ..
-.. This file is part of the beat.core module of the BEAT platform.            ..
+.. This file is part of the beat.docs module of the BEAT platform.            ..
 ..                                                                            ..
 .. Commercial License Usage                                                   ..
 .. Licensees holding valid commercial BEAT licenses may use this file in      ..
@@ -21,11 +21,11 @@
 .. with the BEAT platform. If not, see http://www.gnu.org/licenses/.          ..
 
 
-.. _beat-core-experiments:
+.. _beat-system-experiments:
 
-============
-Experiments
-============
+=============
+ Experiments
+=============
 
 An experiment is the reunion of algorithms, datasets, a toolchain and
 parameters that allow the platform to schedule and run the prescribed recipe
@@ -33,7 +33,7 @@ to produce displayable results. Defining a BEAT experiment can be seen as
 configuring the processing blocks of a toolchain, such as selecting which
 database, algorithms and algorithm parameters to use.
 
-.. _beat-core-experiments-declaration:
+.. _beat-system-experiments-declaration:
 
 Declaration of an experiment
 ----------------------------
@@ -62,7 +62,7 @@ fields:
     }
 
 
-.. _beat-core-experiments-datasets:
+.. _beat-system-experiments-datasets:
 
 Declaration of the dataset(s)
 -----------------------------
@@ -97,7 +97,7 @@ from the toolchain. Then, three fields must be given:
   dataset
 
 
-.. _beat-core-experiments-blocks:
+.. _beat-system-experiments-blocks:
 
 Declaration of the block(s)
 ---------------------------
@@ -149,7 +149,7 @@ toolchain. Then, four fields must be given:
    consecutive blocks are compatible.
 
 
-.. _beat-core-experiments-analyzers:
+.. _beat-system-experiments-analyzers:
 
 Declaration of the analyzer(s)
 ------------------------------

doc/beat/index.rst

@@ -3,7 +3,7 @@
 .. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/          ..
 .. Contact: beat.support@idiap.ch                                             ..
 ..                                                                            ..
-.. This file is part of the beat.core module of the BEAT platform.            ..
+.. This file is part of the beat.docs module of the BEAT platform.            ..
 ..                                                                            ..
 .. Commercial License Usage                                                   ..
 .. Licensees holding valid commercial BEAT licenses may use this file in      ..
@@ -59,7 +59,6 @@ known applications:
 
 .. toctree::
 
-    install
     introduction
     dataformats
     algorithms
@@ -68,7 +67,7 @@ known applications:
     experiments
     databases
     io
-
+    install
 
 Indices and tables
 ==================
@@ -76,3 +75,7 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+
+.. include:: links.rst
+

doc/beat/install.rst

@@ -50,5 +50,8 @@ Requirements
 #. Firefox or Chrome browser
 #. Docker installed and available to the current user (not strictly necessary)
 
+.. include:: links.rst
+
+
 
 

doc/beat/introduction.rst

@@ -3,7 +3,7 @@
 .. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/          ..
 .. Contact: beat.support@idiap.ch                                             ..
 ..                                                                            ..
-.. This file is part of the beat.core module of the BEAT platform.            ..
+.. This file is part of the beat.docs module of the BEAT platform.            ..
 ..                                                                            ..
 .. Commercial License Usage                                                   ..
 .. Licensees holding valid commercial BEAT licenses may use this file in      ..
@@ -21,37 +21,12 @@
 .. with the BEAT platform. If not, see http://www.gnu.org/licenses/.          ..
 
 
-.. _beat-introduction:
-
-=============
-Introduction
-=============
-
-The BEAT platform is a web-based system for certifying results for
-software-based data-driven workflows that can be sub-divided functionally (into
-processing blocks). 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 user provides the
-description of data formats, algorithms, data flows (also known as toolchains)
-and experimental details (parameters), which are mashed inside the platform to
-produce beautiful results, easily exportable into computer graphics or tables
-for scientific reports.
-
-It 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.
-
-This package, in particular, defines a set of core components useful for the
-whole platform: the building blocks used by all other packages in the BEAT
+.. _beat-system:
+
+==============
+ Introduction
+==============
+The Beat system has certain building blocks used by all the packages in the BEAT
 software suite. These are:
 
 * **Data formats**: the specification of data which is transmitted between
@@ -64,11 +39,11 @@ software suite. These are:
   into a toolchain, respecting a certain usage protocol;
 * **Toolchain**: the definition of the data flow in an experiment;
 * **Experiment**: the reunion of algorithms, datasets, a toolchain and
-  parameters that allow the platform to schedule and run the prescribed recipe
+  parameters that allow the system to run the prescribed recipe
   to produce displayable results.
 
 
-.. _beat-core-introduction-example:
+.. _beat-system-example:
 
 A Simple Example
 ----------------
@@ -84,7 +59,7 @@ only a few color-coded components:
   ``echo3``;
 * The final component receives the inputs emitted from ``echo3`` and it is
   called ``analysis``. Because this block has no output, it is considered a
-  final block, from which the BEAT platform expects to collect experiment
+  final block, from which the BEAT expects to collect experiment
   results (that, at this point, are also unspecified).
 
 .. Simple toolchain representation for the BEAT platform
@@ -100,7 +75,7 @@ may yield data in parallel, allowing the execution of blocks ``echo1`` and
 ``echo2``. Block ``echo3`` must come next, before the ``analysis`` block, which
 comes by last.
 
-In typical problems that can be implemented in the BEAT platform, datasets are
+In typical problems that can be implemented in the BEAT, datasets are
 composed of multiple instances of raw data. For example, these could be images
 for an object recognition problem, speech sequences for a speech recognition
 task or model data for biometric recognition tasks. Computing blocks must
@@ -143,7 +118,7 @@ experimental setup.
 .. graphviz:: img/experiment-triangle.dot
 
 
-.. _beat-core-introduction-design:
+.. _beat-system-design:
 
 Design
 ------
@@ -197,12 +172,14 @@ objects in the platform. In the example above, you can identify some examples.
 
 
 The BEAT platform provides a graphical user interface so that you can program
-data formats, algorithms, toolchains and define experiments rather intuitively.
-This package provides the core building blocks of the BEAT platform. For expert
-users, we provide a command-line interface to the platform, allowing such
-users to create, modify and dispose of such objects using their own private
-editors. For developers and programmers, the rest of this guide details each of
-those building blocks, their relationships and how to use such a command-line
+data formats, algorithms, toolchains and define experiments rather intuitively. 
+For expert users, we provide a command-line interface to the platform, allowing
+such users to create, modify and dispose of such objects using their own private
+editors. When using BEAT locally the graphical user interface is used in parallel 
+with the command-line interface.  
+
+For developers and programmers, the rest of this guide details each of
+BEAT building blocks, their relationships and how to use such a command-line
 interface to interact with the platform efficiently.
 
 

doc/beat/libraries.rst

@@ -3,7 +3,7 @@
 .. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/          ..
 .. Contact: beat.support@idiap.ch                                             ..
 ..                                                                            ..
-.. This file is part of the beat.core module of the BEAT platform.            ..
+.. This file is part of the beat.docs module of the BEAT platform.            ..
 ..                                                                            ..
 .. Commercial License Usage                                                   ..
 .. Licensees holding valid commercial BEAT licenses may use this file in      ..
@@ -21,11 +21,11 @@
 .. with the BEAT platform. If not, see http://www.gnu.org/licenses/.          ..
 
 
-.. _beat-core-libraries:
+.. _beat-system-libraries:
 
-==========
-Libraries
-==========
+===========
+ Libraries
+===========
 
 Algorithms are fundamental elements in the platform that formally describe how
 to process data. In particular, they are always attached to a specific

doc/beat/toolchains.rst

@@ -3,7 +3,7 @@
 .. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/          ..
 .. Contact: beat.support@idiap.ch                                             ..
 ..                                                                            ..
-.. This file is part of the beat.core module of the BEAT platform.            ..
+.. This file is part of the beat.docs module of the BEAT platform.            ..
 ..                                                                            ..
 .. Commercial License Usage                                                   ..
 .. Licensees holding valid commercial BEAT licenses may use this file in      ..
@@ -21,11 +21,11 @@
 .. with the BEAT platform. If not, see http://www.gnu.org/licenses/.          ..
 
 
-.. _beat-core-toolchains:
+.. _beat-system-toolchains:
 
-===========
-Toolchains
-===========
+============
+ Toolchains
+============
 
 A toolchain describes the workflow of a particular experiment. Its declaration
 defines:
@@ -41,7 +41,7 @@ defines:
   * a list of *result outputs*, that produce the results of the experiment
 
 
-.. _beat-core-toolchains-declaration:
+.. _beat-system-toolchains-declaration:
 
 Declaration of a toolchain
 --------------------------
@@ -78,7 +78,7 @@ For display purposes, the JSON file may contain an additional field called
 a graphical way.
 
 
-.. _beat-core-toolchains-datasets:
+.. _beat-system-toolchains-datasets:
 
 Declaration of the datasets
 ---------------------------
@@ -130,7 +130,7 @@ mentioned above, this would look like:
     }
 
 
-.. _beat-core-toolchains-blocks:
+.. _beat-system-toolchains-blocks:
 
 Declaration of the processing blocks
 ------------------------------------
@@ -200,7 +200,7 @@ As with the datasets, to define more blocks just add more entries into the
     }
 
 
-.. _beat-core-toolchains-connections:
+.. _beat-system-toolchains-connections:
 
 Declaration of the connections between the processing blocks
 ------------------------------------------------------------
@@ -273,7 +273,7 @@ Several important things to note:
     toolchain
 
 
-.. _beat-core-toolchains-results:
+.. _beat-system-toolchains-results:
 
 Declaration of the outputs to use as results
 --------------------------------------------
@@ -307,12 +307,12 @@ The data written on those `inputs` will be used to display results and plots
 on the web interface.
 
 
-.. _beat-core-toolchains-example:
+.. _beat-system-toolchains-example:
 
 Putting it all together: a complete example
 -------------------------------------------
 
-.. _beat-core-toolchains-example-figure:
+.. _beat-system-toolchains-example-figure:
 .. figure:: img/toolchain-example-2.*
 
    A complete toolchain that train and test an Eigenfaces system

doc/conf.py

@@ -26,7 +26,8 @@ extensions = [
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
     'sphinx.ext.mathjax',
-    'matplotlib.sphinxext.plot_directive'
+    'matplotlib.sphinxext.plot_directive',
+    'sphinxcontrib.programoutput'
     ]
 
 # matplotlib.sphinxext.plot_directive