Commit 61384fe4 authored by André Anjos's avatar André Anjos 💬
Browse files

[doc] Edit quick-start guide to be more explicit and shorter

parent 4b7735f5
Pipeline #37429 passed with stage
in 6 minutes and 13 seconds
......@@ -27,67 +27,92 @@
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 package to setup a conda environment ready for development.
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").
#. Start the editor: ::
.. code-block:: sh
$ beat editor start
$ conda activate beat
(beat) $
#. Start the editor for a specific prefix:
.. note::
In order to use a specific prefix, use the `--prefix` option. ::
In these instructions ``(beat) $`` corresponds to your own shell prompt,
which can be different. The actual command(s) to type comes after the ``$``
marker.
$ beat --prefix /path/to/prefix editor start
All further instructions assume you have the environment where BEAT packages
are installed properly activated.
Work flow
=========
The goal of the BEAT editor is to allow you to implement and test your solution
locally on either a reduced or different dataset. Then, once you have
everything working as expected, push the resulting code to the platform and
execute it there.
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.
1. Get (or pull) the experience you would like to 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.
1. Get the experience you would like to work on: ::
2. Edit the code:
$ beat pull user/author/toolchain/version/name_of_experiment
.. code-block:: sh
This will pull the experiment as well as all its dependencies from the platform
so that it can be run locally.
(beat) $ beat algorithm edit <author>/<algorithm>/<version>
2. Edit the code: ::
This will open your default configured editor to edit the code of the
algorithm passed in parameter.
$ beat algorithm edit author/name_of_algo/version_number
3. To edit any other asset, just start the editor, optionally pointing to the
prefix of interest:
This will open your default configured editor to edit the code of the algorithm
passed in parameter.
.. code-block:: sh
3. Edit an asset: ::
(beat) $ beat --prefix <path/to/prefix> editor start
$ beat 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.
This will start the BEAT editor so that you will have an easy access to your
asset. You'll be able to edit them visually. The editor also allows to start
your favorite editor for code or documentation modification.
4. Once the editing is done, you can run an experiment like this:
4. Run an experiment:
.. code-block:: sh
To run an experiment locally: ::
$ beat exp run <experiment-author>/experiments/<toolchain-author>/<toolchain-name>/<toolchain-version>/<experiment-name>
$ beat exp run user/author/toolchain/version/name_of_experiment
5. Once the experiment runs successfully on your machine, you can upload it to
the online platform and run it there.
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 user/author/toolchain/version/name_of_experiment
$ 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>
$ beat exp start user/author/toolchain/version/name_of_experiment
You can monitor the execution of your experiment at any moment with:
You can monitor the execution of your experiment at any moment with: ::
.. code-block::
$ beat exp monitor user/author/toolchain/version/name_of_experiment
$ 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