Upstream template changes (#353)

nesi · Sep 30, 2024 · 8144ba9 · 8144ba9
1 parent 80b4fb1
commit 8144ba9
Show file tree

Hide file tree

Showing 29 changed files with 581 additions and 239 deletions.
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
@@ -7,6 +7,7 @@ Description of current CI workflow.
 Retrieves dynamically generated content from external sources.
 
 Currently retrieves:
+
 - Software module list from [modules-list](https://github.com/nesi/modules-list).
 - Glossary, spellcheck dictionary and snippets from [nesi-wordlist](https://github.com/nesi/nesi-wordlist)
 

diff --git a/.github/workflows/auto_merge.yml b/.github/workflows/auto_merge.yml
@@ -5,6 +5,8 @@ on:
     - cron: '30 12 * * *' # Should run 30 min after get remote assets.
 env:
   GH_TOKEN: ${{ github.token }}
+  TARGET_REPO: nesi/support-docs
+  LABEL_NAME: auto_merge
 jobs:
   automerge:
     runs-on: ubuntu-latest
@@ -13,8 +15,8 @@ jobs:
       with:
         fetch-depth: 0
     - run: |
-        for branch in $(gh pr list -R nesi/support-docs --label "auto_merge" --json headRefName --jq .[].headRefName);do
-            git checkout $branch
+        for branch in $(gh pr list -R ${TARGET_REPO} --label "${LABEL_NAME}" --json headRefName --jq .[].headRefName);do
+            git checkout ${branch}
             gh pr merge --squash --auto --delete-branch
         done
 
diff --git a/.github/workflows/demo_deploy.yml b/.github/workflows/demo_deploy.yml
@@ -11,7 +11,7 @@ env:
 permissions: write-all
 jobs:
   demo-deploy:
-    # continue-on-error: true
+    continue-on-error: true
     name: Trigger test deployments
     runs-on: ubuntu-latest
     steps:
@@ -26,23 +26,35 @@ jobs:
             -H "X-GitHub-Api-Version: 2022-11-28" \
             https://api.github.com/repos/${TARGET_OWNER}/${TARGET_REPO}/dispatches \
             -d "{\"event_type\":\"deploy\",\"client_payload\":{\"targets\":\"${GITHUB_REPOSITORY}:${HEAD}\", \"use-cache\":\"true\"}}"
+            
+      # This would be better if it worked
+      # - name: Run 'deploy.yml' Workflow
+      #   uses: convictional/[email protected]
+      #   with:
+      #     owner: ${TARGET_OWNER}
+      #     repo: ${TARGET_REPO}
+      #     github_token: ${{ secrets.PAT }}
+      #     workflow_file_name: deploy.yml
+      #     client_payload: '{"targets":"${GITHUB_REPOSITORY}:${HEAD}", "use-cache":"true"}'
+      # - name: Wait for Workflow Action
+      #   run: |
+      #     curl -L \
+      #         -X POST \
+      #         -H "Accept: application/vnd.github+json" \
+      #         -H "Authorization: Bearer ${{ secrets.PAT }}" \
+      #         -H "X-GitHub-Api-Version: 2022-11-28" \
+      #         https://api.github.com/repos/${TARGET_OWNER}/${TARGET_REPO}/actions/runs/deploy.yml
       - name: Wait for Workflow Action
         run: |
           # Just give a minute or so to deploy
-          sleep 60
-          # curl -L \
-          #     -X POST \
-          #     -H "Accept: application/vnd.github+json" \
-          #     -H "Authorization: Bearer ${{ secrets.PAT }}" \
-          #     -H "X-GitHub-Api-Version: 2022-11-28" \
-          #     https://api.github.com/repos/${TARGET_OWNER}/${TARGET_REPO}/actions/runs/deploy.yml
+            sleep 90
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Post messages open requests
         run: |
-            msg="Test deployment available at <a href=\"${DEPLOY_URL}/${HEAD}\">${DEPLOY_URL}/${GITHUB_REPOSITORY}/${HEAD}</a>"
+            msg="Test deployment available at <a href=\"${DEPLOY_URL}/${GITHUB_REPOSITORY}/${HEAD}\">${DEPLOY_URL}/${GITHUB_REPOSITORY}/${HEAD}</a>"
             changed_pages="$(git diff --name-only origin/main -- '*.md')"
             # Logic for truncating out long sections commented out.
             # maxlines=-5
@@ -60,6 +72,6 @@ jobs:
                 # fi
                 msg="${msg}</ul>"
             fi
-            msg="${msg}<br><em>Test site may take a minute or so to deploy after PR Open or Update.</em>"
+            msg="${msg}<br><br><em><a href="${DEPLOY_URL}">See all deployed demo sites</a></em>"
             (gh pr comment ${HEAD} --edit-last --body "${msg}") || (gh pr comment ${HEAD} --body "${msg}")
             echo "::info title=Deploy successful::${DEPLOY_URL}/${GITHUB_REPOSITORY}/${HEAD}" 
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -1,15 +1,11 @@
 name: Deploy to gh-pages 
 on: 
- push:
+  push:
     branches: [main]
- workflow_dispatch:
-  inputs:
-    pr-deploy:
-      description: Deploy open merge requests in sub-directories.
-      type: boolean
-      default: true
+  workflow_dispatch:
 env:
   MODULE_LIST_PATH: docs/assets/module-list.json
+
   PYTHON_VERSION: 3.x
   GH_TOKEN: ${{ github.token }}
 permissions:
@@ -63,10 +59,4 @@ jobs:
         with:
           key: mkdocs-${{ hashfiles('.cache/**') }}
           path: .cache
-      - name: Post messages to PRs
-        run: |
-          for pr in ${{ steps.dev-deps.outputs.branches }}; do
-            msg="Test deployment available at <a href=\"https://docs.nesi.org.nz/${pr}\">https://docs.nesi.org.nz/${pr}</a>"
-            (gh pr comment ${pr} --edit-last --body "${msg}") || (gh pr comment ${pr} --body "${msg}")
-          done
 
diff --git a/.gitignore b/.gitignore
@@ -1,8 +1,5 @@
-from_zendesk/cache/**
-from_zendesk/import_worktree/**
 public/*
 production/*
 **.pyc
-.venv/**
-.ipynb_checkpoints
+.venv/*
 dictionary.dic
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -0,0 +1,34 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug Proselint",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "checks/run_proselint.py",
+            "args": ["docs/fail_checks.md"],
+            "console": "integratedTerminal",
+            "justMyCode": false
+        },
+        {
+            "name": "Debug Meta Check",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "checks/run_meta_check.py",
+            "args": ["docs/fail_checks.md"],
+            "console": "integratedTerminal",
+            "justMyCode": false
+        },
+        {
+            "name": "Debug Testbuild",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "checks/run_test_build.py",
+            "console": "integratedTerminal",
+            "justMyCode": false
+        }
+    ]
+}
diff --git a/README.md b/README.md
@@ -1,52 +1,52 @@
-# NeSI support documentation
-
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/nesi/support-docs?quickstart=1)
-
-[![Deploy to gh-pages](https://github.com/nesi/support-docs/actions/workflows/deploy.yml/badge.svg?branch=main&event=deployment_status)](https://github.com/nesi/support-docs/actions/workflows/deploy.yml)
-
-This repository contains the sources files for the NeSI support documentation.
-
-Rendered pages are visible at [https://docs.nesi.org.nz](http://docs.nesi.org.nz).
-
-## Contents
-
-The repository is organised using the following folders:
-
-- `checks` : scripts intended to be run by CI,
-- `docs`: markdown files, structure determines categories and sections[^1],
-- `docs/assets`: non-template related files, e.g. images,
-- `overrides`: theme overides or extensions for page templates.
-- `overrides/partials`: Overrides and extensions for sub components.
-
-[^1]: A section or category can be replaced by an `index.md` file, this will replace the default nav with a page.
-
-## Developer Documentation
-
-Following pages contain information to help maintain the documentation:
-
-- See [contributing](https://nesi.github.io/support-docs/CONTRIBUTING) ([local version](docs/CONTRIBUTING.md)), to learn how to you can contribute.
-- See [formatting](https://nesi.github.io/support-docs/FORMAT), for examples of markdown syntax.
-- See [create a new page](https://nesi.github.io/support-docs/NEWPAGE), for general principles to consider when writing pages.
-- See [macros](https://nesi.github.io/support-docs/MACROS), for `mkdocs-macros-plugin` environment.
-- See [checks](checks/README.md), for information on quality assurance tests.
-- See [workflows](.github/workflows/README.md), for information on CI workflows.
-
-## Viewing PR Branches
-
-![Demo Site](https://github.com/CallumWalley/support-docs-dev/actions/workflows/deploy.yml/badge.svg)
-
-Deployments of open pull requests can be viewed at [https://callumwalley.github.io/support-docs-dev/NAME-OF-BRANCH](https://callumwalley.github.io/support-docs-dev/)
-
-## Theme
-
-We are using the [mkdocs material theme](https://squidfunk.github.io/mkdocs-material/).
-
-## Analyics
-
-The site uses [Google analytics](https://analytics.google.com/analytics/web/#/p424742084). You will need to ask a google workspace admin to add you to the project.
-
-## Migration
-
-Migration of the Zendesk documentation is done using our [migration pipeline (NeSI internal GitLab](https://git.hpcf.nesi.org.nz/cwal219/migratedocs).
-
-Any one off filters (e.g. don't need to be checked every time, just when converting from ZD) should go there.
+# NeSI support documentation
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/nesi/support-docs?quickstart=1)
+
+[![Deploy to gh-pages](https://github.com/nesi/support-docs/actions/workflows/deploy.yml/badge.svg?branch=main&event=deployment_status)](https://github.com/nesi/support-docs/actions/workflows/deploy.yml)
+
+This repository contains the sources files for the NeSI support documentation.
+
+Rendered pages are visible at [https://docs.nesi.org.nz](http://docs.nesi.org.nz).
+
+## Contents
+
+The repository is organised using the following folders:
+
+- `checks` : scripts intended to be run by CI,
+- `docs`: markdown files, structure determines categories and sections[^1],
+- `docs/assets`: non-template related files, e.g. images,
+- `overrides`: theme overides or extensions for page templates.
+- `overrides/partials`: Overrides and extensions for sub components.
+
+[^1]: A section or category can be replaced by an `index.md` file, this will replace the default nav with a page.
+
+## Developer Documentation
+
+Following pages contain information to help maintain the documentation:
+
+- See [contributing](https://nesi.github.io/support-docs/CONTRIBUTING) ([local version](docs/CONTRIBUTING.md)), to learn how to you can contribute.
+- See [formatting](https://nesi.github.io/support-docs/FORMAT), for examples of markdown syntax.
+- See [create a new page](https://nesi.github.io/support-docs/NEWPAGE), for general principles to consider when writing pages.
+- See [macros](https://nesi.github.io/support-docs/MACROS), for `mkdocs-macros-plugin` environment.
+- See [checks](checks/README.md), for information on quality assurance tests.
+- See [workflows](.github/workflows/README.md), for information on CI workflows.
+
+## Viewing PR Branches
+
+![Demo Site](https://github.com/CallumWalley/support-docs-dev/actions/workflows/deploy.yml/badge.svg)
+
+Deployments of open pull requests can be viewed at [https://callumwalley.github.io/support-docs-dev/NAME-OF-BRANCH](https://callumwalley.github.io/support-docs-dev/)
+
+## Theme
+
+We are using the [mkdocs material theme](https://squidfunk.github.io/mkdocs-material/).
+
+## Analyics
+
+The site uses [Google analytics](https://analytics.google.com/analytics/web/#/p424742084). You will need to ask a google workspace admin to add you to the project.
+
+## Migration
+
+Migration of the Zendesk documentation is done using our [migration pipeline (NeSI internal GitLab](https://git.hpcf.nesi.org.nz/cwal219/migratedocs).
+
+Any one off filters (e.g. don't need to be checked every time, just when converting from ZD) should go there.
diff --git a/checks/run_meta_check.py b/checks/run_meta_check.py
@@ -27,7 +27,7 @@
 # Warning level for missing parameters.
 EXPECTED_PARAMETERS = {
     "title": "",
-    "template": ["main.html", "supported_apps.html", "get_support.html"],
+    "template": ["main.html", "supported_apps.html"],
     "description": "",
     "icon": "",
     "status": ["new", "deprecated"],
@@ -96,10 +96,13 @@ def main():
             except Exception as e:
                 print(f"::error file={input_path},title=misc,col=0,endColumn=0,line=1 ::{e}")
 
+
 def _run_check(f):
     for r in f():
         print(f"::{r.get('level', 'warning')} file={input_path},title={f.__name__},col={r.get('col', 0)},endColumn={r.get('endColumn', 99)},line={r.get('line', 1)}::{r.get('message', 'something wrong')}")
         sys.stdout.flush()
+        time.sleep(0.01)
+
 
 
 def _title_from_filename():
@@ -136,26 +139,29 @@ def _unpack(toc, a):
             return toc[a[0]]
         return _unpack(toc[a[0]]["children"], a[1:])
 
-    if in_code_block:
-        return
+    try:
+        if in_code_block:
+            return
 
-    header_match = re.match(r"^(#+)\s*(.*)$", line)
+        header_match = re.match(r"^(#+)\s*(.*)$", line)
 
-    if not header_match:
-        return
-
-    header_level = len(header_match.group(1))
-    header_name = header_match.group(2)
+        if not header_match:
+            return
+        
+        header_level = len(header_match.group(1))
+        header_name = header_match.group(2)
 
-    if header_level == 1:
-        toc = {header_name: {"lineno": lineno, "children": {}}}
-        toc_parents = [header_name]
+        if header_level == 1:
+            toc = {header_name: {"lineno": lineno, "children": {}}}
+            toc_parents = [header_name]
 
-    while header_level < len(toc_parents)+1:
-        toc_parents.pop(-1)
+        while header_level < len(toc_parents)+1:
+            toc_parents.pop(-1)
 
-    _unpack(toc, toc_parents)["children"][header_name] = {"level": header_level, "lineno": lineno, "children": {}}
-    toc_parents += [header_name]
+        _unpack(toc, toc_parents)["children"][header_name] = {"level": header_level, "lineno": lineno, "children": {}}
+        toc_parents += [header_name]
+    except Exception:
+        print(f"::error file={input_path},title=misc-nav,col=0,endColumn=0,line=1 ::Failed to parse Nav tree. Something is wrong.")
 
 
 def _nav_check():

diff --git a/checks/run_proselint.py b/checks/run_proselint.py
@@ -6,6 +6,7 @@
 
 import sys
 from pathlib import Path
+import time
 
 import proselint
 from proselint import config, tools
@@ -27,5 +28,6 @@
                 f"::{notice[7]} file={file},line={notice[2]+1},"
                 f"col={notice[3]+2},endColumn={notice[2]+notice[6]+1},"
                 f"title={notice[0]}::'{notice[1]}'",
-                flush=True,
+                flush=True
             )
+            time.sleep(0.01)
diff --git a/checks/run_test_build.py b/checks/run_test_build.py
@@ -6,11 +6,14 @@
 import logging
 import sys
 import re
+import time
+
 
 """ 
-This doesnt work and I have no idea why.
+This works but is a bit messy
 """
 
+
 def parse_macro(record):
 
     # These are not useful messages
@@ -29,6 +32,13 @@ def parse_macro(record):
         record.name = g["title"]
         record.filename = g["file"]
         record.msg = g["message"]
+
+    # Does not give correct path to file in question in 'title'.
+    # Infer from message.
+    m = re.search(r"'(.*?\.md)'",  record.msg)
+    if m:
+        record.filename = m.group(1)
+
     return True
 
 
@@ -41,4 +51,5 @@ def parse_macro(record):
         '::%(levelname)s file=%(filename)s,title=%(name)s,col=0,endColumn=0,line=%(lineno)s::%(message)s'))
     log.addHandler(sh)
     config = load_config(config_file_path="./mkdocs.yml")
-    build.build(config, dirty=True)
+    build.build(config)
+    time.sleep(5)
diff --git a/docs/NeSI_support_portal.md b/docs/NeSI_support_portal.md
diff --git a/docs/assets/icons/favicon_nesi.ico b/docs/assets/icons/favicon_nesi.ico