Resolve merge conflicts

docs/src/development/documentation/index.md

@@ -1 +1,9 @@
 # Project Documentation
+
+The subdirectories within this folder contain the generic boiler plate files required for project documentation.
+
+Copy the template files and rename them as needed (e.g. `mkdocs-base-template.yml` would be copied and become `mkdocs-base.yml`).
+
+The `repo-template` folder represents the start of a blank repository.
+
+Edit the `nav` section of the `mkdocs-base-template.yml` to have the correct relevant pathways.

docs/src/development/documentation/repo-template/docs-template/build-docs-html-template.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/src/development/documentation/repo-template/docs-template/build-docs-pdf-template.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/src/development/documentation/repo-template/docs-template/create-mkdocs-html-config-template.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/src/development/documentation/repo-template/docs-template/create-mkdocs-pdf-config-template.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/src/development/documentation/repo-template/docs-template/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/src/development/documentation/repo-template/docs-template/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/src/development/documentation/repo-template/docs-template/mkdocs-base-template.yml

@@ -0,0 +1,57 @@
+site_name: Kartoza Handbook
+site_description: "Kartoza staff handbook and technical documentation."
+site_author: "Kartoza"
+docs_dir: ./src
+site_dir: ./site
+repo_name: "Kartoza Handbook"
+repo_url: "https://github.com/kartoza/TheKartozaHandbook"
+edit_uri: "https://github.com/kartoza/TheKartozaHandbook/blob/main/docs/"
+copyright: Kartoza and Contributors
+
+markdown_extensions:
+        - pymdownx.highlight:
+                  anchor_linenums: true
+        - pymdownx.inlinehilite
+        #- mdx_truly_sane_lists
+        - toc:
+                  permalink: true
+                  slugify: !!python/name:pymdownx.slugs.uslugify
+        - 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
+        - User:
+                  - Quickstart: user/quickstart.md
+                  - User Guide: user/user-guide.md
+                  - User Reference Manual: user/user-reference-manual.md
+                  - API: user/api.md
+        - Admin:
+                  - Admin Reference Manual: admin/admin-reference-manual.md
+        - Developer:
+                  - Tutorial: developer/tutorial.md
+                  - Architecture: developer/architecture.md
+                  - Workflows: developer/workflows.md
+                  - Documentation: developer/docs.md
+                  - Developer Reference Manual: developer/dev-ref-manual.md
+                  - Design: developer/design.md
+        - DevOps:
+                  - DevOps: devops/index.md
+        - About:
+                  - Index: about/index.md

docs/src/development/documentation/repo-template/docs-template/mkdocs-html-template.yml

@@ -0,0 +1,66 @@
+
+# Configuration
+theme:
+  name: material
+  language: en
+  direction: ltr
+  include_search_page: false
+  search_index_only: true
+  features:
+    - content.code.annotate
+    - content.tabs.link
+    - header.autohide
+    - navigation.expand
+    - navigation.indexes
+    - navigation.instant
+    - navigation.sections
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.top
+    - navigation.tracking
+    - search.highlight
+    - search.share
+    - search.suggest
+    - toc.follow
+  palette:
+    - scheme: default
+      primary: blue
+      accent: grey
+      toggle:
+        icon: material/brightness-4
+        name: Switch to dark mode
+    - scheme: slate
+      primary: blue
+      accent: grey
+      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:
+  - css/print.css
+
+extra_javascript:
+  - https://unpkg.com/[email protected]/dist/tablesort.min.js
+  - js/tablesort.js
+
+plugins:
+  - search

docs/src/development/documentation/repo-template/docs-template/mkdocs-pdf-template.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/TheKartozaHandbook.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: The Kartoza Handbook
+      cover_subtitle: Mappiness is Happiness
+      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

docs/src/development/documentation/repo-template/docs-template/src/about/img/naming_convention.md

@@ -0,0 +1,7 @@
+# Image naming convention
+
+Images should be named according to reference doc, sub-section and order in document.
+e.g.
+
+- The 1st image in instructions regarding zooming will be something like instr_zooming__1, the 2nd image will be instr_zooming__2, etc.
+- The 1st image in quickstart regarding logging in will be qs_login_1, etc

docs/src/development/documentation/repo-template/docs-template/src/about/index.md

@@ -0,0 +1,21 @@
+# About
+<!-- Replace all of the titles with relevant titles -->
+
+## License
+<!-- Link to License or actual License -->
+<!-- Either standard Kartoza License or CLient Provided License -->
+
+## Contributors
+
+| Contributor | GitHub Handle |
+| ----------- | ------------- |
+| Example Person | [example GitHub tag]() |
+
+## Project Funders/Backers
+<!-- Images and links to backers/funders -->
+
+## Logos
+
+![Kartoza Logo]()
+
+![Project Partner Logo]()

docs/src/development/documentation/repo-template/docs-template/src/admin/admin-reference-manual.md

@@ -0,0 +1,11 @@
+# Admin Reference Manual
+<!-- Replace all of the titles with relevant titles -->
+
+## Opening Tickets
+<!-- Explanation on how to open Github issues on Project board -->
+
+## Staging version of Product
+<!-- Instructions on how to get staging version of product -->
+
+## Permissions
+<!-- Admin Permissions Framework for product -->

docs/src/development/documentation/repo-template/docs-template/src/admin/img/naming_convention.md

@@ -0,0 +1,7 @@
+# Image naming convention
+
+Images should be named according to reference doc, sub-section and order in document.
+e.g.
+
+- The 1st image in instructions regarding zooming will be something like instr_zooming__1, the 2nd image will be instr_zooming__2, etc.
+- The 1st image in quickstart regarding logging in will be qs_login_1, etc

docs/src/development/documentation/repo-template/docs-template/src/developer/architecture.md

@@ -0,0 +1,8 @@
+# System Architecture
+<!-- Replace all of the titles with relevant titles -->
+
+## Frameworks Used
+
+## High-level System Architecture
+
+## Data Model

docs/src/development/documentation/repo-template/docs-template/src/developer/design.md

@@ -0,0 +1,7 @@
+# Design
+<!-- Replace all of the titles with relevant titles -->
+
+## Design Sheet
+
+## Wire-frame Model
+<!-- Link to wire-frame or screenshots of wire-frame -->

docs/src/development/documentation/repo-template/docs-template/src/developer/dev-ref-manual.md

@@ -0,0 +1,19 @@
+# Developer Reference Manual
+<!-- Replace all of the titles with relevant titles -->
+<!-- Should be mkdocs generated content -->
+
+## Setting up the Development Environment
+
+## Coding Conventions
+
+## Contributor/COntribution Guidelines
+
+## Project SCRUM
+<!-- Info on how work gets organised -->
+
+## How to Test Local Instance
+
+### Adapting tests for later down pipeline
+
+## License
+<!-- Link to Project License -->

docs/src/development/documentation/repo-template/docs-template/src/developer/docs.md

@@ -0,0 +1,14 @@
+# Documentation
+<!-- Replace all of the titles with relevant titles -->
+
+
+## Code Auto Documentation
+<!-- mkdocstrings related -->
+
+## How to Make Documentation
+
+### Adding to Documentation
+
+### Generating PDFS
+
+### Generating Static Site