Skip to content

Commit 0f09faf

Browse files
GutsGuts
committed
Completing documentation
1 parent a0f83a2 commit 0f09faf

File tree

5 files changed

+191
-53
lines changed

5 files changed

+191
-53
lines changed

‎docs/index.md

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,36 @@
66
> **Source code:** {{ repo_url }}
77
> **Last documentation build:** {{ date_update }}
88
9-
---
9+
----
1010

1111
![QGIS Deployment Toolbelt CLI](/static/qgis-deployment-toolbelt_cli_help.png)
1212

13+
## What it is and the underlying philosophy
14+
15+
Development is développement est conçu selon les principes suivants :
16+
17+
- a tailor-made tool for QGIS ecosystem
18+
- open source and community driven
19+
- independant from the QGIS installation mode
20+
- packaged as CLI and prebuilt stand-alone binary
21+
- cross-platform but with a strong focus on Windows
22+
- documented
23+
- tested
24+
- usable with a single action (*one-click run*)
25+
- easily reusable
26+
- easily maintenable
27+
- compatible with automation mechanisms:
28+
- cron / scheduled tasks
29+
- 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/)
30+
- flexible enough to be adapted to an internal security policy (allowing to put a custom code certificate)
31+
32+
### It's not
33+
34+
- an installer for QGIS
35+
- a packager helper
36+
37+
----
38+
1339
```{toctree}
1440
---
1541
caption: How to use
@@ -19,9 +45,10 @@ usage/installation
1945
usage/how_it_works
2046
usage/how_to_use
2147
usage/profile
48+
usage/scenario
49+
jobs/index
2250
usage/cli
2351
usage/settings
24-
jobs/index
2552
usage/schedule_deployment
2653
```
2754

‎docs/usage/cli.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
## Main command
44

