Documentation workflow - Merge #177 from QGIS-Contribution/docs-auto-…

…publish

Documentation workflow: auto-publish from master to gh-pages

.github/workflows/blacker.yml

@@ -10,11 +10,19 @@ on:
     paths:
       - '**.py'
 
+env:
+  PYTHON_VERSION: 3.7
 
 jobs:
   format:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - name: Get source code
+        uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
       - uses: psf/black@stable

.github/workflows/documentation.yml

@@ -0,0 +1,50 @@
+name: Doc build and deploy
+
+on:
+  push:
+    branches: [ master ]
+    paths:
+      - 'docs/*/**'
+      - '.github/workflows/documentation.yml'
+
+env:
+  PYTHON_VERSION: 3.7
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Get source code
+      uses: actions/checkout@v2
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+
+    - name: Cache
+      uses: actions/cache@v2
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('requirements/documentation.txt') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+
+    - 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 docs docs/_build/html
+
+    - name: Upload doc as artifact
+      uses: actions/upload-artifact@v2
+      with:
+        name: Documentation HTML build
+        path: docs/_build
+
+    - name: Deploy to GitHub Pages
+      run: ghp-import --force --no-jekyll --push docs/_build/html

.github/workflows/linter.yml

@@ -1,4 +1,4 @@
-name: Linter
+name: Linter 🐍
 
 env:
   PROJECT_FOLDER: "resource_sharing"
@@ -39,8 +39,6 @@ jobs:
         run: |
           python -m pip install -U -r requirements/base.txt
           python -m pip install -U -r requirements/development.txt
-      # -- COMMENTED thanks to @Gustry comments
-      #     python -m pip install --no-deps -U -r requirements/embedded.txt -t ext_libs
 
       - name: Lint with flake8
         run: |

docs/authoring/creating-metadata.md

@@ -0,0 +1,57 @@
+# Creating metadata
+
+In the root of the repository, there has to be a metadata file describing the repository and its collections.
+
+## General
+
+The metadata file (`metadata.ini`) must have a `general` section with this information:
+
+| Name | Status | Description |
+| :--- | :----: | :---------- |
+| collection | Required | Comma separated list of collection names (these have to match the directory names of the collections) |
+
+## Collection
+
+For each collection, metadata are needed. The section must be named by the name defined in the general section.
+
+This is the contents of the collection section:
+
+| Name | Status | Description |
+| :--- | :----: | :---------- |
+| author | Required | Author's name |
+| description | Required | Additional information about the collection |
+| email | Optional | Author's email |
+| license | Optional | The license of the collection e.g GNU GPL |
+| license_file | Optional | License file (path relative to the collection root) |
+| name | Required | The name of the collection |
+| preview | Optional | Comma separated list of preview images (paths relative to the collection root) |
+| qgis_minimum_version | Optional | Minimum QGIS version. If not specified, the minimum version will be 2.0 |
+| qgis_maximum_version | Optional | Maximum QGIS version. If not specified, the maxium version will be 3.99 |
+| tags | Required | Comma separated list of tags |
+
+This is an example of the `metadata.ini` file:
+
+```ini
+[general]
+collections=osm_spatialite_googlemaps,flowmap
+
+[osm_spatialite_googlemaps]
+name=OSM Spatialite Googlemaps
+author=Anita Graser
+email[email protected]
+tags=osm,spatialite,google maps,roads
+description=The collection contains a complete resources to create a coherent map that looks similar to the old Google Maps style from OSM data in a SpatiaLite database
+preview=preview/osm_spatialite_googlemaps.png, preview/osm_spatialite_googlemaps_lines.png
+qgis_minimum_version=2.0
+qgis_maximum_version=3.99
+
+[flowmap]
+name=Flowmap
+author=Anita Graser
+email[email protected]
+tags=flows, arrows
+description=The collection contains styles for flow maps
+preview=preview/preview.png
+qgis_minimum_version=2.0
+qgis_maximum_version=3.99
+```

docs/authoring/creating-repository.md

