init plugin

docs/conf.py

@@ -0,0 +1,133 @@
+#!python3
+
+"""Configuration for project documentation using Sphinx."""
+
+# standard
+import sys
+from datetime import datetime
+from os import environ, path
+
+sys.path.insert(0, path.abspath(".."))  # move into project package
+
+# 3rd party
+import sphinx_rtd_theme  # noqa: F401 theme of Read the Docs
+
+# Package
+from gn_tools import __about__
+
+# -- Build environment -----------------------------------------------------
+on_rtd = environ.get("READTHEDOCS", None) == "True"
+
+# -- Project information -----------------------------------------------------
+author = __about__.__author__
+copyright = __about__.__copyright__
+description = __about__.__summary__
+project = __about__.__title__
+version = release = __about__.__version__
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    # Sphinx included
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    # 3rd party
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx_rtd_theme",
+]
+
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+source_suffix = {".md": "markdown", ".rst": "restructuredtext"}
+autosectionlabel_prefix_document = True
+# The master toctree document.
+master_doc = "index"
+
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = [
+    "_build",
+    ".venv",
+    "Thumbs.db",
+    ".DS_Store",
+    "_output",
+    "ext_libs",
+    "tests",
+    "demo",
+]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# -- Theme
+
+html_favicon = str(__about__.__icon_path__)
+html_logo = str(__about__.__icon_path__)
+# uncomment next line if you store some statics which are not directly linked into the markdown/RST files
+# html_static_path = ["static/include_additional"]
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "display_version": True,
+    "logo_only": False,
+    "prev_next_buttons_location": "both",
+    "style_external_links": True,
+    "style_nav_header_background": "SteelBlue",
+    # Toc options
+    "collapse_navigation": True,
+    "includehidden": False,
+    "navigation_depth": 4,
+    "sticky_navigation": False,
+    "titles_only": False,
+}
+
+# -- EXTENSIONS --------------------------------------------------------
+
+# Configuration for intersphinx (refer to others docs).
+intersphinx_mapping = {
+    "PyQt5": ("https://www.riverbankcomputing.com/static/Docs/PyQt5", None),
+    "python": ("https://docs.python.org/3/", None),
+    "qgis": ("https://qgis.org/pyqgis/master/", None),
+}
+
+# MyST Parser
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_image",
+    "linkify",
+    "replacements",
+    "smartquotes",
+    "substitution",
+]
+
+myst_substitutions = {
+    "author": author,
+    "date_update": datetime.now().strftime("%d %B %Y"),
+    "description": description,
+    "qgis_version_max": __about__.__plugin_md__.get("general").get(
+        "qgismaximumversion"
+    ),
+    "qgis_version_min": __about__.__plugin_md__.get("general").get(
+        "qgisminimumversion"
+    ),
+    "repo_url": __about__.__uri__,
+    "title": project,
+    "version": version,
+}
+
+myst_url_schemes = ("http", "https", "mailto")

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.

docs/index.md

@@ -0,0 +1,34 @@
+# {{ title }} - Documentation
+
+> **Description:** {{ description }}  
+> **Author and contributors:** {{ author }}  
+> **Plugin version:** {{ version }}  
+> **QGIS minimum version:** {{ qgis_version_min }}  
+> **QGIS maximum version:** {{ qgis_version_max }}  
+> **Source code:** {{ repo_url }}  
+> **Last documentation update:** {{ date_update }}
+
+----
+
+```{toctree}
+---
+caption: Usage
+maxdepth: 1
+---
+Installation <usage/installation>
+```
+
+```{toctree}
+---
+caption: Contribution guide
+maxdepth: 1
+---
+development/code_of_conduct
+development/contribute
+development/environment
+development/documentation
+development/translation
+development/packaging
+development/testing
+development/history
+```

docs/usage/installation.md

@@ -0,0 +1,19 @@
+# Installation
+
+## Stable version (recomended)
+
+This plugin is published on the official QGIS plugins repository: <https://plugins.qgis.org/plugins/gn_tools/>.
+
+## Beta versions released
+
+Enable experimental extensions in the QGIS plugins manager settings panel.
+
+## Earlier development version
+
+If you define yourself as early adopter or a tester and can't wait for the release, the plugin is automatically packaged for each commit to main, so you can use this address as repository URL in your QGIS extensions manager settings:
+
+```url
+https://gitea.cenra-outils.org/CEN38/gn_tools/pages/plugins.xml
+```
+
+Be careful, this version can be unstable.