Merge pull request #285 from Jeremy-Prior/main

Documentation: Setting up mkdocs for documetation site

.github/workflows/BuildMKDocsAndPublishToGithubPages.yml

@@ -0,0 +1,35 @@
+name: 📖 Build MKDocs And Publish To Github Pages.yml
+on:
+  push:
+    branches:
+      - main
+  # Allow manually running in the actions tab
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install dependencies
+        uses: BSFishy/pip-action@v1
+        with:
+          packages: |
+            mkdocs-material 
+            qrcode
+      - name: Checkout main from github
+        uses: actions/checkout@v1
+      - name: Create Mkdocs Config 🚀
+        working-directory: ./docs
+        run: ./create-mkdocs-html-config.sh
+      - name: Deploy docs to github pages
+        # This is where we get the material theme from
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        # Wrong
+        #uses: timlinux/QGISAnimationWorkbench@main
+        env:
+          # Read this carefully:
+          # https://github.com/marketplace/actions/deploy-mkdocs#building-with-github_token
+          # The token is automatically generated by the GH Action
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: docs/mkdocs.yml

.github/workflows/CompileMKDocsToPDF.yml

@@ -0,0 +1,37 @@
+name: 📔 Compile MKDocs to PDF
+# This workflow is triggered on pushes to the repository.
+on:
+  push:
+    branches:
+      - main
+    # Paths can be used to only trigger actions when you have edited certain files, such as a file within the /docs directory
+    paths:
+      - ".github/workflows/CompileMKDocsToPDF.yml"
+      - "docs/**.md"
+      - "docs/assets/**"
+  # Allow manually running in the actions tab
+  workflow_dispatch:
+
+jobs:
+  generatepdf:
+    name: Build PDF
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛒
+        uses: actions/checkout@v2
+      - name: Create Mkdocs Config 🚀
+        working-directory: ./docs
+        run: ./create-mkdocs-pdf-config.sh
+      - name: Build PDF 📃
+        uses: kartoza/mkdocs-deploy-build-pdf@master
+        # Uses orzih's mkdocs PDF builder
+        # https://github.com/orzih/mkdocs-with-pdf
+        env:
+          CONFIG_FILE: mkdocs.yml
+          EXTRA_PACKAGES: build-base
+          #REQUIREMENTS: folder/requirements.txt
+      - name: Upload PDF Artifact ⚡
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: docs/pdfs

.github/workflows/mkdocs.yml

@@ -0,0 +1,24 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v2
+
+      - name: Create Mkdocs Config 🚀
+        working-directory: ./docs
+        run: ./create-mkdocs-html-config.sh        
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: /docs/mkdocs.yml
+          EXTRA_PACKAGES: build-base

.gitignore

@@ -40,3 +40,4 @@ tags
 data
 
 .env
+docs/mkdocs.yml

docs/build-docs-html.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+# This is only intended for local
+# testing. See github workflows for 
+# how this build is automated.
+
+# this will create mkdocs.yml
+./create-mkdocs-html-config.sh
+# and this will build the html site
+mkdocs build

docs/build-docs-pdf.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+# This is only intended for local
+# testing. See github workflows for 
+# how this build is automated.
+
+# this will create mkdocs.yml
+./create-mkdocs-pdf-config.sh
+# and this will build the PDF document
+mkdocs build > /tmp/document.html

docs/create-mkdocs-html-config.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+# This script will assemble a mkdocs.yml
+# file with plugins section suitable for 
+# html site generation.
+
+# This script is used both in manual
+# site compilation (via build-docs-html.sh)
+# and via the github workflow for 
+# publishing the site to github pages
+# .github/workflows/BuildMKDocsAndPublishToGithubPages.yml
+
+cat mkdocs-base.yml > mkdocs.yml
+cat mkdocs-html.yml >> mkdocs.yml

