Updating base template (#12)

* Updating mkdocs-base files to match new standard * updating requirements file * adding python files for mkdocs hooks * updating docs to match updated structure * adding compartmentalised img folders * docs: update plugins to make nicer structure * docs: spelling fix * Docs: DevOps update * Docs: update templates * update requirements.txt * fixing build issues * fix build issues * build fixes * Docs: fix dummy link * Docs: update documentation tutorials * Docs: Updating standard files * Docs: updating content
kartoza · Dec 15, 2023 · ff8f021 · ff8f021
1 parent b292f9e
commit ff8f021
Show file tree

Hide file tree

Showing 165 changed files with 2,761 additions and 315 deletions.
diff --git a/.github/workflows/BuildMKDocsAndPublishToGithubPages.yml b/.github/workflows/BuildMKDocsAndPublishToGithubPages.yml
@@ -3,6 +3,12 @@ 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/BuildMKDocsAndPublishToGithubPages.yml"
+      - "**.md"
+      - "**.py"
+      - "assets/**"
   # Allow manually running in the actions tab
   workflow_dispatch:
 
@@ -25,7 +31,7 @@ jobs:
         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
+        uses: timlinux/mkdocs-deploy-gh-pages@master
         # Wrong
         #uses: timlinux/QGISAnimationWorkbench@main
         env:
@@ -34,3 +40,4 @@ jobs:
           # The token is automatically generated by the GH Action
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           CONFIG_FILE: docs/mkdocs.yml
+          REQUIREMENTS: requirements.txt
diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml
@@ -17,7 +17,7 @@ jobs:
         run: ./create-mkdocs-html-config.sh        
 
       - name: Deploy docs
-        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        uses: timlinux/mkdocs-deploy-gh-pages@master
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           CONFIG_FILE: /docs/mkdocs.yml

diff --git a/default.nix b/default.nix
@@ -1,7 +1,10 @@
 with import <nixpkgs> { };
 
 let
-  pythonPackages = python3Packages;
+  # For packages pinned to a specific version
+  pinnedHash = "933d7dc155096e7575d207be6fb7792bc9f34f6d"; 
+  pinnedPkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/${pinnedHash}.tar.gz") { };
+  pythonPackages = pinnedPkgs.python3Packages;
 in pkgs.mkShell rec {
   name = "impurePythonEnv";
   venvDir = "./.venv";
@@ -12,31 +15,42 @@ in pkgs.mkShell rec {
 
     # This executes some shell code to initialize a venv in $venvDir before
     # dropping into the shell
-    pythonPackages.venvShellHook
 
+    # For PDF production  in mkdocs
+    pythonPackages.venvShellHook
+    python311Packages.weasyprint
+    pinnedPkgs.cairo
+    pinnedPkgs.pango
+    pinnedPkgs.gdk-pixbuf
+    pinnedPkgs.glib
+    pinnedPkgs.gtk2
     # Those are dependencies that we would like to use from nixpkgs, which will
     # add them to PYTHONPATH and thus make them accessible from within the venv.
-    pythonPackages.numpy
     pythonPackages.requests
-
-    # In this particular example, in order to compile any binary extensions they may
-    # require, the Python modules listed in the hypothetical requirements.txt need
-    # the following packages to be installed locally:
-    taglib
-    openssl
-    git
-    libxml2
-    libxslt
-    libzip
-    zlib
+    pythonPackages.pygobject3
+    # Doesnt work properly
+    #python311Packages.cffi
+    pinnedPkgs.gobject-introspection 
+    pinnedPkgs.gtk3
+    pinnedPkgs.taglib
+    pinnedPkgs.openssl
+    pinnedPkgs.git
+    pinnedPkgs.libxml2
+    pinnedPkgs.libxslt
+    pinnedPkgs.libzip
+    pinnedPkgs.zlib
+    pinnedPkgs.gnused
+    pinnedPkgs.rpl
   ];
 
   # Run this command, only after creating the virtual environment
   postVenvCreation = ''
     unset SOURCE_DATE_EPOCH
-    pip install -r requirements.txt
+    pip install -r requirements.txt 
   '';
 
+  shellHook = ''
+  '';
   # Now we can execute any commands within the virtual environment.
   # This is optional and can be left out to run pip manually.
   postShellHook = ''

diff --git a/docs/clean.sh b/docs/clean.sh
@@ -0,0 +1,5 @@
+#! /usr/bin/env bash
+
+rm -rf .venv
+rm -rf site
+rm -rf __pycache__
diff --git a/docs/create-uuid.py b/docs/create-uuid.py
@@ -0,0 +1,5 @@
+#! /usr/bin/env python
+
+import shortuuid
+uuid = shortuuid.uuid()
+print (uuid)
diff --git a/docs/mkdocs-base.yml b/docs/mkdocs-base.yml
@@ -10,6 +10,8 @@ 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
@@ -35,26 +37,60 @@ markdown_extensions:
                   emoji_generator: !!python/name:materialx.emoji.to_svg
                   emoji_index: !!python/name:materialx.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 Documentation: user/quickstart/index.md
-                  - User Guide: user/user-guide/index.md
-                  - User Reference Manual: user/user-reference-manual/index.md
-                  - API: user/api/index.md
-        - Admin:
-                  - Admin Guide: admin/admin-guide/index.md
-                  - Admin Reference Manual: admin/admin-reference-manual/index.md
-        - Developer:
-                  - Tutorial: developer/tutorial/index.md
-                  - Architecture: developer/architecture/index.md
-                  - Documentation: developer/docs/index.md
-                  - Developer Reference Manual: developer/dev-ref-manual/index.md
-                  - Design: developer/design/index.md
+                  - 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 Tutorial: devops/tutorial/index.md
-                  - DevOps Reference Manual: devops/devops-ref-manual/index.md
+                  - devops/index.md
+                  - Guide: devops/guide/index.md
+                  - Manual: devops/manual/index.md
         - About:
-                  - Index: about/index.md
+                  - About: about/index.md
                   - License: about/license.md
+                  - Contributing: about/contributing.md
+                  - Disclaimer: about/disclaimer.md
+
diff --git a/docs/mkdocs-html.yml b/docs/mkdocs-html.yml
@@ -10,10 +10,10 @@ theme:
     - content.code.annotate
     - content.tabs.link
     - header.autohide
-    - navigation.expand
+#    - navigation.expand # This causes the nav menu to auto expand
     - navigation.indexes
     - navigation.instant
-    - navigation.sections
+#    - 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
@@ -62,5 +62,59 @@ 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
diff --git a/docs/mkdocs-pdf.yml b/docs/mkdocs-pdf.yml
@@ -8,7 +8,7 @@ plugins:
       # 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
+      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

diff --git a/docs/python_manual_hook.py b/docs/python_manual_hook.py
@@ -0,0 +1,45 @@
+import logging
+import mkdocs.plugins
+import os
+log = logging.getLogger('mkdocs')
+
+@mkdocs.plugins.event_priority(-50)
+
+
+def on_startup(command, dirty):
+
+    template = """
+---
+title: Automatically Generated Python Documentation
+summary: DO NOT EDIT THIS FILE MANUALLY : It is created during the mkdocs build process
+date: 2023-08-03
+---
+
+# Python Reference Manual
+"""
+    ignore_list = [ 
+    	"__init__",
+    	"migrations",
+        "tests"]
+    for root, dirs, files in os.walk("../django_project"):
+        for file in files:
+             file = os.path.join(root, file)
+             ignored = False;
+             if file.endswith(".py"):
+                 for item in ignore_list:
+                     if item in file:
+                         ignored = True;
+                     #print (item, file, ignored)
+                 if not ignored:
+                     file = file.replace("../django_project/", "::: ")
+                     file = file.replace("/", ".")
+                     file = file.replace(".py", "")
+                     template = template + file + "\n"
+    output_path = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)),
+        "src/developer/manual/index.md") 
+    log.info("Manual will be written to: " + output_path) 
+    file = open(output_path,"wt+")
+    file.write(template)
+    file.close()
+    log.info("Manual written to:         " + os.path.realpath(file.name)) 
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,14 @@
+
+mkdocs-with-pdf
+mkdocs-material
+mdx_gh_links
+mkdocs-pdf-export-plugin
+mkdocstrings-python
+mkdocs-video
+mkdocs-redirects
+mkdocs-enumerate-headings-plugin
+mkdocs-git-revision-date-localized-plugin
+# needed for the create-uuid.py helper script
+shortuuid
+# Needed for mkdocstrings python documentation generator
+black