parts of walkthrough complete

doc/index.rst

@@ -43,6 +43,7 @@ implement more advanced functionality than this client (`beat`) provides.
     toolchains
     experiments
     databases
+    walkthrough
 
 Indices and tables
 ==================

doc/walkthrough.rst

+.. vim: set fileencoding=utf-8 :
+
+.. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/          ..
+.. Contact: beat.support@idiap.ch                                             ..
+..                                                                            ..
+.. This file is part of the beat.cmdline module of the BEAT platform.         ..
+..                                                                            ..
+.. Commercial License Usage                                                   ..
+.. Licensees holding valid commercial BEAT licenses may use this file in      ..
+.. accordance with the terms contained in a written agreement between you     ..
+.. and Idiap. For further information contact tto@idiap.ch                    ..
+..                                                                            ..
+.. Alternatively, this file may be used under the terms of the GNU Affero     ..
+.. Public License version 3 as published by the Free Software and appearing   ..
+.. in the file LICENSE.AGPL included in the packaging of this file.           ..
+.. The BEAT platform is distributed in the hope that it will be useful, but   ..
+.. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ..
+.. or FITNESS FOR A PARTICULAR PURPOSE.                                       ..
+..                                                                            ..
+.. You should have received a copy of the GNU Affero Public License along     ..
+.. with the BEAT platform. If not, see http://www.gnu.org/licenses/.          ..
+
+
+.. _beat-cmdline-walkthrough:
+
+Walkthrough
+-----------
+
+This page gives an overview on setting up an environment to develop BEAT
+experiments locally. The topics covered are the following:
+
+- Preparing a proper Python environment
+- Bootstrapping ``beat.cmdline``
+- Running the `BEAT Platform <https://gitlab.idiap.ch/beat/beat.web>`_ locally
+- Introducing a possible workflow for BEAT development
+
+Tips for preparing a proper environment
+.......................................
+
+- Using a `Conda <https://conda.io/docs/>`_ environment is recommended.
+- ``beat.cmdline`` requires Python 2.7 and will not work on Python 3.x.
+- It uses `Buildout <http://www.buildout.org/en/latest/>`_, to bootstrap,
+  commonly known as `zc.buildout`. This package is also available on Conda.
+- The Python 2.7 environment used for bootstrapping will also be the
+  environment used to execute BEAT code when using the local executor.
+- While you can bootstrap and use ``beat.cmdline`` without having a local
+  BEAT instance, ``beat`` can't yet create BEAT objects (experiments, etc.)
+  from scratch. We recommend you instead modify existing BEAT objects.
+
+Boostrapping ``beat.cmdline``
+.............................
+
+Thanks to Buildout, setup is simple:
+
+- Clone the ``beat.cmdline`` repository.
+- Using a compatible environment (see above) run ``buildout`` in the project's
+  root directory. Assuming this step is successful, the ``beat`` tool is now
+  functional.
+- To build this documentation locally, use the ``sphinx-build`` tool in
+  ``bin/``: ``./bin/sphinx-build doc/ sphinx/`` to output to ``sphinx/``.
+
+Running the BEAT Platform locally
+.................................
+
+
+