Commit 24957334 authored by Jaden DIEFENBAUGH's avatar Jaden DIEFENBAUGH
Browse files

[docs] semi-finalized install & dev docs, #123

parent 1eda1cdc
Pipeline #21651 passed with stages
in 40 minutes and 36 seconds
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
Before developing for ``beat.editor``, you'll need to familiarize yourself with at least the following concepts/tools:
* Flask & RESTful APIs
* JSON-schema, v4
* Node.js
* The DOM & browser APIs
* Javascript
* ES6
* React
* Redux
* Bootstrap
* D3 & SVG in general
* Flow typings
* Webpack
* Babel
* Karma
* Mocha
Configuring Your Editor
Your editor is probably adequately configured for editing Python code; it won't be properly configured for the JS part of ``beat.editor`` unless you do modern web development.
* Make sure to pick up JS & JSX syntax highlighting for your editor! Make sure your highlighting supports "ES6" (a landmark JS verion released a couple years ago) and "Flow" (the static typing language extension we are using).
* The configuration files for various linters/static analysis tools are found as dotfiles in the root folder for the JS (next to ``package.json``).
* The provided ``.tern-project`` file is configuration for Tern.js, a JS code analysis tool (autocompletion, etc.). If you're using a popular editor, it'll probably have a plugin for Tern.js.
* There's a few diferent linters available for the different code types (JS, HTML, CSS, JSX). I would suggest installing a linting engine that picks up the available linters for you, like "Syntastic" or "ALE" for Vim. If you aren't using a linting engine, here's some additional notes to get linting working:
- Linting via ESLint should be configured to use the local installation (from ``node_modules/``) - *not* a global installation. This lets ESLint properly find all the plugins on a per-project basis.
- Linting CSS via Stylelint should be configured similarly to ESLint. Since this linter is relatively new, your linting engine/editor might not pick it up automatically.
* Linting using Flow needs more configuration regardless of how you set up linting. You need to install the ``flow-typed`` package from NPM globally and pull the types for dependencies: ::
$ npm i -g flow-typed
$ cd conda/js
$ flow-typed update
Development Notes
- You'll probably want the `React devtools <>`_ and `Redux devtools <>`_ browser plugins to sanely debug and inspect React/Redux code.
- You might need to enable/configure sourcemaps in your browser manually.
- The Python server can be run in dev mode (doesn't try to launch a browser tab) via the ``--dev`` flag.
- You'll probably want Webpack's dev server (``npm start``) running in a separate terminal window/tab, as Webpack will automatically rebuild/update your project when files change (served at ``localhost:9101``. However, changes to the webpack config or other configuration files may not be watched. In general, anything under ``conda/js/src/`` should be hot-reloaded, while anything else may not be. If there's issues with the app when running the dev server that you don't expect or don't make sense (especially if the issue came up after a hot reload), try refreshing the page - sometimes the hot reloader doesn't properly handle complex changes (such as state management or async functionality).
- When changing/updating dependencies, you'll want to install/update flow types for them. Run ``flow-typed update`` again whenever you add JS dependencies.
- If you're quickly iterating test code, you can run the testing daemon in a terminal tab/pane with the ``test-start`` npm script. This lets you quickly trigger tests again with ``karma run`` (via a global ``karma-cli`` installation through npm) since it won't have to start up the daemon each time you want to run the tests. It will also rerun tests when the files change (this is configurable). The daemon is a bit buggy, so if you are getting unexpected errors, try restarting it.
JS Project Structure
All JS is stored under ``conda/js``. Unless otherwise noted, all future paths given in this section are relative to that one.
* All dependencies are stored in ``node_modules/``.
* All source is stored in ``src/``.
* All ``*.spec.*`` files are test files. They should be next to the file/component they are testing, which has the same name minus the ``.spec`` infix.
* There are 3 different folders in ``src/``, ``components/``, ``helpers``, and ``store/``.
- ``components/`` holds the UX components, written in a mix of HTML & JSX & CSS, and their associated processing code. Non-generic components are stored in their respective sub-folders, broken up by BEAT entity type.
- ``helpers/`` holds code used in many different places or generic utility code. The ``helpers/schema/`` subfolder holds the code & schemas for validating BEAT objects.
- ``store/`` holds all the code for the Redux store, including the reducers, actions, and selectors.
* All this source code is pulled together by ``main.jsx``, which is processed by Webpack via the ``webpack.config.js`` config file.
* ``test/`` holds test data and configures and runs the tests.
.. automodule:: beat.editor
......@@ -34,6 +34,8 @@
.. toctree::
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.
#. Working internet connection
#. `Virtualbox <>`_ installed and working (might need configuration)
#. `Packer <>`_ 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 git clone
#. 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 ``beateditor``, should be available in the shell.
Method 2: Conda (easyish)
This method integrates with one of your Conda environments' packages on your local machine, but has more strict requirements.
#. Linux or MacOS (Docker features not available on MacOS for now)
#. Working internet connection
#. Useable Conda setup (see `Bob's documentation on it <>`_)
#. 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
#. Add a new Conda channel: ::
$ conda config --env --add channels
#. Install the ``beat.editor`` package: ::
$ conda install beat.editor
#. The BEAT commands, ``beat`` and ``beateditor``, should be available.
Method 3: For developers
This method is for developers looking to work on ``beat.editor``.
#. Linux or MacOS
#. Working internet connection
#. Useable Conda setup (see `Bob's documentation on it <>`_)
#. 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 <>`_.
Installation Steps
#. Clone the ``beat.editor`` repository: ::
$ git clone
#. Clone the ``bob.admin`` repository, necessary for building a development Conda environment: ::
$ git clone
#. Use ``bob.admin`` to create a development Conda environment named ``beatedit`` for Python 3.6: ::
$ conda activate base
$ cd beat.editor
$ ../bob.admin/conda/ --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
#. 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/beateditor --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
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