Documentation: complete contributing guide and publish to GitHub Pages using GitHub Actions

.github/workflows/documentation.yml

@@ -0,0 +1,105 @@
+name: "📚 Documentation"
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/documentation.yml"
+      - "docs/*/**"
+      - "profile_manager/**/*.py"
+      - "profile_manager/metadata.txt"
+      - "requirements/documentation.txt"
+    tags:
+      - "*"
+
+  pull_request:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/documentation.yml"
+      - docs/**/*
+      - requirements/documentation.txt
+
+  workflow_dispatch:
+
+  workflow_run:
+    workflows:
+      - "Packager 📦"
+    types:
+      - completed
+
+# Allow one concurrent deployment per branch/pr
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  PROJECT_FOLDER: "profile_manager"
+  PYTHON_VERSION: 3.9
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Get source code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          cache: "pip"
+          cache-dependency-path: "requirements/documentation.txt"
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install -U -r requirements/documentation.txt
+
+      - name: Build doc using Sphinx
+        run: sphinx-build -b html -d docs/_build/cache -j auto docs docs/_build/html
+
+      - name: Save build doc as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation
+          path: docs/_build/html/*
+          if-no-files-found: error
+          retention-days: 30
+
+      - name: Download artifact from build workflow
+        if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main')
+        uses: dawidd6/action-download-artifact@19f6be5f04a702e84928b9c7db33da57bd5415c2
+        with:
+          allow_forks: false
+          branch: main
+          event: push
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          if_no_artifact_found: warn
+          name: ${{ env.PROJECT_FOLDER }}-latest
+          path: docs/_build/html/
+          # run_id: ${{ github.event.workflow_run.id }}
+          workflow: package_and_release.yml
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+        if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main')
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main')
+        with:
+          path: docs/_build/html/
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main')
+        uses: actions/deploy-pages@v4

docs/conf.py

@@ -0,0 +1,144 @@
+#!python3
+
+"""
+Configuration for project documentation using Sphinx.
+"""
+
+# standard
+import sys
+from datetime import datetime
+from os import path
+
+sys.path.insert(0, path.abspath(".."))  # move into project package
+
+# Package
+from profile_manager import __about__
+
+# -- 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.autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    # 3rd party
+    "myst_parser",
+    "sphinx_copybutton",
+]
+
+
+# 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 = "furo"
+
+# -- EXTENSIONS --------------------------------------------------------
+
+# Sphinx API doc
+autodoc_mock_imports = [
+    "qgis.core",
+    "qgis.gui",
+    "qgis.PyQt",
+    "qgis.PyQt.QtCore",
+    "qgis.PyQt.QtGui",
+    "qgis.PyQt.QtNetwork",
+    "qgis.PyQt.QtWidgets",
+    "qgis.utils",
+]
+
+# 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 = [
+    "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")
+
+
+# -- API Doc --------------------------------------------------------
+# run api doc
+def run_apidoc(_):
+    from sphinx.ext.apidoc import main
+
+    cur_dir = path.normpath(path.dirname(__file__))
+    output_path = path.join(cur_dir, "_apidoc")
+    modules = path.normpath(path.join(cur_dir, "../profile_manager"))
+    exclusions = ["../.venv", "../tests"]
+    main(["-e", "-f", "-M", "-o", output_path, modules] + exclusions)
+
+
+# launch setup
+def setup(app):
+    app.connect("builder-inited", run_apidoc)

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,55 @@
+# Development
+
+## Environment setup
+
+> Typically on Ubuntu (but should work on Windows).
+
+### 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
+```
+
+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
+```
+
+### 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 or OSGeo4W Shell):
+
+    ```sh
+    # Linux
+    qgis --profile plg_profile_manager
+    # Windows - OSGeo4W Shell
+    qgis-ltr --profile plg_profile_manager
+    # Windows - PowerShell opened in the QGIS installation directory
+    PS C:\Program Files\QGIS 3.40.4\LTR\bin> .\qgis-ltr-bin.exe --profile plg_profile_manager
+    ```
+
+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/index.md

@@ -0,0 +1,33 @@
+# {{ 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
+---
+usage/installation
+```
+
+```{toctree}
+---
+caption: Contribution guide
+maxdepth: 1
+---
+development/contribute
+development/environment
+development/documentation
+development/translation
+development/packaging
+development/history
+Code documentation <_apidoc/modules>
+```

docs/usage/installation.md

@@ -0,0 +1,9 @@
+# Installation
+
+## Stable version (recomended)
+
+This plugin is published on the official QGIS plugins repository: <https://plugins.qgis.org/plugins/profile_manager/>.
+
+## Beta versions released
+
+Enable experimental extensions in the QGIS plugins manager settings panel.

requirements/documentation.txt

@@ -0,0 +1,8 @@
+# Documentation (for devs)
+# -----------------------
+
+furo>=2024
+myst-parser[linkify]>=2
+sphinx-autobuild>=2024
+sphinx-copybutton>=0.5,<1
+sphinxext-opengraph>=0.4,<1