Commit da6f035b authored by André Anjos's avatar André Anjos 💬

Merge branch 'docedit' into 'master'

merges new documentation to master

See merge request !34
parents ed21420b dc78eb61
Pipeline #25509 passed with stages
in 47 minutes and 49 seconds
.. _beat-editor-development:
=============
Development
......@@ -5,9 +6,71 @@
This section is a compilation of notes and advice about how to develop the ``beat.editor`` project, aimed at those less familiar with web development but familiar with Python.
Important Concepts
Preparing the package for development
=====================================
The requirements for installing and preparing the ``beat.editor`` package for development are as following:
#. Linux or MacOS
#. Working internet connection
#. Useable Conda setup (see `Bob's documentation on it <https://www.idiap.ch/software/bob/docs/bob/bob/master/install.html>`_)
#. Up-to-date Firefox and Chrome browsers (both need headless support, a relatively recent feature)
#. Docker installed and available to the current user
#. A relatively recent version of `NodeJS & NPM <http://nodejs.org/>`_.
Installation Steps
------------------
#. Clone the ``beat.editor`` repository: ::
$ git clone git@gitlab.idiap.ch:beat/beat.editor.git
#. Clone the ``bob.admin`` repository, necessary for building a development Conda environment: ::
$ git clone git@gitlab.idiap.ch:bob/bob.admin.git
#. Use ``bob.admin`` to create a development Conda environment named ``beatedit`` for Python 3.6: ::
$ conda activate base
$ conda install pyyaml # install a dependency that isn't fetched by default
$ cd beat.editor
$ ../bob.admin/conda/conda-bootstrap.py --overwrite --python=3.6 beatedit
#. Activate the created environment and use the ``buildout`` command from ``bob.buildout`` in the new environment to generate the executables for ``beat.editor``: ::
$ conda activate beatedit
$ buildout
#. Note for development mode: Add the line ``dependent-scripts = true`` then use the ``buildout`` command to ensure to generate all the executables in the ``bin/``
folder even ``beat`` for ``beat.editor``: ::
$ buildout
#. In ``bin/`` you should several new executables for the project. The Python setup part is done.
#. Go into the root folder for the Javascript and install the dependencies via NPM: ::
$ cd conda/js
$ npm install
#. Test the JS to make sure everything is working properly: ::
$ npm test
#. Assuming the tests pass, you can start the development webpack server: ::
$ npm start
#. In a separate terminal tab/window, go back to the root of the ``beat.editor`` project and run the web server in development mode: ::
$ ./bin/beat editor serve --dev
#. You should now be able to go ``localhost:9101`` in your browser to see the ``beat.editor`` web app, now served by the webpack dev server.
Important Concepts
==================
Before developing for ``beat.editor``, you'll need to familiarize yourself with at least the following concepts/tools:
* Flask & RESTful APIs
......
......@@ -27,11 +27,14 @@
Local Editor for BEAT Objects
===============================
This package provides a web server to manage and edit BEAT objects locally. The users can make new objects or new versions of existing ones using the graphical interface provided by this server and the editor produces the correct JSON_ format for the corresponding objects. In case of new objects it also provides a Python template as well. This is the package used as the graphical interface in
`A Hands On Tutorial <https://www.idiap.ch/software/beat/docs/beat/docs/master/beat/user.html>`_.
In the following sections different parts of the graphical interface will be explained in details. The developers interested in developing this package can find the information in :ref:`beat-editor-development`.
.. toctree::
install
user
editor
development
......@@ -42,3 +45,7 @@ Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. include:: links.rst
==============
Installation
==============
This section includes information for installing ``beat.editor`` a couple different ways.
Method 1: Virtualbox Image (easiest)
====================================
This method is the easiest - one command will generate a new Virtualbox image with ``beat.editor`` installed.
Requirements
------------
#. Working internet connection
#. `Virtualbox <https://www.virtualbox.org/>`_ installed and working (might need configuration)
#. `Packer <https://www.packer.io/>`_ installed
#. About 3G of disk space (at the time of writing, 2.7G needed)
#. Git
Installation Steps
------------------
#. Clone the repository holding the scripts: ::
$ git clone https://gitlab.idiap.ch/beat/beat.tutorial.git
#. Checkout the Git branch containing the packer scripts: ::
$ git checkout june-allies
#. Change directory to the folder holding the scripts: ::
$ cd beat.tutorial/packer_scripts
#. Generate the Virtualbox image: ::
$ packer-io build ubuntu-18.04-beat.json
This will generate the OVF file in ``packer_scripts/output-virtualbox-iso``.
To use this OVF file in the Virtualbox GUI, select "Import Appliance" under the "File" menu in Virtualbox and choose to import the OVF file.
The username and password for the image are both ``beat``.
The BEAT commands, ``beat`` and ``beat editor serve``, should be available in the shell in the VM. The Firefox browser is available, as is the Vim, Emacs, Nano, and Gedit editors.
Method 2: Conda (easyish)
=========================
This method integrates with one of your Conda environments' packages on your local machine, but has more strict requirements.
Requirements
------------
#. Linux or MacOS (Docker features not available on MacOS for now)
#. Working internet connection
#. Useable Conda setup (see `Bob's documentation on it <https://www.idiap.ch/software/bob/docs/bob/bob/master/install.html>`_)
#. Firefox or Chrome browser
#. Docker installed and available to the current user (not strictly necessary)
Installation Steps
------------------
#. Activate the Conda environment you will be adding ``beat.editor`` to
#. Due to the current development state of this project you need to add these two Conda channels: ::
$ conda config --env --add channels https://www.idiap.ch/software/beat/conda/label/beta
$ conda config --env --add channels https://www.idiap.ch/software/beat/conda
Note: once this package released only the second channel will be required
#. Install the ``beat.editor`` package: ::
$ conda install beat.editor
#. The BEAT commands, ``beat`` and ``beat editor serve``, should be available.
Method 3: For developers
========================
This method is for developers looking to work on ``beat.editor``.
Requirements
------------
#. Linux or MacOS
#. Working internet connection
#. Useable Conda setup (see `Bob's documentation on it <https://www.idiap.ch/software/bob/docs/bob/bob/master/install.html>`_)
#. Up-to-date Firefox and Chrome browsers (both need headless support, a relatively recent feature)
#. Docker installed and available to the current user
#. A relatively recent version of `NodeJS & NPM <http://nodejs.org/>`_.
Installation Steps
------------------
#. Clone the ``beat.editor`` repository: ::
$ git clone git@gitlab.idiap.ch:beat/beat.editor.git
#. Clone the ``bob.admin`` repository, necessary for building a development Conda environment: ::
$ git clone git@gitlab.idiap.ch:bob/bob.admin.git
#. Use ``bob.admin`` to create a development Conda environment named ``beatedit`` for Python 3.6: ::
$ conda activate base
$ conda install pyyaml # install a dependency that isn't fetched by default
$ cd beat.editor
$ ../bob.admin/conda/conda-bootstrap.py --overwrite --python=3.6 beatedit
#. Activate the created environment and use the ``buildout`` command from ``bob.buildout`` in the new environment to generate the executables for ``beat.editor``: ::
$ conda activate beatedit
$ buildout
#. Note for development mode: Add the line ``dependent-scripts = true`` then use the ``buildout`` command to ensure to generate all the executables in the ``bin/``
folder even ``beat`` for ``beat.editor``: ::
$ buildout
#. In ``bin/`` you should several new executables for the project. The Python setup part is done.
#. Go into the root folder for the Javascript and install the dependencies via NPM: ::
$ cd conda/js
$ npm install
#. Test the JS to make sure everything is working properly: ::
$ npm test
#. Assuming the tests pass, you can start the development webpack server: ::
$ npm start
#. In a separate terminal tab/window, go back to the root of the ``beat.editor`` project and run the web server in development mode: ::
$ ./bin/beat editor serve --dev
#. You should now be able to go ``localhost:9101`` in your browser to see the ``beat.editor`` web app, now served by the webpack dev server.
.. automodule:: beat.editor
.. Place your links here
.. _beat: https://www.idiap.ch/software/beat
.. _docker: https://www.docker.com/
.. _reproducible research: https://reproducibleresearch.net/
.. _numpy safe-casting rules: http://docs.scipy.org/doc/numpy/reference/generated/numpy.can_cast.html
.. _zen of python: https://www.python.org/dev/peps/pep-0020/
.. _json: http://en.wikipedia.org/wiki/JSON
.. _beat.env.python27: http://gitlab.idiap.ch/biometric/beat.env.python27
.. _beat.backend.python: http://gitlab.idiap.ch/biometric/beat.backend.python
.. _python 2.7: http://www.python.org
.. _zero message queue: http://zeromq.org
.. _zmq: http://zeromq.org
.. _language bindings: http://zeromq.org/bindings:_start
.. _python bindings: http://zeromq.org/bindings:python
.. _markdown: http://daringfireball.net/projects/markdown/
.. _restructuredtext: http://docutils.sourceforge.net/rst.html
.. _conda: https://conda.io/
.. _beat editor: https://www.idiap.ch/software/beat/docs/beat/docs/new/beat.editor/doc/index.html
.. _bob: https://www.idiap.ch/software/bob/docs/bob/docs/stable/bob/doc/index.html
.. _idiap: http://www.idiap.ch
.. _eigenface: https://en.wikipedia.org/wiki/Eigenface
\ No newline at end of file
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment