Developer Manual

Note

All commands listed in this manual are for Debian and its derivations.

Technologies

NOFAInsert is a QGIS plugin written in Python. Like other QGIS Python plugins it uses QGIS API and PyQt bindings. Additionally NOFAInsert plugin makes extensive use of psycopg package.

Documentation

The newest version of plugin was developed for QGIS 2.18.

Development

History

In December 2016 Stefan Blumentrath (GitHub profile) started developing the plugin. At the beggining of 2017 Matteo De Stefano (GitHub profile) created a separate repository and released version 0.3. Together with intern Jakob Miksch (GitHub profile) who worked in NINA as part of his Erasmus+ Internship version 0.4 was released. Another Erasmus+ intern Ondřej Svoboda (GitHub profile) reworked the whole plugin and released version 0.5. Current version is 0.5.2.

Development Tools Setup

There is nothing a developer must setup in order to start (except for building documentation) because all needed Python packages are already present in QGIS by default.

However, if you are using an IDE you can set it up to understand the API.

API Documentation

All classes, methods and functions are documented in reStructuredText format that can be used by Sphinx to generate documentation.

Branches

There are three important branches:

  • master – main branch.
  • gh-pages – branch with documentation.
  • before_rework_2017-07-13 – version 0.5 came with significant changes. This branch serves as a backup of the previous version.

Plugin Structure

Structure with short comments is as follows:

/
├── data/
│   └── icons/
│       └── options.png      # icon for opening connection parameters dialog
├── docs/                    # directory with docs
│   ├── source/              # directory with docs source
│   ├── make.bat             # batch file for creating docs
│   ├── Makefile             # makefile for creating docs
│   └── update-docs.sh       # bash script for publishing updates docs
├── nofa/                    # NOFA package
│   ├── gui/                 # GUI package
│   │   ├── __init__.py      # module for package initialization
│   │   ├── con_dlg.py       # module with connection dialog class
│   │   ├── de.py            # module with custom date edit class
│   │   ├── dtst_dlg.py      # module with reference dialog class
│   │   ├── exc.py           # module with custom exceptions
│   │   ├── ins_mw.py        # module with insert main window class
│   │   ├── ins_mw.ui        # XML file for creating GUI
│   │   ├── prj_dlg.py       # module with project dialog class
│   │   ├── ref_dlg.py       # module with reference dialog class
│   │   └── vald.py          # module with custom validators
│   ├── wms/                 # directory with WMS files
│   │   └── osm.xml          # XML file for loading OSM basemap
│   ├── __init__.py          # module for package initialization
│   ├── db.py                # module with database queries
│   └── ordered_set.py       # module with OrderedSet container
├── scripts/                 # directory with scripts
│   └── create_log_tbls.py   # script for creating log tables
├── test/                    # directory with tests
├── __init__.py              # module for package initialization
├── LICENSE                  # license file
├── Makefile                 # makefile
├── metadata.txt             # plugin metadata
├── nofainsert.png           # PNG plugin icon 64x64 pixels
├── nofainsert.svg           # SVG plugin icon
├── nofa_insert.py           # module with main class
├── nofainsert-24.png        # PNG plugin icon 24x24 pixels
└── README.md                # GitHub readme

NINA QGIS Plugin Repository

Users install NOFAInsert plugin from NINA QGIS Plugin Repository. It is a simple XML file:

When new version of plugin is released it is necessary to edit the file so that users get a notification.

Note

How soon a user gets notified depends on his/her settings in Plugins ‣ Manage and Install Plugins… ‣ Settings.

To adjust the file log in to server and edit version="0.5.2" to the new version.

ssh <username>@vm-srv-finstad.vm.ntnu.no
cd /var/www/html/NOFA_plugins
nano plugins.xml

Note

Version listed in http://vm-srv-finstad.vm.ntnu.no/NOFA_plugins/plugins.xml should match version in metadata.txt.

Don’t forget to edit documentation.

Online Documentation

Plugin documentation is available on its own webpage. This webpage is connected to gh-pages branch. The documentation itself is written in reStructuredText and built with Sphinx.

First install Sphinx and Read the Docs Theme:

sudo pip install sphinx
sudo pip install sphinx_rtd_theme

Note

To run commands mentioned above you need to have pip installed.

sudo apt install python-pip

Then you can build the documentation:

cd docs/
make html

Warning

If you run across a problem building the documentation (especially API documentation) make sure you run Sphinx for Python 2.

To view created pages in Firefox:

firefox build/html/index.html &

When you are satisfied with your changes publish updated documentation to gh-pages branch by calling a script.

./docs/update-docs.sh

Hint

Call the script from plugin main directory.

Testing

Unfortunately NOFAInsert plugin was not developed by using test-driven development so test were written later. That means there are not as many test as there should be.

Todo

Write tests for:

  • Location Table
  • Occurrence Table
  • Dataset Project and Reference windows
  • inserting new Dataset Project and Reference
  • Reset button
  • Insert to NOFA button
  • History tab

After trying to make QGIS Tester Plugin work and considering QGIS Desktop for Docker it was decided to use unittest framework and nose extension. On top of that coverage tool is used for an overview of how much code is tested.

First install all required packages:

sudo pip install nose
sudo pip install coverage

To run tests execute this command from plugin main directory:

make test