docs/create-mkdocs-pdf-config.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+# This script will assemble a mkdocs.yml
+# file with plugins section suitable for 
+# PDF site generation.
+
+# This script is used both in manual
+# site compilation (via build-docs-html.sh)
+# and via the github workflow for 
+# publishing the site to github pages
+# .github/workflows/CompileMKDocsToPDF.yml
+
+cat mkdocs-base.yml > mkdocs.yml
+cat mkdocs-pdf.yml >> mkdocs.yml
+# This is a kludge: I could not figure out 
+# how to reference image resources using a relative path in the scss...
+cat templates/graphics.scss.templ | sed "s?\[BASE_FOLDER\]?$PWD?g" > templates/graphics.scss

docs/create-uuid.py

@@ -0,0 +1,5 @@
+#! /usr/bin/env python
+
+import shortuuid
+uuid = shortuuid.uuid()
+print (uuid)

docs/css/extra.css

@@ -0,0 +1,32 @@
+@font-face {
+    src: url(../assets/AvenirLTStd-Book.otf);
+    font-family: avenir;
+}
+@page {
+    size: a4 portrait;
+    margin: 0mm;
+    padding: 25mm 10mm 25mm 10mm;
+    counter-increment: page;
+    font-family: avenir;
+    font-size: 8pt;
+    white-space: normal;
+    color: grey;
+    @bottom-right {
+        content: 'Copyright © Kartoza';
+    	  margin-top: -25mm;
+    	  margin-right: 10mm;
+    }
+    @bottom-center{
+        content: 'Page ' counter(page);
+    	margin-top: -25mm;
+    }
+
+}
+
+body{
+  background-image: url('../img/kartozaBackgroundBorder.png');
+  background-repeat: no-repeat;
+  background-size: cover;
+  font-family: avenir;
+  height: 100vh;
+}

docs/js/tablesort.js

@@ -0,0 +1,6 @@
+document$.subscribe(function() {
+    var tables = document.querySelectorAll("article table:not([class])")
+    tables.forEach(function(table) {
+      new Tablesort(table)
+    })
+  })

docs/mkdocs-base.yml

@@ -0,0 +1,51 @@
+site_name: MiniSASS
+site_description: "MiniSASS documentation."
+site_author: "Kartoza"
+docs_dir: ./src
+site_dir: ./site
+repo_name: "miniSASS"
+repo_url: "https://github.com/kartoza/minisass"
+edit_uri: "https://github.com/kartoza/minisass/blob/main/docs/"
+
+copyright: Kartoza and Contributors
+
+markdown_extensions:
+        - attr_list # lets us resize images see https://github.com/mkdocs/mkdocs/issues/1678#issuecomment-455500757
+        - sane_lists # needed to keep numbers in ordered lists correct
+        - pymdownx.highlight:
+                  anchor_linenums: true
+        - pymdownx.inlinehilite
+        #- mdx_truly_sane_lists
+        - toc:
+                  permalink: true
+                   #slugify: !!python/name:pymdownx.slugs.slugify
+        - pymdownx.snippets:
+                  base_path: .
+        - admonition
+        - tables
+        - pymdownx.details
+        - pymdownx.caret
+        - pymdownx.keys
+        - pymdownx.mark
+        - pymdownx.tilde
+        - pymdownx.superfences:
+                  custom_fences:
+                          - name: mermaid
+                            class: mermaid
+                            format: !!python/name:pymdownx.superfences.fence_code_format
+        - pymdownx.emoji:
+                  emoji_generator: !!python/name:materialx.emoji.to_svg
+                  emoji_index: !!python/name:materialx.emoji.twemoji
+
+nav:
+        - Home:
+                  - Home: index.md
+                  - Developer Documentation: developer/index.md
+                  - About: about/index.md
+        - Developer:
+                  - developer/index.md
+                  - Installation: developer/install.md
+                  - Authentication: developer/authentication.md
+        - About:
+                  - about/index.md
+                  - License: about/license.md

docs/mkdocs-html.yml

