Deploy documentation

.github/doxygen.json

@@ -0,0 +1,16 @@
+{
+  "problemMatcher": [
+    {
+      "owner": "doxygen",
+      "severity": "warning",
+      "pattern": [
+        {
+          "regexp": "^(.*):(\\d+): warning: (.*)$",
+          "file": 1,
+          "line": 2,
+          "message": 3
+        }
+      ]
+    }
+  ]
+}

.github/linkchecker.json

@@ -0,0 +1,18 @@
+{
+  "problemMatcher": [
+    {
+      "owner": "linkchecker",
+      "severity": "warning",
+      "pattern": [
+        {
+          "regexp": "^(.*):(\\d+):(\\d+);(.*);(.*);(.*)$",
+          "file": 1,
+          "line": 2,
+          "column": 3,
+          "code": 5,
+          "message": 6
+        }
+      ]
+    }
+  ]
+}

.github/workflows/docs.yml

@@ -0,0 +1,125 @@
+name: Build Doxygen Documentation
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  DOXYGEN_VERSION: 1.9.6
+  DOXYGEN_URL: 'https://sourceforge.net/projects/doxygen/files/rel-{VERSION}/doxygen-{VERSION}.linux.bin.tar.gz/download'
+
+jobs:
+  documentation:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Install packages
+        shell: bash
+        run: |
+          sudo apt-get update
+          sudo pip install LinkChecker
+    
+      - name: Cache Doxygen ${{ env.DOXYGEN_VERSION }}
+        id: cache-doxygen
+        uses: actions/cache@v3
+        with:
+          path: /opt/doxygen-${{ env.DOXYGEN_VERSION }}
+          key: doxygen-${{ env.DOXYGEN_VERSION }}-${{ runner.os }}
+
+      - name: Download Doxygen ${{ env.DOXYGEN_VERSION }}
+        if: steps.cache-doxygen.outputs.cache-hit != 'true'
+        shell: bash
+        run: |
+          wget -O doxygen.tgz $(sed -e 's/{VERSION}/${{ env.DOXYGEN_VERSION }}/g' <<< ${{ env.DOXYGEN_URL }})
+          sudo tar -C /opt -xf doxygen.tgz
+  
+      - name: Install Doxygen ${{ env.DOXYGEN_VERSION }}
+        if: env.DOXYGEN_VERSION != 'none'
+        shell: bash
+        run: |
+          sudo ln -s /opt/doxygen-${{ env.DOXYGEN_VERSION }}/bin/doxygen /usr/local/bin/
+          which doxygen
+          doxygen --version
+
+      - name: Generate doxygen
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          echo "::add-matcher::.github/doxygen.json"
+          ./Documentation/Doxygen/gen_doc.sh
+          echo "::remove-matcher owner=doxygen::"
+  
+      - name: Run linkchecker
+        shell: bash
+        run: |
+          echo "::add-matcher::.github/linkchecker.json"
+          ./Documentation/Doxygen/check_links.sh
+          echo "::remove-matcher owner=linkchecker::"
+
+      - name: Archive documentation
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v3
+        with:
+          name: documentation
+          path: ./Documentation/html/
+          retention-days: 1
+          if-no-files-found: error
+
+      - name: Archive documentation
+        if: (github.event_name == 'release' || github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+        shell: bash
+        run: |
+          tar -cvjf /tmp/doc.tbz2 -C ./Documentation/html/ .
+
+          - uses: actions/checkout@v3
+          if: inputs.doc-path && inputs.gh-pages-branch && (github.event_name == 'release' || github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+          with:
+            ref: gh-pages
+    
+      - name: Publish documentation
+        if: (github.event_name == 'release' || github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+        shell: bash
+        run: |
+          rm -rf ${GITHUB_REF_NAME}
+          mkdir -p ${GITHUB_REF_NAME}
+          tar -xvjf /tmp/doc.tbz2 -C ${GITHUB_REF_NAME}
+          if ${{ github.event_name == 'release' }}; then
+            rm -f latest
+            ln -s ${GITHUB_REF_NAME} latest
+            MSG="release"
+          else
+            MSG="branch"
+          fi
+          .github/update_versions.sh
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+          git add .
+          git commit -m "Update documentation for ${MSG} ${GITHUB_REF_NAME}"
+          git push
+  
+      - uses: actions/checkout@v3
+        if: (github.event_name == 'release' || github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+        with:
+          ref: ${{ github.ref }}
+
+      - name: Trigger GH-Pages deployment
+        if: (github.event_name == 'release' || github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh workflow run gh-pages.yml --ref gh-pages
+          if [ $? -ne 0 ]; then
+            echo "::notice::Failed to trigger GH-Pages deployment via workflow 'gh-pages.yml'!"
+          fi
+    

.github/workflows/gh-pages.yml

@@ -0,0 +1,46 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to GitHub Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: [gh-pages]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          # Upload entire repository
+          path: '.'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

Documentation/Doxygen/check_links.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+
+set -o pipefail
+
+DIRNAME=$(dirname $(realpath $0))
+REQUIRED_GEN_PACK_LIB="0.8.4"
+
+############ gen-pack library ###########
+
+function install_lib() {
+  local URL="https://github.com/Open-CMSIS-Pack/gen-pack/archive/refs/tags/v$1.tar.gz"
+  local STATUS=$(curl -sLI "${URL}" | grep "^HTTP" | tail -n 1 | cut -d' ' -f2 || echo "$((600+$?))")
+  if [[ $STATUS -ge 400 ]]; then
+    echo "Wrong/unavailable gen-pack lib version '$1'!" >&2
+    echo "Check REQUIRED_GEN_PACK_LIB variable."  >&2
+    echo "For available versions see https://github.com/Open-CMSIS-Pack/gen-pack/tags." >&2
+    exit 1
+  fi
+  echo "Downloading gen-pack lib version '$1' to '$2' ..."
+  mkdir -p "$2"
+  curl -L "${URL}" -s | tar -xzf - --strip-components 1 -C "$2" || exit 1
+}
+
+function load_lib() {
+  if [[ -d ${GEN_PACK_LIB} ]]; then
+    . "${GEN_PACK_LIB}/gen-pack"
+    return 0
+  fi
+  local GLOBAL_LIB="/usr/local/share/gen-pack/${REQUIRED_GEN_PACK_LIB}"
+  local USER_LIB="${HOME}/.local/share/gen-pack/${REQUIRED_GEN_PACK_LIB}"
+  if [[ ! -d "${GLOBAL_LIB}" && ! -d "${USER_LIB}" ]]; then
+    echo "Required gen-pack lib not found!" >&2
+    install_lib "${REQUIRED_GEN_PACK_LIB}" "${USER_LIB}"
+  fi
+
+  if [[ -d "${GLOBAL_LIB}" ]]; then
+    . "${GLOBAL_LIB}/gen-pack"
+  elif [[ -d "${USER_LIB}" ]]; then
+    . "${USER_LIB}/gen-pack"
+  else
+    echo "Required gen-pack lib is not installed!" >&2
+    exit 1
+  fi
+}
+
+load_lib
+find_linkchecker
+
+#########################################
+
+check_links "${DIRNAME}/../index.html" "${DIRNAME}"

Documentation/version.js

@@ -0,0 +1,2 @@
+
+function writeVersionDropdown() {}