Commit 5a4d7eb2 authored by André Anjos's avatar André Anjos 💬
Browse files

Merge branch 'quick_start_guide' into 'master'

Quick start guide

See merge request !118
parents 218b415b f6114eae
Pipeline #37439 passed with stages
in 8 minutes and 12 seconds
* beat/beat.editor
* major release v1.0.0 :
- beat/beat.editor!27 Toolchain Editor UX Improvements: This is the MR for the similarly-named milestone (and the last milestone!)
- beat/beat.editor!35 Fix tests to run all tests: `Plotterparameter.spec.jsx` whitelisted its own tests, preventing any tests outside of that file being ran.
- beat/beat.editor!36 Alg editor form warning 162: The warning about proptypes no longer shows, wrapping the child components in a `<React.Fragment>` worked Fixes beat/beat.editor#162
- beat/beat.editor!38 Add templates for issues and MR: These template should be used when opening a new issue or merge request. There are two templates under issue: - Default.md which is a bug report - suggestion.md which is for suggestion to be implemented To use them, select the corresponding template in the dropdown beside the title of the issue/merge request. Only available once merge in the default branch.
- beat/beat.editor!40 [backend] Implement AssetModel class: Summary This patch implements the AssetModel class which can be used to retrieve a list available assets of one type. It can be used to, for example, populate combo boxes needing to show a list of dataformats. One such a case is the dataformat editor itself. Part of beat/beat.editor#186
- beat/beat.editor!43 fix misspelling of "unkown" -> "unknown": Summary Fixes misspelling of "unknown" in AssetType.py Relevant issue(s) fixed Fixes beat/beat.editor#190
- beat/beat.editor!41 server-side port config: Summary Adds the "--port" option to the server so it can serve the API on a different port number. Relevant issue(s) fixed Fixes beat/beat.editor#188
- beat/beat.editor!45 Fix pre-commit package name: Summary Fix name of pre-commit conda package in installation instruction. Relevant issue(s) fixed Fixes beat/beat.editor#189
- beat/beat.editor!39 Parameter testing: MR for beat/beat.editor#166 Note that tests have been added for everything except for `ParameterCreate`, which is added in this MR. This also fixes a bug with setting the default value for boolean parameter types.
- beat/beat.editor!44 Cleanup v1 artifacts: Summary Removes the rest of the artifacts from the v1 editor. Relevant issue(s) fixed Fixes beat/beat.editor#191
- beat/beat.editor!47 Add a "Copy Path" button to copy path to clipboard: Summary Adds a button to copy the object's absolute path on the filesystem to the clipboard. I tried to add more dynamic copying abilities, but you quickly run into having to ask the user for permissions, browser~version compatibility issues, and having to write/use a wrapper for the clipboard (see [the mozilla article on it](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard)). The button I added is something that I'd use alot - when I create/browse objects in the editor I almost always end up wanting to look at its files in the terminal, which requires the objects path. Relevant issue(s) fixed beat/beat.editor#104
- beat/beat.editor!49 Fix AssetModel initialisation: Summary Fix initialization of member variables
- beat/beat.editor!42 Toolchain blocks properly handle new input names: Summary Adding & changing inputs/outputs in toolchain blocks will work as expected without overwriting other names (see the issue for more) Relevant issue(s) fixed beat/beat.editor#176
- beat/beat.editor!50 Simplifies the CI of this package by re-using definitions in bob/bob.devtools (bdt): This update only brings the CI (`.gitlab-ci.yml`) file in sync with the rest of BEAT packages (using bob/bob.devtools's bdt)
- beat/beat.editor!53 Allow package to be tested outside of source checkout: Summary This MR addresses a minor issue when testing conda packages out of a checkout of the package source. So far, this was not possible as the documentation source code was not shipped with the package. This MR changes that. Relevant issue(s) fixed bob/bob.devtools#5
- beat/beat.editor!57 Use relative path to change to conda/js dir during test: This MR removes the `RECIPE_DIR` environment variable use during test. Such value may change depending on the docker CI the test is running. If the value is different than that used during the build phase, then the build fails. Example: https://gitlab.idiap.ch/beat/beat.editor/-/jobs/158178 It also makes the built package more relocatable and about 10x smaller!
- beat/beat.editor!46 New algorithms are created with an input & output: Summary When a new algorithm is created, it will have by default an empty input & output. This won't happen if you're copying an algorithm or creating an algorithm from a toolchain block, as expected. Relevant issue(s) fixed beat/beat.editor#145
- beat/beat.editor!37 Json schema update: Fixes beat/beat.editor#174, updating the JSON schema files & making sure the editor works with the new files.
- beat/beat.editor!58 Update development docs for bob.devtools: This updates the development installation docs for v1 to use `bob.devtools`. It also clarifies/cleans up things :) Closes beat/beat.editor#201
* beat/beat.editor
* minor release v1.1.0 :
- beat/beat.editor!61 Restrict algorithm editor parameter types: Users could set the type of algorithm parameters as `array` or `dict`, now they can't. This also separates the `BUILTIN_TYPES` (derived from the `basetype` in the schema) from the special dataformat-only types (now in `DATAFORMAT_TYPES`). Closes beat/beat.editor#205
- beat/beat.editor!64 Restrict range parameter min/max values: `min` can no longer be greater than `max`, and `max` can no longer be less than `min`. Closes beat/beat.editor#206
...@@ -35,6 +35,7 @@ In the following sections different parts of the graphical interface will be exp ...@@ -35,6 +35,7 @@ In the following sections different parts of the graphical interface will be exp
.. toctree:: .. toctree::
editor editor
quick_start_guide
contribute contribute
......
...@@ -26,3 +26,4 @@ ...@@ -26,3 +26,4 @@
.. _PyQt: https://www.riverbankcomputing.com/software/pyqt/intro .. _PyQt: https://www.riverbankcomputing.com/software/pyqt/intro
.. _PyQt documentation: http://pyqt.sourceforge.net/Docs/PyQt5/index.html .. _PyQt documentation: http://pyqt.sourceforge.net/Docs/PyQt5/index.html
.. _pytest-qt: https://pytest-qt.readthedocs.io/en/latest/ .. _pytest-qt: https://pytest-qt.readthedocs.io/en/latest/
.. _installation: https://www.idiap.ch/software/beat/install
.. vim: set fileencoding=utf-8 :
.. Copyright (c) 2020 Idiap Research Institute, http://www.idiap.ch/ ..
.. Contact: beat.support@idiap.ch ..
.. ..
.. This file is part of the beat.editor 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-editor-quick-start-guide:
===========================
Quick Start Guide
===========================
This quick start guide gives an overview of the development workflow using this
editor.
Installation
============
Follow the same `installation`_ procedure as other beat packages to setup a
conda environment ready for development. Activate the conda environment (e.g.
named "beat").
.. code-block:: sh
$ conda activate beat
(beat) $
.. note::
In these instructions ``(beat) $`` corresponds to your own shell prompt,
which can be different. The actual command(s) to type comes after the ``$``
marker.
All further instructions assume you have the environment where BEAT packages
are installed properly activated.
Work flow
=========
The BEAT editor allows you to implement and test your solution locally on
either a reduced or different dataset. Once you have everything working as
expected, push the resulting code to the platform and execute it there, for
validation.
The following steps describe the procedure to start from an **existing**
experiment and build on that.
#. Get (or pull) the reference experience you would like to base your work on:
.. code-block:: sh
(beat) $ beat pull <experiment-author>/<experiments>/<toolchain-author>/<toolchain-name>/<toolchain-version>/<experiment>
This will pull the experiment as well as all its dependencies from the
platform so that it can be edited (and run) locally.
.. note::
Values within angle brackets (``<`` and ``>``) will depend on the asset
name. Replace these values by appropriate actual values.
#. Create your own fork of the experiment:
.. code-block:: sh
(beat) $ beat experiment fork <experiment-author>/<experiments>/<toolchain-author>/<toolchain-name>/<toolchain-version>/<experiment> <your-beat-user-id>/<experiments>/<toolchain-author>/<toolchain-name>/<toolchain-version>/<experiment-name>
#. Create your own fork from an algorithm you want to modify:
.. code-block:: sh
(beat) $ beat algorithm fork <author>/<algorithm>/<version> <your-beat-user-id>/<algorithm>/<version>
This will allow you to use your own modified algorithm for your fork.
.. note::
You will have to update your experiment fork in order to use your own
algorithm(s).
.. note::
You do not need to fork an algorithm, you can use a different one as
long as its inputs and outputs match the one you want to replace.
#. Edit the code:
.. code-block:: sh
(beat) $ beat algorithm edit <author>/<algorithm>/<version>
This will open your default configured editor to edit the code of the
algorithm passed in parameter.
#. To edit any other asset, just start the editor, optionally pointing to the
prefix of interest:
.. code-block:: sh
(beat) $ beat --prefix <path/to/prefix> editor start
This will start the BEAT editor so that you will have an easy access to all
locally available assets. You'll be able to edit them visually. The editor
also allows to start your favorite editor for code or documentation
modification.
#. Once the editing is done, you can run an experiment **locally** like this:
.. code-block:: sh
$ beat exp run <experiment-author>/experiments/<toolchain-author>/<toolchain-name>/<toolchain-version>/<experiment-name>
#. Once the experiment runs successfully on your machine, you can upload it to
the online platform and run it there.
.. code-block:: sh
$ beat exp push <experiment-author>/experiments/<toolchain-author>/<toolchain-name>/<toolchain-version>/<experiment-name>
$ beat exp start <experiment-author>/experiments/<toolchain-author>/<toolchain-name>/<toolchain-version>/<experiment-name>
You can monitor the execution of your experiment at any moment with:
.. code-block::
$ beat exp monitor <experiment-author>/experiments/<toolchain-author>/<toolchain-name>/<toolchain-version>/<experiment-name>
.. include:: links.rst
Supports Markdown
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