@@ -0,0 +1,134 @@
+# Creating a repository
+
+## Preparing the Repository
+
+In order for the tools to parse the repository correctly, the repository must have a certain structure. This is what you need to do:
+
+1. Go to [this page](repository-structure) to get information about the expected structure.
+2. Create correct metadata for the repository (consult [this page](creating-metadata)).
+3. When you have prepared your repository, you can check if the repository is all good by trying it using the file system handler.
+
+In the plugin, go to the `Settings` tab and add a new repository pointing to the root of the repository in your local file system. The repository URL looks like this:
+
+- Linux: `file:///home/pointing/to/repository_root`
+- Windows: `file://C:/home/pointing/to/repository_root`
+
+----
+
+## Where can you share it?
+
+These are the options for sharing: on Github, GitLab, Bitbucket (they need to be public repositories), Gogs (_Go Git Service_), local file system (if you want to share the collections with your colleagues on the network), or in your own server with the HTTP(S) protocol.
+
+### Github, GitLab and Bitbucket
+
+There is nothing complicated here if you are already familiar with git.
+
+After preparing the repository on your local machine, you can make it into a git repository as usual.
+In general, you can do:
+
+```bash
+cd <repository root>
+git init
+git add .
+git commit -m "Created a cool repository for cool users."
+git remote add origin <remote repository URL>
+git push origin master
+```
+
+Note that you currently need to use the `master` branch for your repository.
+
+### Local File System
+
+This is even simpler.
+
+After preparing the repository, you can use it right away.
+
+In the `Settings` tab, you add a repository with URL pointing to the repository root in your local machine (absolute path, example: `file:/home/user/QGIS-collections/mycollection`).
+
+It's as simple as that.
+
+If there is a problem with metadata or other issues when adding the
+repository, you will be told.
+
+### Your Own Server
+
+This option could be useful in some cases, e.g. if you want to make private collections available for your customers.
+
+There are some additional requirements that you need to be aware of if you choose this option:
+
+- The URL structure of the repository. If your repository URL is `http://www.mydomain.com/qgisrepository/`, you must make the metadata available on: `http://www.mydomain.com/qgisrepository/metadata.ini`
+- Each collection must be zipped. The zip file of a collection must be named `<name of collection>.zip`, and the zip shall combine the subdirectories of the collection (one or more of `checklists`, `expressions`, `image`, `models`, `processing`, `rscripts`, `svg` and `symbol`), in addition to a `preview` subdirectory for preview images.
+
+For example, if you have a collection named `test_collection`, the collection must be present as: `http://www.mydomain.com/qgisrepository/collections/test_collection.zip`, and the structure of this zip file must be (only include directories that contain resources you would like to share):
+
+```txt
+test_collection.zip
+├── checklists
+├── expressions
+├── image
+├── models
+├── preview
+├── processing
+├── rscripts
+├── svg
+├── symbol
+```
+
+- Preview images that illustrates the collection should be included. If you define preview images for collection `test_collection` in metadata (`preview=preview/prev1.png,prev2.png`), you have to place these preview images in the zip-file in a separate directory. `preview` is the recommended name for that directory.
+
+An example server directory setup for the repository `myfirstrepository` with one collection (`test_collection`) that contains resources to share in a lot of resource categories:
+
+```ascii
+      qgisrepository
+      ├── metadata.ini
+      └── collections
+          └── test_collection.zip
+              ├── checlists
+              |   ├── checklist1.json
+              |   ├── ...
+              |   └── lastchecklist.json
+              ├── expressions
+              |   ├── expressions1.json
+              |   ├── ...
+              |   └── lastexpressions.json
+              ├── image
+              |   ├── image1.png
+              |   ├── ...
+              |   └── lastimage.png
+              ├── models
+              |   ├── firstmodel.model3
+              |   ├── ...
+              |   └── testmodel.model3
+              ├── preview
+              |   ├── prev1.png
+              |   └── prev2.png
+              ├── processing
+              |   ├── firstscript.py
+              |   ├── ...
+              |   └── testscript.py
+              ├── rscripts
+              |   ├── firstRscript.rsx
+              |   └──firstRscript.rsx.help
+              |   ├── ...
+              |   ├── testRscript.rsx
+              |   └── testRscript.rsx.help
+              ├── style
+              |   ├── firstlayerstyle.qml
+              |   ├── ...
+              |   └── testlayerstyle.qml
+              ├── svg
+              |   ├── firstmodel.model3
+              |   ├── ...
+              |   └── testmodel.model3
+              └── symbol
+                  ├── firststyle.xml
+                  ├── ...
+                  └── teststyle.xml
+
+```
+
+The repository URL to be used when adding the repository (in the _QGIS Resource Sharing_ plugin): `http://www.mydomain.com/qgisrepository/`.
+
+You can also use authentication for this repository.
+
+Users can configure authentication details in the plugin, so that they will be able to fetch the repository and the collections inside.

docs/authoring/publishing-repository.md

