init plugin

docs/development/code_of_conduct.md

@@ -0,0 +1,2 @@
+```{include} ../../CODE_OF_CONDUCT.md
+```

docs/development/contribute.md

@@ -0,0 +1,2 @@
+```{include} ../../CONTRIBUTING.md
+```

docs/development/documentation.md

@@ -0,0 +1,24 @@
+# Documentation
+
+Project uses Sphinx to generate documentation from docstrings (documentation in-code) and custom pages written in Markdown (through the [MyST parser](https://myst-parser.readthedocs.io/en/latest/)).
+
+## Build documentation website
+
+To build it:
+
+```bash
+# install aditionnal dependencies
+python -m pip install -U -r requirements/documentation.txt
+# build it
+sphinx-build -b html -d docs/_build/cache -j auto -q docs docs/_build/html
+```
+
+Open `docs/_build/index.html` in a web browser.
+
+## Write documentation using live render
+
+```bash
+sphinx-autobuild -b html docs/ docs/_build
+```
+
+Open <http://localhost:8000> in a web browser to see the HTML render updated when a file is saved.

docs/development/environment.md

@@ -0,0 +1,63 @@
+# Development
+
+## Environment setup
+
+> Typically on Ubuntu (but should also work on Windows with potential small adjustments).
+
+### 1. Install virtual environment
+
+Using [qgis-venv-creator](https://github.com/GispoCoding/qgis-venv-creator) (see [this article](https://blog.geotribu.net/2024/11/25/creating-a-python-virtual-environment-for-pyqgis-development-with-vs-code-on-windows/#with-the-qgis-venv-creator-utility)) through [pipx](https://pipx.pypa.io) (`sudo apt install pipx`):
+
+```sh
+pipx run qgis-venv-creator --venv-name ".venv"
+```
+
+Then enter into the virtual environment:
+
+```sh
+. .venv/bin/activate
+# or
+source .venv/bin/activate
+```
+
+Old school way:
+
+```bash
+# create virtual environment linking to system packages (for pyqgis)
+python3 -m venv .venv --system-site-packages
+source .venv/bin/activate
+```
+
+### 2. Install development dependencies
+
+```sh
+# bump dependencies inside venv
+python -m pip install -U pip
+python -m pip install -U -r requirements/development.txt
+
+# install git hooks (pre-commit)
+pre-commit install
+```
+
+### 3. Dedicated QGIS profile
+
+It's recommended to create a dedicated QGIS profile for the development of the plugin to avoid conflicts with other plugins.
+
+1. From the command-line (a terminal with qgis executable in `PATH` or OSGeo4W Shell):
+
+    ```sh
+    # Linux
+    qgis --profile plg_gn_tools
+    # Windows - OSGeo4W Shell
+    qgis-ltr --profile plg_gn_tools
+    # Windows - PowerShell opened in the QGIS installation directory
+    PS C:\Program Files\QGIS 3.40.4\LTR\bin> .\qgis-ltr-bin.exe --profile plg_gn_tools
+    ```
+
+1. Then, set the `QGIS_PLUGINPATH` environment variable to the path of the plugin in profile preferences:
+
+    ![QGIS - Add QGIS_PLUGINPATH environment variable in profile settings](../static/dev_qgis_set_pluginpath_envvar.png)
+
+1. Finally, enable the plugin in the plugin manager (ignore invalid folders like documentation, tests, etc.):
+
+    ![QGIS - Enable the plugin in the plugin manager](../static/dev_qgis_enable_plugin.png)

docs/development/history.md

@@ -0,0 +1,2 @@
+```{include} ../../CHANGELOG.md
+```

docs/development/packaging.md

@@ -0,0 +1,43 @@
+# Packaging and deployment
+
+## Packaging
+
+This plugin is using the [qgis-plugin-ci](https://github.com/opengisch/qgis-plugin-ci/) tool to perform packaging operations.  
+Under the hood, the package command is performing a `git archive` run based on `CHANGELOG.md`.
+
+Install additional dependencies:
+
+```bash
+python -m pip install -U -r requirements/packaging.txt
+```
+
+Then use it:
+
+```bash
+# package a specific version
+qgis-plugin-ci package 1.3.1
+# package latest version
+qgis-plugin-ci package latest
+```
+
+## Release a version
+
+Everything is done through the continuous deployment, sticking to a classic git workflow: 1 released version = 1 git tag.
+
+Here comes the process for a tag `X.y.z` (which has to be SemVer compliant):
+
+1. Add the new version to the `CHANGELOG.md`..
+1. Optionally change the version number in `metadata.txt`. It's recommended to use the next version number with `-DEV` suffix (e.g. `1.4.0-DEV` when `X.y.z` is `1.3.0` ) to avoid confusion during the development phase.
+1. Apply a git tag with the relevant version: `git tag -a X.y.z {git commit hash} -m "This version rocks!"`
+1. Push tag to main branch: `git push origin X.y.z` or `git push --tags` if you want to push all tags at once.
+1. The CI/CD pipeline will be triggered and will create a new release on your Git repository and publish it to the [official QGIS plugins repository](https://plugins.qgis.org/) (if you picked up the option).
+
+If things go wrong (failed CI/CD pipeline, missed step...), here comes the fix process:
+
+```sh
+git tag -d old
+git push origin :refs/tags/old
+git push --tags
+```
+
+And try again!

docs/development/testing.md

@@ -0,0 +1,33 @@
+# Testing the plugin
+
+Tests are written in 2 separate folders:
+
+- `tests/unit`: testing code which is independent of QGIS API
+- `tests/qgis`: testing code which depends on QGIS API
+
+## Requirements
+
+- 3.30 < QGIS < 3.99
+
+```bash
+python -m pip install -U -r requirements/testing.txt
+```
+
+## Run unit tests
+
+```bash
+# run all tests with PyTest and Coverage report
+python -m pytest
+
+# run only unit tests with pytest launcher (disabling pytest-qgis)
+python -m pytest -p no:qgis tests/unit
+
+# run only QGIS tests with pytest launcher
+python -m pytest tests/qgis
+
+# run a specific test module using standard unittest
+python -m unittest tests.unit.test_plg_metadata
+
+# run a specific test function using standard unittest
+python -m unittest tests.unit.test_plg_metadata.TestPluginMetadata.test_version_semver
+```

docs/development/translation.md

@@ -0,0 +1,44 @@
+# Manage translations
+
+## Requirements
+
+Qt Linguist tools are used to manage translations. Typically on Ubuntu:
+
+```bash
+sudo apt install qttools5-dev-tools
+```
+
+## Workflow
+
+1. Generate the `plugin_translation.pro` file:
+
+    ```bash
+    python scripts/generate_translation_profile.py
+    ```
+
+1. Update `.ts` files:
+
+    ```bash
+    pylupdate5 -noobsolete -verbose gn_tools/resources/i18n/plugin_translation.pro
+    ```
+
+1. Translate your text using QLinguist or directly into `.ts` files. Launching it through command-line is possible:
+
+    ```bash
+    linguist gn_tools/resources/i18n/*.ts
+    ```
+
+1. Compile it:
+
+    ```bash
+    lrelease gn_tools/resources/i18n/*.ts
+    ```
+
+## Notes
+
+- Remember that the resulting `*.qm` file should not be tracked in git history since it's autogenerated and a binary file. The CI/CD pipeline will take care of generating it and packaging it. However, you can add the `*.qm` file to `.gitignore` to avoid any accidental commits.
+- The `pylupdate5` command is used to extract translatable strings from the source code and update the `.ts` files accordingly.
+- The `-no-obsolete` flag is important to avoid removing obsolete translations, which can be useful for maintaining the history of translations and ensuring that no existing translations are lost during updates.
+- The `-verbose` flag is used to provide detailed output during the translation update process, which can be helpful for debugging and ensuring that the process is working correctly.
+- The `linguist` command is used to launch the Qt Linguist application, which provides a graphical interface for translating the `.ts` files. This can be more user-friendly than editing the files directly in a text editor.
+- The `lrelease` command is used to compile the `.ts` files into `.qm` files, which are binary files used by Qt applications for translations.