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.
Install EDM: The installer for EDM can be found here. Select the full GUI installer rather than the CLI-only version.
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
.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
Git must be installed on your system to build the developer environment. The installer can be found here.
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.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 variousci
tasks. The name of the environment is arbitrary, however a common convention is to usebootstrap
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"
To start an EDM shell in the bootstrap environment, execute
edm shell -e bootstrap
. All commands shown below of the formpython -m ci ...
are assumed to be executed from within this EDM bootstrap environment.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 bothedge
andedge_app
python packages into this environment in developer mode.Additionally, this command will write a
version.py
file into theenthought_edge/edge
andenthought_edge/edge_app
package directories based on thePROJECT_VERSION
specified inci.config.py
.The main application can be launched by entering the development environment with
edm shell -e edge-dev-3.6
and executingstart_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.