DEVELOPMENT.md

Development

This page contains developer instructions to build and maintain mdadash.

• Installation
  • With conda
  • With pip
• Run
• Develop
  • Frontend
  • Backend
• Lint checks
  • Frontend
  • Backend
• Tests
  • Frontend
  • Backend
• Code Coverage
  • Frontend
  • Backend
• Build
• Verify GitHub actions locally
• Docs
• Publishing
  • TestPyPI
  • PyPI
  • conda-forge

Installation

To build mdadash from source,we highly recommend using virtual environments. If possible, we strongly recommend that you use Anaconda as your package manager. Below we provide instructions both for conda and for pip.

With conda

Ensure that you have conda installed.

Create a virtual environment and activate it:

conda create --name mdadash
conda activate mdadash

Install the development, testing and documentation dependencies:

conda env update --name mdadash --file devtools/conda-envs/dev_env.yaml
conda env update --name mdadash --file devtools/conda-envs/test_env.yaml
conda env update --name mdadash --file docs/requirements.yaml

Build this package from source:

pip install -e .

If you want to update your dependencies (which can be risky!), run:

conda update --all

And when you are finished, you can exit the virtual environment with:

conda deactivate

With pip

To build the package from source, run:

pip install .

If you want to create a development environment, install the dependencies required for tests and docs with:

pip install ".[dev,test,doc]"

Run

The frontend code needs to be built before running the backend server. This can be done as follows:

cd mdadash/frontend
npm install
npm run build

To run the dashboard server:

mdadash --topology <topology_filename> --trajectory <trajectory_url>

To see the options available:

mdadash --help

Develop

Frontend

Developer instructions for frontend code can be found here.

Backend

• Use the editable installation above (pip install -e .)

Lint checks

Frontend

npm run lint --prefix mdadash/frontend

Backend

ruff check

Tests

Frontend

npm run test:unit --prefix mdadash/frontend -- --run

Backend

pytest -v

Code Coverage

Frontend

cd mdadash/frontend
npx vitest --run --coverage

The coverage details will be shown on the console. Open coverage/index.html to view the interactive coverage report in the browser.

Backend

To see coverage output on the console:

pytest -v --cov=mdadash

To write coverage output to html file:

pytest -v --cov=mdadash --cov-report=html

Open htmlcov/index.html to view the coverage report in the browser.

Build

To build this package:

rm -rf mdadash.egg-info dist && python -m build

To verify the created wheel in an isolated environment:

uv run --no-project --refresh --with path.to.whl mdadash <options>

To check the created distribution:

twine check dist/*

Verify GitHub actions locally

GitHub actions can be verified locally using act.

Note that this requires Docker. Running on Mac needs an additional param --container-architecture linux/arm64. To bypass the repo name check, you can pass --env GITHUB_REPOSITORY=MDAnalysis/mdadash. Both these can be set in ~/.actrc as well.

To list the jobs:

act -l

To run a job (eg: pylint_check):

act -j pylint_check

To run all jobs:

act

Docs

Setting up the docs environment:

conda env update --name mdadash --file docs/requirements.yaml

Building docs locally:

cd docs
make clean && make html

Open docs/_build/html/index.html to view the docs in the browser.

Publishing

TestPyPI

Create a new tag to trigger TestPyPI deployment (needs to be done from command line as it is not possible from GitHub web UI directly):

Example:

git tag -a v0.1.0 -m "v0.1.0"
git push origin v0.1.0

After the action runs successfully, verify at: https://test.pypi.org/project/mdadash/

PyPI

Create a new release with the tag above after verifying on TestPyPI.

After the action runs successfully, verify at: https://pypi.org/project/mdadash/

conda-forge

Feedstock repo: https://github.com/conda-forge/mdadash-feedstock

A new PR will automatically get created by regro-cf-autotick-bot after a few hours of the new package version being available on PyPI.

To manually trigger a version update:

Create a new issue with the type Bot commands and enter @conda-forge-admin, please update version in the issue title. The bot will create a new PR immediately.