5+
Aliases : `qdt`, `qgis-deployment-toolbelt`, `qdeploy-toolbelt`
6+
57
```{sphinx_argparse_cli}
68
:module: qgis_deployment_toolbelt.cli
79
:hook:

‎docs/usage/how_it_works.md

Lines changed: 80 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,87 @@
1-
# How does it works
2-
3-
> TO DOC
1+
# How does it works: concepts and global workflow
42

53
## Concepts
64

7-
### Scenarios
5+
To run the workflow properly, you will need 3 items:
86

9-
> TO DOC
7+
| QGIS profiles | A scenario | The QDT executable |
8+
| -- | -- | -- |
9+
| ![icon profiles](/static/icon_profiles.svg) | ![icon scenario](/static/icon_scenario.svg) | ![icon QDT](/static/logo_qdt.png) |
1010

11-
### Jobs
11+
### QGIS profiles
1212

1313
> TO DOC
14+
15+
### Scenarios
16+
17+
Clearly inspired from Ansible and CI/CD platforms (especially GitLab CI, GitHub Actions), QDT uses scenario (YAML files) organised in sections, the main one allowing to define the tasks (called jobs) to be performed for the deployment.
18+
19+
```{button-link} ./scenario.html
20+
:color: primary
21+
:shadow:
22+
:expand:
23+
24+
Write your scenario
25+
```
26+
27+
----
28+
29+
## Functional workflow
30+
31+
### Typical roles
32+
33+
- GIS administrator: in charge of editing QGIS profiles and QDT scenarios
34+
- IT team: in charge of automating the QDT execution with its favourite tool
35+
- End-user: in charge of clicking on desktop Icons and playing with its favourite GIS software
36+
37+
### Flow chart
38+
39+
List of jobs mentioned here is just an example. Every scenario can adapt its own jobs to apply.
40+
41+
```{mermaid}
42+
flowchart TB
43+
A1 --> | push | G1
44+
A2 --> It
45+
It ---> | send or deploy | Enduser
46+
E1 --> E2 --> E3 --> E4 --> E5 --> E6 --> E7
47+
E5 <--> | clone/pull profiles | G1
48+
E6 <--> | download | Plugins
49+
50+
subgraph Org[Organization]
51+
direction LR
52+
subgraph It[IT Team]
53+
I1{{fa:fa-cog Deploy tools:<br>SCCM, GPO, remote script...}}
54+
end
55+
subgraph Admin[QGIS Administrator]
56+
A1(fa:fa-pen Edit profile.json files)
57+
A2(fa:fa-pen Edit scenario.qdt.yml)
58+
end
59+
subgraph Enduser[End-user computer]
60+
E1[QDT executable + scenario.qdt.yml]
61+
E2{RUN<br>cron / manual double-click}
62+
E3[Read scenario]
63+
E3>Set persistent environment variables]
64+
E5>Sync local profiles from repo]
65+
E6>Download and install plugins locally]
66+
E7>Create shortcuts to profiles]
67+
end
68+
end
69+
70+
subgraph Git[Git repository]
71+
direction LR
72+
G1([fa:fa-git https://git.myorg.net/qgis/profiles.git])
73+
end
74+
75+
subgraph Plugins[Plugins repositories]
76+
direction LR
77+
P1(["Official <br>plugins.qgis.org"])
78+
P2(["Custom <br>plugins.myorg.net"])
79+
end
80+
81+
82+
subgraph Legend
83+
direction LR
84+
L1>a QDT job]
85+
L2(["A website accessible through HTTP"])
86+
end
87+
```

‎docs/usage/how_to_use.md

Lines changed: 9 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,20 @@
11
# How to use
22

3-
## Using scenarios
4-
5-
This is the main way to use this toobelt. You write your deployment scenario by describing the steps to be done to prepare the QGIS environment, take a coffee (cup of tea is also tolerated) and look at the scenario running.
6-
7-
The format used is YAML and the syntax is largely inspired by DevOPS oriented tools like Ansible or CI/CD platforms (GitHub Actions, GitLab CI in particular).
8-
9-
By default, the toolbelt will look for a file named `scenario.qdt.yml` in the current directory.
10-
If it is not found, it will expect subcommands to run.
11-
12-
### Sample scenario
13-
14-
For development and test purposes, project provides a [sample scenario](https://github.com/Guts/qgis-deployment-cli/blob/main/tests/fixtures/scenarios/good_scenario_sample.qdt.yml):
15-
16-
```{eval-rst}
17-
.. literalinclude:: ../../tests/fixtures/scenarios/good_scenario_sample.qdt.yml
18-
:language: yaml
19-
```
20-
21-
### Validate scenario using JSON Schema
22-
23-
In order to minimize friction and maximize productivity, the project tries to provide a [schema.json](https://json-schema.org/) for scenarios files. If your editor supports YAML schema validation, it's definitely recommended to set it up.
24-
25-
#### Generic
26-
27-
1. Ensure your editor of choice has support for YAML schema validation.
28-
2. Add the following lines at the top of your scenario file:
29-
30-
```yaml
31-
# yaml-language-server: $schema=https://raw.githubusercontent.com/Guts/qgis-deployment-cli/main/docs/schemas/scenario/schema.json
32-
```
3+
## As a CLI
334

34-
#### Visual Studio Code
5+
To use as a CLI, make sure to remove any `scenario.qdt.yml` file from the current directory.
356

36-
1. Install the [vscode-yaml](https://marketplace.visualstudio.com/items?itemname=redhat.vscode-yaml) extension for YAML language support.
37-
2. Add the schema under the `yaml.schemas` key in your user or workspace [`settings.json`](https://code.visualstudio.com/docs/getstarted/settings):
7+
Then, you can use the following commands:
388

39-
```json
40-
{
41-
"yaml.schemas": {
42-
"https://raw.githubusercontent.com/Guts/qgis-deployment-cli/main/docs/schemas/scenario/schema.json": "*.qdt.yml"
43-
}
44-
}
9+
```sh
10+
qgis-deployment-toolbelt --help
11+
qdeploy-toolbelt --verbose upgrade --check-only
12+
qdt deploy -vv -s https://gitlab.com/Oslandia/qgis/profils_qgis_fr_2022/-/raw/main/qdt_scenarii/scenario.qdt.yml?inline=false
4513
```
4614

47-
---
48-
49-
## As a CLI
50-
51-
To use as a CLI, make sure to remove any `scenario.qdt.yml` file from the current directory.
15+
See: [Command-line interface usage](./cli.md)
5216

53-
Then, you can use the following commands:
17+
## Sample
5418

5519
```sh
5620
qgis-deployment-toolbelt --help

‎docs/usage/scenario.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Write your deployment scenario
2+
3+
## What is a scenario?
4+
5+
This is the main way to use QDT. You write your deployment scenario by describing the steps to be done to prepare the QGIS environment, take a coffee (cup of tea is also tolerated) and look at the scenario running.
6+
7+
In concrete terms, a scenario is a [YAML file](https://fr.wikipedia.org/wiki/YAML) whose extension (`.yaml` or `.yml`) can be suffixed with `.qdt` so as to be more easily distinguished by the tool in the midst of potential other YAML files. Example: `scenario.qdt.yml`. The syntax is largely inspired by DevOPS oriented tools like Ansible or CI/CD platforms (GitHub Actions, GitLab CI in particular).
8+
9+
A scenario has 3 sections:
10+
11+
- `metadata`: to describe the scenario (title, description, etc.)
12+
- `settings`: to set execution parameters to be applied to QDT, in the form of keys/values
13+
- `steps`: the steps that the deployment scenario will successively take. Each step can call for a "job".
14+
15+
By default, QDT looks for a file named `scenario.qdt.yml` in the current directory.
16+
If it is not found, it will expect subcommands to run.
17+
18+
### Jobs
19+
20+
A *job* is a logical module that is called by a *step* in a *scenario*, by passing it parameters. Concretely, each job is a Python module of QDT ([here in the code](https://guts.github.io/qgis-deployment-cli/_apidoc/qgis_deployment_toolbelt.jobs.html)).
21+
22+
A step consists of 3 elements:
23+
24+
- `name`: the name of the step
25+
- `uses` : the job identifier to use
26+
- with` : the parameters to pass to the Job
27+
28+
```{button-link} ../jobs/index.html
29+
:color: primary
30+
:shadow:
31+
:expand:
32+
33+
See available jobs
34+
```
35+
36+
## Sample scenario
37+
38+
For development and test purposes, project provides a [sample scenario](https://github.com/Guts/qgis-deployment-cli/blob/main/tests/fixtures/scenarios/good_scenario_sample.qdt.yml):
39+
40+
```{eval-rst}
41+
.. literalinclude:: ../../tests/fixtures/scenarios/good_scenario_sample.qdt.yml
42+
:language: yaml
43+
```
44+
45+
### Validate scenario using JSON Schema
46+
47+
In order to minimize friction and maximize productivity, the project tries to provide a [schema.json](https://json-schema.org/) for scenarios files. If your editor supports YAML schema validation, it's definitely recommended to set it up.
48+
49+
#### Generic
50+
51+
1. Ensure your editor of choice has support for YAML schema validation.
52+
2. Add the following lines at the top of your scenario file:
53+
54+
```yaml
55+
# yaml-language-server: $schema=https://raw.githubusercontent.com/Guts/qgis-deployment-cli/main/docs/schemas/scenario/schema.json
56+
```
57+
58+
#### Visual Studio Code
59+
60+
1. Install the [vscode-yaml](https://marketplace.visualstudio.com/items?itemname=redhat.vscode-yaml) extension for YAML language support.
61+
2. Add the schema under the `yaml.schemas` key in your user or workspace [`settings.json`](https://code.visualstudio.com/docs/getstarted/settings):
62+
63+
```json
64+
{
65+
"yaml.schemas": {
66+
"https://raw.githubusercontent.com/Guts/qgis-deployment-cli/main/docs/schemas/scenario/schema.json": "*.qdt.yml"
67+
}
68+
}
69+
```
70+
71+
---

0 commit comments

Comments
 (0)