@@ -0,0 +1,81 @@
+
+# Configuration
+theme:
+  name: material
+  logo: 
+  language: en
+  direction: ltr
+  include_search_page: false
+  search_index_only: true
+  features:
+    - content.code.annotate
+    - content.tabs.link
+    - header.autohide
+#    - navigation.expand # stop auto-expanding menus
+    - navigation.indexes
+    - navigation.instant
+#    - navigation.sections # This removes the ability to shrink sections on the nav menu but gives the bold headings
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.top
+    - navigation.tracking
+    - search.highlight
+    - search.share
+    - search.suggest
+    - toc.follow
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: teal
+      toggle:
+        icon: material/brightness-4
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: teal
+      toggle:
+        icon: material/brightness-6
+        name: Switch to light mode
+  font:
+    text: Roboto
+    code: Roboto Mono
+  favicon: assets/logo.png
+  icon:
+    logo: material/book
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/kartoza
+    - icon: fontawesome/brands/docker
+      link: https://hub.docker.com/r/kartoza/
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/KartozaGeo
+    - icon: fontawesome/brands/facebook
+      link: https://kartoza.com
+    - icon: fontawesome/solid/earth-africa
+      link: https://kartoza.com
+
+extra_css:
+  - stylesheets/extra.css
+
+extra_javascript:
+  - https://unpkg.com/[email protected]/dist/tablesort.min.js
+  - js/tablesort.js
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [..]
+          import:
+            - https://docs.python.org/3/objects.inv
+            - https://mkdocstrings.github.io/autorefs/objects.inv
+          options:
+            docstring_style: sphinx
+            separate_signature: true
+            merge_init_into_class: true
+            docstring_options:
+              ignore_init_summary: true
+

docs/mkdocs-pdf.yml

@@ -0,0 +1,56 @@
+# See mkdocs base and the create-mkdocs*
+# scripts for how this is used
+
+plugins:
+  - with-pdf:
+      # Generate the whole site as a single PDF
+      # Full details on this plugin here:
+      # https://github.com/orzih/mkdocs-with-pdf
+      # And don't get it confused with https://github.com/zhaoterryy/mkdocs-pdf-export-plugin
+      # which is intended to export a single page at a time
+      output_path: ../pdfs/Documenation.pdf
+      author: Kartoza Pty (Ltd.)
+      # copyright will draw in page.bottom-right
+      # do it manually in templates/styles.scss
+      # for more control
+      # if you comment out here or use an empty string,
+      # the copyright text from mkdocs-base.yml will be
+      # used instead
+      copyright: " "
+      cover: true # see templates/cover.html
+      back_cover: true
+      cover_title: MiniSASS documentation.
+      cover_subtitle: MiniSASS technical and user documentation.
+      cover_logo: ./resources/img/logo/kartoza-logo.svg
+      # Print css is defined in templates/styles.scss
+      #custom_template_path: TEMPLATES PATH
+      #
+      toc_title: Contents
+      #heading_shift: false
+      toc_level: 2
+      # Set to 0 so that it does not generate chapter numbering
+      # we do the numbering in styles.css rather
+      ordered_chapter_level: 0
+      #excludes_children:
+      #    - 'release-notes/:upgrading'
+      #    - 'release-notes/:changelog'
+      #
+      #exclude_pages:
+      #    - 'bugs/'
+      #    - 'appendix/contribute/'
+      #convert_iframe:
+      #    - src: IFRAME SRC
+      #      img: POSTER IMAGE URL
+      #      text: ALTERNATE TEXT
+      #    - src: ...
+      #two_columns_level: 3
+      #
+      #render_js: true
+      #headless_chrome_path: headless-chromium
+      #
+
+      #enabled_if_env: ENABLE_PDF_EXPORT
+      # See notes at the top of templates/styles.scss.templ
+      # for debugging workflow details.
+      debug_html: true
+      #show_anchors: true