Contribute to This Plugin¶
This guide walks through setting up a working environment for developing nomad-north-gwyddion.
Structure of this repository
The plugin's Python side (the NORTHTool/NorthToolEntryPoint definition) lives in
src/nomad_north_gwyddion.
The container itself -- Dockerfile, autostart config, and icon -- lives in
src/nomad_north_gwyddion/north_tools/gwyddion,
which has its own README covering the Docker side in more detail.
Setup¶
It is recommended to use Python 3.11 with a dedicated virtual environment. We recommend uv, an extremely fast Python package and project manager; a more classical venv/pip approach works too.
=== "uv"
uv is capable of creating a virtual environment and installing the required Python version at the same time.
```bash
uv venv --python 3.11
```
=== "venv" Note that you will need to install the Python version manually beforehand.
```bash
python3.11 -m venv .venv
. .venv/bin/activate
```
Development installation¶
Clone the repository:
Install the package in editable mode, together with its dev dependencies:
=== "uv"
```bash
uv pip install -e ".[dev]"
```
=== "pip"
```bash
pip install --upgrade pip
pip install -e ".[dev]"
```
Linting, formatting, and pre-commit hooks¶
We use Ruff for linting/formatting and mypy for type checking. .pre-commit-config.yaml also runs pyupgrade, nbstripout, and cspell. We use prek -- a drop-in, faster reimplementation of pre-commit that reads the same config file -- as the runner; it's installed as part of the dev extra above, so you just need to enable the hook once per clone:
prek install # installs the git hook
prek run --all-files # run all hooks against the whole repo once
You can also run Ruff directly:
If cspell flags a real (correctly spelled) word, add it to .cspell/custom-dictionary.txt, or regenerate it from the current source/docs:
Working on the Docker image¶
If you're changing the Dockerfile or the autostart config, build and smoke-test the image locally before opening a PR (from the package root):
docker build -f src/nomad_north_gwyddion/north_tools/gwyddion/Dockerfile \
-t nomad-north-gwyddion:dev .
docker run -p 8888:8888 nomad-north-gwyddion:dev
Then point NORTHTool.image in
src/nomad_north_gwyddion/north_tools/__init__.py
at your local tag (e.g. nomad-north-gwyddion:dev) to test it end-to-end from within a running NOMAD -- see the NORTH tools how-to for details on testing local images. Revert that change before merging: CI (.github/workflows/publish_north.yml) builds and publishes the real image on every push to main.
Testing¶
Unit tests are written with pytest:
Contributing on GitHub¶
Commit your changes on a separate branch and open a pull request. CI checks linting, runs the tests, builds the Docker image, and builds the docs; once those pass and a review happens, the PR can be merged.
Changing something in docs/? See How-to guides > Contribute to the Documentation for the writing conventions, how to build the docs locally, and how to add a new page.
Template updates¶
This project was generated from, and stays in sync with, FAIRmat's cookiecutter-nomad-plugin template via cruft. To check for and apply template updates, run cruft update in the repository root -- see the cruft documentation for details. .github/* workflow files are excluded from these updates ([tool.cruft].skip in pyproject.toml) to avoid permissions issues.
Releasing¶
Before tagging a release, the image tag in NORTHTool (in north_tools/__init__.py) is automatically updated to the version you are about to release (e.g. v0.1.6). The publish workflow (used for publishign to PyPI) does not push this change back to GitHub, so the entry point on main always points at the :main image tag -- see the project README for why installing from PyPI is recommended over a GitHub checkout.
Developing this plugin as part of NOMAD¶
If you're testing this plugin's NORTH integration against a full NOMAD instance -- not just its own unit tests -- use nomad-distro-dev, FAIRmat's development environment for NOMAD and its plugins. See How-to guides > Install this Plugin for how this repo is wired into that workspace.
Troubleshooting¶
If you hit an issue with the tool or with setting up the development environment, open a GitHub issue.