Update documentation

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 438b348f6092dc88e8f1953419b66fef
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/development/contributing.md.txt

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

_sources/development/documentation.md.txt

@@ -0,0 +1,46 @@
+# Documentation
+
+This documentation website is generated using Sphinx and deployed on [GitHub pages](https://pages.github.com/) using GitHub Actions.
+
+To work on the documentation, install the related requirements:
+
+```bash
+python -m pip install -U -r requirements/documentation.txt
+```
+
+## Write
+
+The documentation is divided into categories. To update a particular page, find the markdown file in the related folder:
+
+- for end-users: `docs/usage`
+- for developers: `docs/development`
+
+Put images in the `assets` directory.
+
+````{tip}
+To see live rendering of your documentation, you can run:
+
+```bash
+sphinx-autobuild -b html -d docs/_build/cache docs docs/_build/html
+```
+````
+
+After you make changes to the documentation, please make a PR.
+
+## Build
+
+```bash
+sphinx-build -b html -d docs/_build/cache -j auto -q docs docs/_build/html
+```
+
+Open `docs/_build/index.html` in a web browser.
+
+## Deploy
+
+Documentation website is hosted on GitHub Pages. Deployment takes advantage of [`ghp-import` library](https://pypi.org/project/ghp-import/). It's automatically triggered on CI but it's still possible to deploy it manually:
+
+```bash
+ghp-import --force --no-jekyll --push docs/_build/html
+```
+
+Files are uploaded to the branch `gh-pages` of the repository: <https://github.com/QGIS-Contribution/QGIS-ResourceSharing/tree/gh-pages>.

_sources/development/environment.md.txt

@@ -0,0 +1,32 @@
+# Development environment setup
+
+Clone the repository, then follow these steps.
+
+It's strongly recomended to develop into a virtual environment:
+
+```bash
+python3 -m venv --system-site-packages .venv
+```
+
+```{note}
+We link to system packages to keep the link with installed QGIS Python libraries: PyQGIS, PyQT, etc.
+```
+
+In your virtual environment:
+
+```bash
+# use the latest pip version
+python -m pip install -U pip
+# install development tools
+python -m pip install -U -r requirements/development.txt
+# install external dependencies
+python -m pip install --no-deps -U -r requirements/embedded.txt -t RoofClassify/embedded_external_libs
+# install pre-commit to respect common development guidelines
+pre-commit install
+```
+
+## Additionnal external dependencies
+
+This plugin has external dependencies listed in this specific file: <requirements/embedded.txt>
+
+Because it's still hard to install Python 3rd party packages from an index (for example <https://pypi.org>), especially on Windows or Mac systems (or even on Linux if we want to do it properly in a virtual environment), those required packages are stored in the `embedded_external_libs` folder.

_sources/development/history.md.txt

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

_sources/development/packaging.md.txt

@@ -0,0 +1,28 @@
+# Packaging and deployment
+
+## Packaging
+
+This plugin is using the [qgis-plugin-ci](https://github.com/opengisch/qgis-plugin-ci/) tool to perform packaging operations.
+
+```bash
+python -m pip install -U -r requirements/packaging.txt
+```
+
+Then use it:
+
+```bash
+# package a specific version
+qgis-plugin-ci package 1.5.2
+# package the latest version documented into the changelog
+qgis-plugin-ci package latest
+```
+
+## Release a version
+
+Follow the git workflow:
+
+1. Fillfull the `CHANGELOG.md`
+2. Apply a git tag with the relevant version: `git tag -a 0.3.0 {git commit hash} -m "New plugin UI"`
+3. Push tag to master
+4. Once the [release workflow](https://github.com/DINFO-UniFI/RoofClassify/actions/workflows/packager.yml) is over, check everything went fine
+5. Double-check if the uploaded plugin on the official QGIS plugins repository is the same  as the one published on Github Release and has a relevant size. If not, fix it by manually uploading the plugin to the official QGIS plugins repository.

_sources/development/testing.md.txt

@@ -0,0 +1,50 @@
+# Tests
+
+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
+
+- QGIS 3.16+
+
+```bash
+python -m pip install -U pip
+python -m pip install -U -r requirements/testing.txt
+```
+
+## Running tests
+
+```bash
+# run all tests with PyTest and Coverage report
+python -m pytest
+
+# run only unit tests
+python -m pytest tests/unit
+
+# run only QGIS tests
+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
+```
+
+### Using Docker
+
+Build the image:
+
+```bash
+docker build --pull --rm -f "tests/tests_qgis.dockerfile" -t qgis_316:plugin_tester .
+```
+
+Run tests:
+
+```bash
+docker run -v "$(pwd):/tmp/plugin" qgis_316:plugin_tester python3 -m pytest
+```
+
+Please note that will use the root rights on some folders.

_sources/development/translation.md.txt

@@ -0,0 +1,24 @@
+# Manage translations
+
+## Requirements
+
+Qt Linguist tools are used to manage translations. Typically on Ubuntu 22.04:
+
+```bash
+sudo apt install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qttools5-dev-tools
+```
+
+## Workflow
+
+1. Update `.ts` files:
+
+    ```bash
+    pylupdate5 -noobsolete -verbose RoofClassify/resources/i18n/plugin_translation.pro
+    ```
+
+2. Translate your text using QLinguist or directly into `.ts` files.
+3. Compile it:
+
+    ```bash
+    lrelease RoofClassify/resources/i18n/*.ts
+    ```

_sources/index.md.txt

@@ -0,0 +1,47 @@
+# {{ 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 }}
+
+----
+
+## Quickstart
+
+Open the plugins GUI by clicking to its icon or from the plugin menu entry `Plugins`-> `ClassifyRoofs`.
+
+![RoofClassify GUI](/static/gui_form_classification.png "RoofClassify GUI")
+
+Fill the entries with the requested paths and click `ok`
+
+----
+
+```{toctree}
+---
+caption: User manual
+maxdepth: 1
+---
+usage/installation
+usage/settings
+```
+
+----
+
+```{toctree}
+---
+caption: Contribution guide
+maxdepth: 1
+---
+development/contributing
+misc/credits
+development/environment
+development/documentation
+development/translation
+development/packaging
+development/testing
+development/history
+```

_sources/misc/credits.md.txt

@@ -0,0 +1,17 @@
+# Credits and sponsoring
+
+The original script version was developed by Alessandro Bacciottini and Arjan Feta for the Università degli Studi di Firenze (UNIFI).
+
+In 2021, it has been completely refactored to work under QGIS 3, with a simple installation and usage workflow even for Windows users. This work has been developed by Oslandia (<https://www.oslandia.com>) and sponsored by ANR - Programme ERASEd - ANR-18-CE03-0001-01, through IRD, the *Institut de Recherche pour le Développement* (the French National Research Institute for Sustainable Development).
+
+## Sponsors
+
+- ANR - Programme ERASEd - ANR-18-CE03-0001-01
+
+## Funding
+
+```{admonition} Ready to contribute?
+Plugin is free to use, not to develop. If you use it quite intensively or are interested in improving it, please consider to contribute to the code, to the documentation or fund some developments:
+
+Want to fund? Please, [send us an email](mailto:[email protected])
+```

_sources/usage/installation.md.txt

@@ -0,0 +1,83 @@
+# Installation
+
+## Requirements
+
+The plugin's logic is mainly based on a well-known machine learning toolkit: [scikit-learn](https://scikit-learn.org/stable/). To work, the plugin needs it and it's quite a challenge to install it on QGIS for Windows, because QGIS uses its own Python interpreter and doesn't make it easy to use packages manager (`pip`).
+
+To make it easier for Windows end-users, we did our best to embed the dependencies within the released version of the plugin, inside the `embedded_external_libs` folder.
+
+Technically, the plugin tries to:
+
+1. import Scikit-learn from the Python interpreter used by QGIS (system on Linux, specific on Windows)
+1. add `embedded_external_libs` to the `PYTHONPATH` and then import Scikit-Learn from it
+
+**BUT** there are some caveats because
+
+### Linux
+
+> Mainly tested on Ubuntu 20.04.
+
+- {{ qgis_version_min }} =< QGIS =< {{ qgis_version_max }}
+- Python 3.8+
+- dependencies listed in `requirements/embedded.txt`. On Linux, you need to install them by yourself. Typically, on Ubuntu:
+
+```bash
+# using the requirements file if you have the plugin repository
+python3 -m pip install --no-deps -U -r requirements/embedded.txt
+# or directly - refer to the file to be sure of using the right updated pinned versions
+python3 -m pip install --no-deps -U "joblib==1.1.*" "scikit-learn==1.0.*" "threadpoolctl>=2,<3"
+```
+
+:::{important}
+**Remember** to look at the `requirements/embedded.txt` file to make sure you are using the right versions. The above command is just an example, a pattern.
+:::
+
+### Windows
+
+> Mainly tested on Windows 10.0.19044.
+
+- {{ qgis_version_min }} =< QGIS =< {{ qgis_version_max }}
+- Python 3.9 (strictly)
+
+### Use it with a different Python version (manual install)
+
+1. Launch the `OSGeo4W Shell`. Look for it in your Windows Search or directly into your QGIS install folder:
+    - installed with the _all inclusive_ standalone `.msi`: `C:\Program Files\QGIS`
+    - installed with the OSGeo4W with default settings: `C:\OSGeo4W`
+1. Run:
+
+  ```batch
+  python-qgis-ltr -m pip install -U pip
+  python-qgis-ltr -m pip install -U setuptools wheel
+  python-qgis-ltr -m pip install -U "joblib==1.1.*" "scikit-learn==1.0.*" "threadpoolctl>=2,<3"
+  ```
+
+:::{important}
+**Remember** to look at the `requirements/embedded.txt` file to make sure you are using the right versions. The above command is just an example, a pattern.
+:::
+
+---
+
+## Stable version (recomended)
+
+This plugin is published on the official QGIS plugins repository: <https://plugins.qgis.org/plugins/RoofClassify/>.
+
+Go to `Plugins` -> `Manage and Install Plugins`, look for the plugin and install it.
+
+## Beta versions released
+
+Enable experimental extensions in the QGIS plugins manager settings panel.
+
+## Alternate plugins repository
+
+During the release workflow (see [Packaging and deployment](/development/packaging.md)), the plugin is packaged and released on the official QGIS plugins repository but also as a GitHub Release, right aside the repository.
+
+You can add the following URL to the QGIS extensions repositories, in the `Settings` tab of the `Plugins Manager` window (see [official documentation](https://docs.qgis.org/3.16/en/docs/user_manual/plugins/plugins.html#the-settings-tab)):
+
+```html
+https://github.com/DINFO-UniFI/RoofClassify/releases/latest/download/plugins.xml
+```
+
+:::{warning}
+As GitHub Releases publishes only stable releases through its *latest* API, only not tagged releases as pre-release are available.
+:::

_sources/usage/settings.md.txt

@@ -0,0 +1,17 @@
+# Settings
+
+To manage plugin settings, open the `Preferences` menu and select `Settings` within QGIS.
+
+## Available preferences
+
+### Number of parallelized jobs
+
+How many threads should be used for parallelization.
+
+Default: 2.
+
+### Debug mode
+
+Increase plugin verbosity.
+
+Default: False.