Documentation structure (#2)

* Add .github folder

* Added docs

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/clean.sh

@@ -0,0 +1,5 @@
+#! /usr/bin/env bash
+
+rm -rf .venv
+rm -rf site
+rm -rf __pycache__

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,96 @@
+site_name: Project Name
+site_description: "Project technical and user documentation."
+site_author: "Kartoza"
+docs_dir: ./src
+site_dir: ./site
+repo_name: "Project Name"
+repo_url: "https://github.com/kartoza/<project name>"
+edit_uri: "https://github.com/kartoza/<project name>/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:material.extensions.emoji.to_svg
+                  emoji_index: !!python/name:material.extensions.emoji.twemoji  
+
+# Navigation
+nav:
+        - Home:
+                  - Home: index.md
+                  - Code of Conduct: about/code-of-conduct.md
+                  - License: about/license.md
+                  - Running Instances: about/running-instances.md
+        - User:
+                  - user/index.md
+                  - Quickstart: user/quickstart/index.md
+                  - Guide:
+                          - user/guide/index.md
+                  - Manual :
+                          - user/manual/index.md
+        - Administrators:
+                - administrator/index.md
+                - Guide:
+                        - administrator/guide/index.md
+                - Manual:
+                        - administrator/manual/index.md
+        - Developers:
+                - developer/index.md
+                - Guide:
+                        - developer/guide/index.md
+                        - Architecture: developer/guide/architecture.md
+                        - Prerequisites: developer/guide/prerequisites.md
+                        - Cloning: developer/guide/cloning.md
+                        - IDE Setup: developer/guide/ide-setup.md
+                        - Configuration: developer/guide/configuration.md
+                        - Building: developer/guide/building.md
+                        - Design: developer/guide/design.md
+                        - Road Map: developer/guide/roadmap.md
+                        - Workflows: developer/guide/workflows.md
+                        # Pages to render but exclude from navigation
+                        - "": developer/guide/templates/pull-request-template.md 
+                        - "": developer/guide/templates/commit-message-convention.md
+                - Manual: developer/manual/index.md
+                - Documentation Writing:
+                        - developer/documentation/index.md
+                        - Simple Workflow: developer/documentation/easy-workflow.md
+                        - Advanced Workflow: developer/documentation/overview.md
+                        - Context Help: developer/documentation/context-help.md
+                - API:
+                        - developer/api/index.md
+                        - Reference: developer/api/manual/index.md
+                        - Guide: developer/api/guide/index.md
+                - License: about/license.md
+        - DevOps:
+                  - devops/index.md
+                  - Guide: devops/guide/index.md
+                  - Manual: devops/manual/index.md
+        - About:
+                  - About: about/index.md
+                  - License: about/license.md
+                  - Contributing: about/contributing.md
+                  - Disclaimer: about/disclaimer.md
+

docs/mkdocs-html.yml

@@ -0,0 +1,120 @@
+
+# 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 # This causes the nav menu to auto expand
+    - 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: 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
+
+# Needed for the hooks below to work
+plugins:
+  - search
+  - mkdocs-video
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [../django_project]
+          import:
+            - https://docs.python.org/3/objects.inv
+            - https://mkdocstrings.github.io/autorefs/objects.inv
+          options:
+            # Lots of other nice options can be found at  
+            # https://mkdocstrings.github.io/python/usage/
+            docstring_style: sphinx
+            heading_level: 2
+            show_bases: true
+            show_signature: true
+            separate_signature: true
+            show_signature_annotations: true
+            show_source: true
+            show_root_heading: true
+            show_root_full_path: true
+            show_root_members_full_path: true
+            merge_init_into_class: true
+            docstring_options:
+              ignore_init_summary: false
+
+  - redirects:
+      redirect_maps:
+        #see https://github.com/mkdocs/mkdocs-redirects/tree/master#using
+        #'old.md': 'new.md'
+        #'old/file.md': 'new/file.md'
+        #'some_file.md': 'http://external.url.com/foobar'
+  - enumerate-headings:
+      toc_depth: 3
+      strict: true
+      increment_across_pages: true
+      include:
+        - "*"
+      exclude:
+        - index.md
+        - user/index.md
+        - administrator/index.md
+        - developer/index.md
+        - developer/manual/*.md
+        - devops/index.md
+      restart_increment_after:
+        - second_section.md
+
+# Hook to add a uuid to every anchor
+# see also hook.py and https://github.com/squidfunk/mkdocs-material/discussions/3758#discussioncomment-4397373
+# Note that although the above link implies you can use UUIDs, you have to use numeric IDS not UUIDS
+hooks:
+  - ./uuid_redirects_hook.py
+  - ./python_manual_hook.py

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/[PROJECT_NAME]Documentation.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: Title for PDF
+      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