@@ -0,0 +1,14 @@
+# Publishing your repository
+
+When everything is done, and you have published the repository somewhere, you can add the repository in the
+_QGIS Resource Sharing_ plugin in QGIS.
+
+You may wonder if you can have your repository included as a default repository that will be shown to all QGIS users without them
+needing to add the repository manually.
+
+Well, yes, that may be possible.
+
+To offer your repository as a default repository, fork the [QGIS official resource repository](https://github.com/qgis/QGIS-Resources), update the [`directory.csv`](https://github.com/qgis/QGIS-Resources/blob/master/directory.csv) file and make a pull request to the upstream project.
+
+If your offer is accepted, and the pull request merged, your repository will be listed among the "approved" repositories and its
+collections will be available to everyone through the _Resource Sharing_ plugin the next time they start QGIS and the _Resource Sharing_ plugin.

docs/authoring/repository-example.md

@@ -0,0 +1,8 @@
+# Gallery of examples
+
+Below is a list of repositories that you can have a look at when you want to create a repository:
+
+- [QGIS Official Repository](https://github.com/qgis/QGIS-Resources)
+- [Richard Duivenvoorde Repository](https://github.com/rduivenvoorde/qgis-styles)
+- [Remote ZIP Test Repository](https://github.com/akbargumbira/zip_data_example) (**_QGIS 2_**)
+- [Akbar's Test Repository](https://github.com/akbargumbira/qgis_resources_data) (**_QGIS 2_**)

docs/authoring/repository-structure.md

@@ -0,0 +1,76 @@
+# Repository structure
+
+In order for the plugin to be able to read the repository correctly, the repository must have a specific structure.
+
+Generally the structure looks like this:
+
+    Repository root
+    ├── README (encouraged)
+    ├── metadata.ini (required)
+    └── collections
+        ├── [Collection1 register id] (the id string used in "collections" in metadata.ini)
+        │   ├── checklists (optional, containing checklist definition JSON files)
+        │   ├── expressions (optional, containing JSON files with QGIS Expressions)
+        │   ├── image (optional, containing all kinds of image files)
+        │   ├── models (optional, containing Processing models)
+        │   ├── preview (encouraged, containing previews for the collection, referenced in metadata.ini)
+        │   ├── processing (optional, containing Python Processing scripts)
+        │   ├── rscripts (optional, containing R scripts)
+        │   ├── style (optional, containing QML files - QGIS Layer style)
+        │   ├── svg (optional, containing SVG files)
+        │   ├── symbol (optional, containing symbol definition XML files)
+        │   └── license file (encouraged)
+        │
+        ├── [Collection2 register id] (the id string used in "collections" in metadata.ini)
+        │   ├── checklists (optional, containing checklist definition JSON files)
+        │   ├── expressions (optional, containing JSON files with QGIS Expressions)
+        │   ├── image (optional, containing all kinds of image files)
+        │   ├── models (optional, containing Processing models)
+        │   ├── preview (encouraged, containing previews for the collection, referenced in metadata.ini)
+        │   ├── processing (optional, containing Python Processing scripts)
+        │   ├── rscripts (optional, containing R scripts)
+        │   ├── style (optional, containing QML files - QGIS Layer style)
+        │   ├── svg (optional, containing SVG files)
+        │   ├── symbol (optional, containing symbol definition XML files)
+        │   └── license file (encouraged)
+        │
+        ├── ...
+        ├── ...
+        │
+        └── [CollectionN register id] (the id string used in "collections" in metadata.ini)
+            ├── checklists (optional, containing checklist definition JSON files)
+            ├── expressions (optional, containing JSON files with QGIS Expressions)
+            ├── image (optional, containing all kinds of image files)
+            ├── models (optional, containing Processing models)
+            ├── processing (optional, containing Python Processing scripts)
+            ├── rscripts (optional, containing R scripts)
+            ├── style (optional, containing QML files - QGIS Layer style)
+            ├── svg (optional, containing SVG files)
+            ├── symbol (optional, containing symbol definition XML files)
+            └── license file (encouraged)
+
+If the _QGIS Resource Sharing plugin_ shall be able to make the
+resources available to QGIS users in a convenient way, you have
+to place them where the plugin expects to find them:
+
+- Layer style (QML) files belong in the **_style_** directory.
+- Processing models belong in the **_models_** directory.
+- Processing (Python) scripts belong in the **_processing_**
+  directory.
+- R script (for use with the Processing R plugin) belong in in the
+  **_rscripts_** directory.
+
+- Symbol XML files belong in the **_symbol_** directory.
+  Symbol images are expected to be in the **_image_** directory and
+  symbol SVGs are expected to be in the **_svg_** directory.
+
+- SVGs belong in the **_svg_** directory.
+
+- Images belong in the **_image_** directory.
+
+- Expression JSON files belong in the **_expressions_** directory.
+
+- Data QA Workbench checklist JSON files belong in the
+  **_checklists_** directory.
+
+Check the [QGIS Resources Repository](https://github.com/QGIS/QGIS-Resources) and [this test repository](https://github.com/QGIS-Contribution/QGIS_Test-Resources) for GitHub repository examples.