Create GitHub Pages site with Jekyll

.github/workflows/pages.yml

@@ -0,0 +1,71 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Deploy Jekyll site to Pages
+
+on:
+  push:
+    branches:
+      - "main"
+    paths:
+      - "docs/**"
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3' # Not needed with a .ruby-version file
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          cache-version: 0 # Increment this number if you need to re-download cached gems
+          working-directory: '${{ github.workspace }}/docs'
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Build with Jekyll
+        # Outputs to the './_site' directory by default
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+      - name: Upload artifact
+        # Automatically uploads an artifact from the './_site' directory by default
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site/
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/.gitignore

@@ -0,0 +1,6 @@
+_site
+.sass-cache
+.jekyll-cache
+.jekyll-metadata
+vendor
+Gemfile.lock

docs/404.html

@@ -0,0 +1,25 @@
+---
+permalink: /404.html
+layout: default
+---
+
+<style type="text/css" media="screen">
+  .container {
+    margin: 10px auto;
+    max-width: 600px;
+    text-align: center;
+  }
+  h1 {
+    margin: 30px 0;
+    font-size: 4em;
+    line-height: 1;
+    letter-spacing: -1px;
+  }
+</style>
+
+<div class="container">
+  <h1>404</h1>
+
+  <p><strong>Page not found :(</strong></p>
+  <p>The requested page could not be found.</p>
+</div>

docs/Gemfile

@@ -0,0 +1,34 @@
+source "https://rubygems.org"
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+# gem "jekyll", "~> 4.3.4"
+# This is the default theme for new Jekyll sites. You may change this to anything you like.
+# gem "minima", "~> 2.5"
+gem "just-the-docs"
+# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
+# uncomment the line below. To upgrade, run `bundle update github-pages`.
+gem "github-pages", "~> 232", group: :jekyll_plugins
+# If you have any plugins, put them here!
+# group :jekyll_plugins do
+#   gem "jekyll-feed", "~> 0.12"
+# end
+
+# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
+# and associated library.
+platforms :mingw, :x64_mingw, :mswin, :jruby do
+  gem "tzinfo", ">= 1", "< 3"
+  gem "tzinfo-data"
+end
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1", :platforms => [:mingw, :x64_mingw, :mswin]
+
+# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
+# do not have a Java counterpart.
+gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]

docs/_config.yml

@@ -0,0 +1,59 @@
+# Welcome to Jekyll!
+#
+# This config file is meant for settings that affect your whole blog, values
+# which you are expected to set up once and rarely edit after that. If you find
+# yourself editing this file very often, consider using Jekyll's data files
+# feature for the data you need to update frequently.
+#
+# For technical reasons, this file is *NOT* reloaded automatically when you use
+# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
+#
+# If you need help with YAML syntax, here are some quick references for you:
+# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml
+# https://learnxinyminutes.com/docs/yaml/
+#
+# Site settings
+# These are used to personalize your new site. If you look in the HTML files,
+# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
+# You can create any custom variable you would like, and they will be accessible
+# in the templates via {{ site.myvariable }}.
+
+title: AusMap User Manual
+#email: [email protected]
+description: >- # this means to ignore newlines until "baseurl:"
+  User manual for the AusMap QGIS plugin.
+#baseurl: "" # the subpath of your site, e.g. /blog
+url: https://wms-engineering.github.io/AusMap/ # the base hostname & protocol for your site, e.g. http://example.com
+# twitter_username: jekyllrb
+# github_username:  jekyll
+
+# Build settings
+theme: just-the-docs
+# plugins:
+#   - jekyll-feed
+
+
+logo: "/assets/images/icon.png"
+favicon_ico: "/assets/images/icon.ico"
+
+# Exclude from processing.
+# The following items will not be processed, by default.
+# Any item listed under the `exclude:` key here will be automatically added to
+# the internal "default list".
+#
+# Excluded items can be processed by explicitly listing the directories or
+# their entries' file path in the `include:` list.
+#
+exclude:
+  - .sass-cache/
+  - .jekyll-cache/
+  - gemfiles/
+  - Gemfile
+  - Gemfile.lock
+  - node_modules/
+  - vendor/bundle/
+  - vendor/cache/
+  - vendor/gems/
+  - vendor/ruby/
+
+nav_enabled: true

docs/bug-reports.md

