Complete user manual (#268)

Author: Guts

.vscode/settings.json

@@ -18,10 +18,9 @@
     "python.terminal.activateEnvInCurrentTerminal": true,
     "python.terminal.activateEnvironment": true,
     // Formatter
-    "python.formatting.provider": "black",
-    "python.formatting.blackArgs": [
-        "--target-version=py38"
-    ],
+    "[python]": {
+        "editor.defaultFormatter": "ms-python.black-formatter"
+    },
     // Linter
     "python.linting.enabled": true,
     "python.linting.flake8Enabled": true,

CONTRIBUTING.md

@@ -4,6 +4,11 @@ First off, thanks for considering to contribute to this project!
 
 These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
 
+## Versioning and changelog
+
+This project adheres to [Semantic Versioning](https://semver.org/).  
+The CHANGELOG format tries to complies with [Keep a Changelog](https://keepachangelog.com/) but it's mainly a concatenation of autogenerated release notes by GitHub Release.
+
 ## Git hooks
 
 We use git hooks through [pre-commit](https://pre-commit.com/) to enforce and automatically check some "rules". Please install it before to push any commit.

README.md

@@ -14,9 +14,9 @@
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/qgis-deployment-toolbelt)](https://pypi.org/project/qgis-deployment-toolbelt/)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/qgis-deployment-toolbelt)](https://pypi.org/project/qgis-deployment-toolbelt/)
 
-Cross-platform (but Windows focused) CLI to perform deployment operations: profiles, plugins, etc.
+Cross-platform (but Windows focused) CLI to perform deployment operations aorund QGIS: profiles, plugins, etc.
 
-**Interested**? For further details, [read the documentation](https://guts.github.io/qgis-deployment-cli//) :books:.
+**Interested**? For further details, [read the documentation](https://guts.github.io/qgis-deployment-cli/) :books:.
 
 ## Contribute
 

docs/conf.py

@@ -97,8 +97,8 @@
 # -- Options for HTML output -------------------------------------------------
 
 # Theme
-# html_favicon = "static/img/qgis_deployment_toolbelt_logo_200px.png"
-# html_logo = "static/img/qgis_deployment_toolbelt_logo_200px.png"
+html_favicon = "static/logo_qdt.png"
+html_logo = "static/logo_qdt.png"
 html_theme = "furo"
 html_theme_options = {
     "source_repository": __about__.__uri__,
@@ -146,7 +146,7 @@
     "--theme",
     "forest",
     "--width",
-    "600",
+    "100%",
     "--backgroundColor",
     "transparent",
 ]
@@ -247,4 +247,4 @@ def run_apidoc(_):
 # launch setup
 def setup(app):
     app.connect("builder-inited", run_apidoc)
-    app.connect("builder-inited", populate_download_page)
+    # app.connect("builder-inited", populate_download_page)

docs/index.md

@@ -6,10 +6,36 @@
 > **Source code:** {{ repo_url }}  
 > **Last documentation build:** {{ date_update }}
 
----
+----
 
 ![QGIS Deployment Toolbelt CLI](/static/qgis-deployment-toolbelt_cli_help.png)
 
+## What it is and the underlying philosophy
+
+Development is  développement est conçu selon les principes suivants :
+
+- a tailor-made tool for QGIS ecosystem
+- open source and community driven
+- independant from the QGIS installation mode
+- packaged as CLI and prebuilt stand-alone binary
+- cross-platform but with a strong focus on Windows
+- documented
+- tested
+- usable with a single action (*one-click run*)
+- easily reusable
+- easily maintenable
+- compatible with automation mechanisms:
+  - cron / scheduled tasks
+  - Windows [groups policies](https://en.wikipedia.org/wiki/Group_Policy) (so called GPO for *Group Policies Object*) and [tooling around client management](https://learn.microsoft.com/en-us/windows/client-management/)
+- flexible enough to be adapted to an internal security policy (allowing to put a custom code certificate)
+
+### It's not
+
+- an installer for QGIS
+- a packager helper
+
+----
+
 ```{toctree}
 ---
 caption: How to use
@@ -19,9 +45,10 @@ usage/installation
 usage/how_it_works
 usage/how_to_use
 usage/profile
+usage/scenario
+jobs/index
 usage/cli
 usage/settings
-jobs/index
 usage/schedule_deployment
 ```
 
@@ -47,6 +74,7 @@ caption: Miscellaneous
 maxdepth: 1
 ---
 misc/compatibility
+misc/tip_get_plugin_id
 misc/credits
 misc/funding
 ```

docs/misc/compatibility.md

@@ -8,5 +8,5 @@ The executable has been tested on Windows 10+.
 
 The Python script is multiplatform (in theory...) and has been tested on:
 
-- Ubuntu 20.04
+- Ubuntu 22.04
 - Windows 10

docs/misc/credits.md

@@ -11,10 +11,19 @@
 
 ```
 
+----
+
 ## Licenses
 
 > Generated with [pip-licenses](https://pypi.org/project/pip-licenses/)
 
 ```{include} licenses.md
 
 ```
+
+----
+
+## Images
+
+- film scenario [by Berkah Icon from Noun Project](https://thenounproject.com/browse/icons/term/film-scenario/) under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)
+- profiles icon [by Lil Squid from Noun Project](https://thenounproject.com/browse/icons/term/profiles/) under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)

docs/misc/tip_get_plugin_id.md

@@ -0,0 +1,8 @@
+# How to get a plugin ID
+
+1. Open the repository in your browser. Example for the official set on QGIS 3.28: <https://plugins.qgis.org/plugins/plugins.xml?qgis=3.28>
+1. Open the RAW mode (or source), typing `Ctrl + U` or right-click and  select `View page source`
+1. Use your browser search `Ctrl + F` to look for the plugin you want
+1. Grab the `plugin_id` attribute:
+
+  ![Plugin ID into official repository - Example QuickOSM](/static/repository_plugins_plugin_id.webp)