Installation & Setup

This will create a development environment and install the edge and edge_app packages. Steps 1-3 can be skipped if EDM is already installed & configured.

  1. Install EDM: The installer for EDM can be found here. Select the full GUI installer rather than the CLI-only version.

  2. After downloading and installing EDM, setup an Enthought API token via edm configure. For more details regarding the EDM authentication token configuration, please see setting up a default configuration and Using token based authentication. If you already have an API token, you can set this in the api_token field of the default EDM configuration file, ~/.edm.yaml.

  3. The EDM configuration file should be edited to include the repositories containing packages required by Edge. Add the following repositories to the repositiories: section of your ~/.edm.yaml file (or alternatively use the EDM GUI to add these):

    • enthought/free

    • enthought/lgpl

    • enthought/platform

    • enthought/edge

    • (Optional) enthought/edge-dev

    You will also need to add the following to the bundle_repositories section of the same file:

    • enthought/edge

    • (Optional) enthought/edge-dev

  4. Git must be installed on your system to build the developer environment. The installer can be found here.

  5. Create a local copy of the repository with the command:

    git clone https://github.com/enthought/ms-platform.git

    and navigate to the new ms-platform directory.

  6. To use the project ci module for common development tasks, the first step is to setup a bootstrap EDM environment, which is a minimal environment needed to execute the various ci tasks. The name of the environment is arbitrary, however a common convention is to use bootstrap as the environment name. Any EDM environment with the following python packages will suffice:

    • click

    • enthought_sdk >= 1.7.0

    • pip

    • pyyaml

    • setuptools

    This environment can be setup with the following command:

    edm install -e bootstrap click pyyaml pip setuptools "enthought_sdk>=1.5.0"

  7. To start an EDM shell in the bootstrap environment, execute edm shell -e bootstrap. All commands shown below of the form python -m ci ... are assumed to be executed from within this EDM bootstrap environment.

  8. Setup a development environment by executing the following command:

    python -m ci setup

    This will create an EDM environment called edge-dev-3.6 and will install both edge and edge_app python packages into this environment in developer mode.

    Additionally, this command will write a version.py file into the enthought_edge/edge and enthought_edge/edge_app package directories based on the PROJECT_VERSION specified in ci.config.py.

  9. The main application can be launched by entering the development environment with edm shell -e edge-dev-3.6 and executing start_app.

Setting up a local stack

To start a local stack, run the following command:

python -m ci stack up

Note that this requires the user to be logged in to the quay.io registry, with an account that has access to the Enthought platform repositories:

docker login -u username -p password quay.io

If used without other options, stack up will create a temporary docker volume for storing its data, which is disposed of when the stack is terminated. This is suitable for running the test suite; if the preference is to persist the data, so that the local stack can be re-used for other purposes, choose a prefix to add to the generated storage volumes:

python -m ci stack up --volume-prefix my_stack

In this case, the data will persist, even after shutting down the stack:

python -m ci stack down

Deleting the volumes generated for the stack should not be generally necessary. However, if needed, use the following commands to delete the volumes:

docker volume rm {prefix}_identity
docker volume rm {prefix}_catalog
docker volume rm {prefix}_messages

In addition to the services provided by the Enthought SDK (Identity, Events, and Catalog), it is also possible to set up a JupyterHub service for local testing. The local JupyterHub deployment contains a dummy login mechanism, and therefore any credentials will be accepted, as long as the user name is not empty. Before using the JupyterHub service, the Docker images need to be built using the following command:

python -m ci stack build-jupyter EDGE_VERSION

In the command above, EDGE_VERSION specifies the version of the edge package that will be installed by default in the single user images spawned by JupyterHub. The version specified needs to be available in either the enthought/edge or enthought/edge-dev repositories.

To start the JupyterHub service, run the following command:

python -m ci stack start-jupyter

When the JupyterHub service is started, the user's hatcher token is retrieved from either the HATCHER_TOKEN environment variable or from the ~/.edm.yaml file, and made available as an environment variable in the single user images spawned by the JupyterHub service. This mechanism is implemented for the purpose of local testing only, and would not be safe in production.

To stop the local JupyterHub service run the following command:

python -m ci stack stop-jupyter

Note that stopping the full local stack, as described above, also stops the JupyterHub service.

Running tests

If running service-related tests is not required, start the test suite via the following command:

python -m ci test --skip-catalog-tests

The full test suite can be run against an existing remote deployment of SDK services, or against a local stack deployment (see previous section). By default, the test command will use the default connection details for a local stack deployment. To provide different connection details see the available help via:

python -m ci test --help

By default, the stack up command creates a catalog named msp_test_db, for use with tests. Other catalogs in the local stack can be created and managed using the following commands:

# Create a catalog
python -m ci stack create-catalog CATALOG_NAME

# Remove an existing catalog
python -m ci stack remove-catalog CATALOG_NAME

# List available catalogs
python -m ci stack list-catalogs

Writing and Building Documentation

Documentation Style Conventions

Project documentation should aim to follow the model detailed here. There is also a convention in the Edge user guide of italicising references to code objects and bolding references to text or items visible in the application UI.

Building Documentation with PlantUML

We use the standard sphinx package to build documentation via the command python -m ci docs. Details on the general documentation build process are available here.

As we generate PlantUML diagrams as part of the documentation, a local installation is required wherever the documentation is being built. Sphinx relies on being able to call the command plantuml to process the .puml files so any install method that achieves this is suitable. See below for the OS specific parts of the install procedure.

One caveat across all OSes is that we require a version of plantUML greater than 1.2019.6 (see here).

A python package contributing a sphinx plugin (sphinx_contrib_plantuml) is also required to parse .. uml:: directives and is installed along with the other python dependencies via python -m ci setup.

MacOS

The easiest way is installing the package available for mac via brew (the macports package should also work!)

Linux

While there is a PlantUML package available via apt, it is older than the version we require. The easiest way to install is instead to download the PlantUML .jar and create a wrapper script in the system PATH as detailed in the sphinx_contrib_plantuml readme here.

The installation method used in our CI runs places a script in /usr/local/bin/plantuml and the .jar in /usr/local/share, but the most appropriate locations may be system (or user permissions) dependant.

Checking the Install

The above methods of installation should bundle the required graphviz package, but if not this may also need to be installed. You can check if graphviz is present by creating a PlantUML file with the code:

@startuml
testdot
@enduml

PlantUML documentation and support in IDEs

Documentation describing the PlantUML syntax and standard library can be found here, our documentation also makes use of some additional functions contributed by files from the C4-PlantUML repository.

PyCharm has a useful plugin named PlantUML Integration, available via the plugins menu in PyCharm > Preferences. There is a similar plugin available for VSCode.