@@ -0,0 +1,10 @@
+---
+title: Bug Reports and Feature Requests
+layout: page
+nav_order: 5
+permalink: /issues/
+---
+
+# Bug Reports and Feature Requests
+
+If you encounter any bugs or have feature requests, please feel free to create an issue in our GitHub repository. We appreciate your feedback!

docs/getting-started.md

@@ -0,0 +1,24 @@
+---
+title: Getting Started
+layout: page
+nav_order: 3
+permalink: /getting-started/
+---
+
+# Getting Started
+
+## Adding Map Layers
+
+Once installed, the AusMap plugin appears in the menu bar.
+
+![QGIS menu bar](/assets/images/menu-bar.png)
+
+The available map layers are arranged in alphabetically ordered categories.
+
+![Ausmap menu](/assets/images/ausmap-menu.png)
+
+## Search Functionality
+
+You can search for the layer names provided by the AusMap plugin by using the locator bar in the bottom left corner of the QGIS interface. Clicking on a layer in the search results will add it to the map canvas.
+
+![Locator bar](/assets/images/search.png)

docs/index.md

@@ -0,0 +1,12 @@
+---
+title: Introduction
+layout: home
+nav_order: 1
+permalink: /
+---
+
+# Introduction
+
+AusMap is a QGIS plugin for visualising publicly available Australian geographic data. It gives quick access to a variety of feature sets and map layers provided by Geoscience Australia, the Google Maps Platform and OpenStreetMap. Selecting a desired layer from the AusMap menu will add it to the map canvas with styling and labelling applied. The layers are provided via WMS, WFS, WMTS and XYZ services, which all require an active internet connection.  
+
+This manual will guide you through the installation, configuration and use of the plugin.

docs/installation.md

@@ -0,0 +1,26 @@
+---
+title: Installation
+layout: page
+nav_order: 2
+permalink: /installation/
+---
+
+# Installation
+
+## Requirements
+
+- QGIS version 3.18 or higher
+- Internet access for fetching online map layer web services
+
+## Installation through QGIS
+
+1. Open QGIS.
+2. Navigate to **Plugins** > **Manage and Install Plugins**.
+3. Search for *AusMap*.
+4. Click the **Install** button.
+
+## Manual Installation through GitHub
+
+1. Download the ZIP file from the GitHub repository.
+2. In QGIS, navigate to **Plugins** > **Manage and Install Plugins**.
+3. Click **Install from ZIP** and select the downloaded plugin file.

docs/license.md

@@ -0,0 +1,12 @@
+---
+title: Credits and License
+layout: page
+nav_order: 6
+permalink: /license/
+---
+
+# Credits and License
+
+AusMap is developed and maintained by WMS Engineering and is licensed under the GNU General Public License (GPL) v3.0 or later. You are free to use, modify, and distribute this plugin under the terms of the [GNU GPL](https://www.gnu.org/licenses/) as published by the Free Software Foundation. This plugin is distributed in the hope that it will be useful, but without any warranty. See the GNU GPL for more details.  
+
+The design and functionality of AusMap draw inspiration from the [Dataforsyningen QGIS plugin](https://github.com/SDFIdk/Qgis-dataforsyningen). The map layers are provided by [Geoscience Australia](https://services.ga.gov.au/), the Google Maps Platform, and OpenStreetMap.

docs/settings.md

@@ -0,0 +1,35 @@
+---
+title: Settings
+layout: page
+nav_order: 4
+permalink: /settings/
+---
+
+# Settings
+
+The AusMap plugin can be extended with additional map layers saved in a Layer Definition File (QLR). The map layers in this file will be added to the AusMap menu and therefore easily accessible.  
+
+The QLR file must match the AusMap menu layout, meaning that the map layers must be grouped into one or more categories.  
+
+See the example below.
+
+## Example
+
+The additional layers 1, 2 and 3 are grouped into two categories.
+
+![Grouped map layers](/assets/images/grouped-layers.png)
+
+Save the layers in a QLR file by selecting the groups, right-clicking, and choosing **Export** > **Save as Layer Definition File**.
+
+![Save QLR](/assets/images/save-qlr.png)
+
+Navigate to the AusMap page in the options dialog (**Settings** > **Options** > **AusMap**), select the QLR file from your local machine and click **OK**.  
+
+![AusMap options dialog](/assets/images/options-dialog.png)
+
+The additional map layers will now appear in their respective groups inside the AusMap menu.  
+
+![Custom layers in menu](/assets/images/new_layers_in_menu.png)
+
+To remove the layers from the menu, go back to the options dialog, delete the file path and save.
+