QGIS plugin development

1 Set up the developer environment

After you have installed the environment as described here you must still activate the QGIS plugins.

Note

Note that on macOS you currently need to manually install and point to a QGIS executable in your path. If you use pixi that could be as simple as: pixi global install --environment qgis qgis pandas.

The simplest way to do this is by running pixi run install-qgis-plugins. It makes a symlink to the ribasim_qgis folder so that QGIS can find it. It also installs plugins that make it possible to reload and debug your plugin while QGIS is open.

Note

On Windows you need to have Developer mode enabled. Otherwise you will not have enough access rights to create symlinks. For more info, see this Windows blog.

We wanted to implement this via pip install --editable, but QGIS doesn’t find the metadata.txt and therefore cannot load the plugin on startup.

2 Running QGIS

In order to run QGIS with the plugins, simply call pixi run qgis. You will find the Ribasim plugin in the tool bar.

Note

On Windows, running QGIS from the start menu will disable Python, and thus the plugins. QGIS needs some more paths during the startup and the Pixi environment provides those.

3 Running tests

To run the QGIS plugin tests locally inside a QGIS process, call pixi run test-ribasim-qgis. This launches QGIS and runs the full test suite (including plugin and UI tests) via the test runner.

For CI or headless environments, the same tests can be run in Docker with pixi run test-ribasim-qgis-docker. Make sure that Docker is installed and available in your path.

4 QML styles and node icons

The node style QML is stored in python/ribasim/ribasim/styles/NodeStyle.qml.

Node icon SVGs in this QML file are generated with:

pixi run write-node-icons

The utils/write_node_icons.py script:

  • generates overview and icon artifacts in utils/node_icons/
  • updates categorized node_type symbols in NodeStyle.qml with embedded SVG marker data

To also upload the icons to the S3 bucket (under doc-image/node-icons/) for use in the documentation, run:

pixi run upload-node-icons

This requires MinIO credentials (MINIO_ACCESS_KEY / MINIO_SECRET_KEY) via environment variables or a .env file. The uploaded icons are publicly available at https://s3.deltares.nl/ribasim/doc-image/node-icons/.

When changing icons, rerun write-node-icons and include the resulting QML and icon changes in your PR. Once you are happy with the changes locally, run upload-node-icons to update the S3 copies used in the documentation.

You can also modify the QML files by making changes in QGIS. For NodeStyle.qml it is best to run write_node_icons.py afterwards so the formatting stays the same.

5 Debugging

After installing the plugins via pixi run install-qgis-plugins. Extra debugging tools are also installed in QGIS that is installed within your pixi environment.

After you have started pixi run qgis, you can make alterations to the Python code and use the Plugin Reloader to reload the plugin without restarting QGIS. The shortcut in QGIS is CTRL+F5.

It is also possible to connect the debugger of Visual Studio Code. For this the debugvs plugin is installed in QGIS. In QGIS press the button to Enable Debug for Visual Studio. Then go to Visual Studio Code and start the launch task Ribasim QGIS: Attach to QGIS. Now you can place breakpoints.

Note

We are currently using debugvs 0.7 with ptvsd as service, since there is an open issue that breaks debugvs 0.8 with debugpy.