Feature/documentation

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  - package-ecosystem: "gradle" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+    target-branch: "develop"

.github/workflows/build-artifacts.yml

@@ -0,0 +1,88 @@
+name: Build Artifacts
+on:
+  workflow_call:
+    inputs:
+      java-version:
+        required: true
+        type: string
+        default: '17'
+      run-sonar:
+        required: false
+        type: boolean
+        default: false
+env:
+  SONAR_ORGANIZATION: ${{ secrets.SONAR_ORGANIZATION || 'aim42' }}
+  SONAR_PROJECT_KEY: ${{ secrets.SONAR_PROJECT_KEY || 'aim42_htmlSanityCheck' }}
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: ${{ inputs.java-version }}
+
+      - name: Cache Gradle Toolchain JDKs
+        uses: actions/cache@v4
+        with:
+          path: ~/.gradle/jdks
+          key: "${{ runner.os }}-gradle-jdks"
+          restore-keys: ${{ runner.os }}-jdk
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+        with:
+          cache-read-only: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/develop' }}
+
+      - name: Cache Gradle packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.gradle/caches
+          key: "${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle') }}"
+          restore-keys: ${{ runner.os }}-gradle
+
+      - name: Validate Gradle Wrapper
+        uses: gradle/actions/wrapper-validation@v4
+
+      - name: Execute Gradle build
+        run: ./gradlew clean check integrationTest --scan --stacktrace
+
+      - name: Cache SonarCloud packages
+        uses: actions/cache@v4
+        if: ${{ inputs.run-sonar }}
+        with:
+          path: ~/.sonar/cache
+          key: ${{ runner.os }}-sonar
+          restore-keys: ${{ runner.os }}-sonar
+
+      - name: Analyze with SonarCloud
+        if: ${{ inputs.run-sonar }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+        run: |
+          BRANCH_NAME=${GITHUB_REF#refs/heads/}
+          ./gradlew sonar -Psonar.branch.name=${BRANCH_NAME} --info --scan
+
+      - name: Upload Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-artifacts
+          path: |
+            **/build
+
+      - name: Collect state upon failure
+        if: failure()
+        run: |
+          echo "Git:"
+          git status
+          echo "Env:"
+          env
+          echo "PWD:"
+          pwd
+          echo "Files:"
+          find * -ls

.github/workflows/gh-pages.yml

@@ -1,37 +1,84 @@
 name: GitHub Pages
 
 on:
+  pull_request:
   push:
-    branches:
-      - main  # Set a branch name to trigger deployment
-#  pull_request:
-  workflow_dispatch: {}
+  workflow_dispatch:
+    inputs:
+      perform_step:
+        type: boolean
+        description: 'Publish GH Page'
+        default: false
 
 jobs:
-  deploy:
-    runs-on: ubuntu-20.04
+  build-artifacts:
+    uses: ./.github/workflows/build-artifacts.yml
+    with:
+      # SonarQube requires JDK 17 or higher
+      java-version: '17'
+
+  pages:
+    needs: build-artifacts
+    runs-on: ubuntu-latest
     concurrency:
-      group: ${{ github.workflow }}-${{ github.ref }}
+      group: "${{ github.workflow }}-${{ github.ref }}"
     env:
       DTC_HEADLESS: true
     steps:
-      - uses: actions/checkout@v2
-      - name: exportExcel
-        run: ./dtcw exportExcel
-      - name: generateSite
-        run: ./dtcw generateSite
-      - name: removeDraft
-        run: find build/microsite/output/. -name "*-draft.html" -type f -delete
-      - name: generatePdf
-        run: ./dtcw generatePdf
-      - name: htmlSanityCheck
-        run: ./dtcw htmlSanityCheck
-      - name: copyToPublic
-        run: cp -r ./build/pdf ./build/microsite/output && cp -r ./build/report/htmlchecks ./build/microsite/output && cp -r ./build/microsite/output ./public
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
-#        if: ${{ github.ref == 'refs/heads/main' }}
+      - name: Install dot (Graphviz)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y graphviz
+
+      - name: Cache Gradle packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.gradle/caches
+          key: "${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle') }}"
+          restore-keys: ${{ runner.os }}-gradle
+
+      - name: Cache .doctoolchain
+        uses: actions/cache@v2
+        with:
+          path: ~/.doctoolchain
+          key: "${{ runner.os }}-doctoolchain-${{ hashFiles('**/lockfiles') }}"
+          restore-keys: ${{ runner.os }}-doctoolchain
+
+      - name: Check out
+        uses: actions/checkout@v2
+
+      - name: Setup JDK
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+
+      - name: Download Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: build-artifacts
+          path: .
+
+      - name: Validate Gradle Wrapper
+        uses: gradle/actions/wrapper-validation@v4
+
+      - name: Generate Pages
+        run: ./generate-pages
+
+      - name: Upload Artifacts
+        uses: actions/upload-pages-artifact@v3
+        with:
+          name: github-pages
+          path: public
+          retention-days: 7
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: pages
+    if: ${{ github.event.inputs.perform_step }}
+    steps:
+      - name: Deploy Pages
+        uses: actions/deploy-pages@v4
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./public
+          token: ${{ secrets.GITHUB_TOKEN }}
 

.github/workflows/gradle-build.yml

@@ -1,20 +1,52 @@
-name: Gradle Build Check
+name: Build and Test
 on:
   pull_request:
   push:
-  workflow_dispatch: {}
+  workflow_dispatch:
 jobs:
-  gradle:
-    runs-on: ubuntu-22.04
+  build-artifacts:
+    uses: ./.github/workflows/build-artifacts.yml
+    with:
+      # SonarQube requires JDK 17 or higher
+      java-version: '17'
+      run-sonar: true
+
+  post-build:
+    needs: build-artifacts
+    runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-java@v3
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Download Artifacts
+        uses: actions/download-artifact@v4
         with:
-          distribution: temurin
-          java-version: 8
+          name: build-artifacts
+          path: .
 
-      - name: Setup Gradle
-        uses: gradle/gradle-build-action@v2
+      - name: 'Publish Test Results'
+        uses: EnricoMi/publish-unit-test-result-action/linux@v2
+        if: always()
+        with:
+          files: |
+            **/build/test-results/**/*.xml
+
+      - name: JaCoCo Test Coverage Report
+        uses: PavanMudigonda/[email protected]
+        with:
+          coverage_results_path: "htmlSanityCheck-gradle-plugin/build/reports/jacoco/testCodeCoverageReport/testCodeCoverageReport.xml"
+          coverage_report_name: Coverage
+          coverage_report_title: JaCoCo
+          github_token: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Execute Gradle build
-        run: ./gradlew check --scan -stacktrace
+      - name: Collect state upon failure
+        if: failure()
+        run: |
+          echo "Git:"
+          git status
+          echo "Env:"
+          env
+          echo "PWD:"
+          pwd
+          echo "Files:"
+          find * -ls

.github/workflows/gradle-wrapper-validation.yml

@@ -0,0 +1,13 @@
+name: "Validate Gradle Wrapper"
+on: [pull_request]
+
+jobs:
+  validation:
+    name: "Validation"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Validate Gradle Wrapper
+        uses: gradle/actions/wrapper-validation@v4

.github/workflows/test-java-os-mix.yml

@@ -0,0 +1,60 @@
+name: HTML Sanity Check Matrix Test
+on:
+  pull_request:
+  push:
+  workflow_dispatch:
+
+jobs:
+  build-artifacts:
+    uses: ./.github/workflows/build-artifacts.yml
+    with:
+      # SonarQube requires JDK 17 or higher
+      java-version: '17'
+
+  test-java-os-mix:
+    needs: build-artifacts
+    strategy:
+      matrix:
+        os-version: [ ubuntu-latest, macos-14, windows-latest ]
+        java-version: [ 8, 11, 17, 21 ]
+        exclude:
+          - os-version: macos-14
+            java-version: 8
+    runs-on: ${{ matrix.os-version }}
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Validate Gradle Wrapper
+        uses: gradle/actions/wrapper-validation@v4
+
+      - name: Setup JDK
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: ${{ matrix.java-version }}
+
+      - name: Download Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: build-artifacts
+          path: .
+
+      - name: Execute integration test (on Unixes)
+        run: |
+          cd integration-test/gradle-plugin
+          uname -a
+          ./gradlew --version
+          ./gradlew htmlSanityCheck --scan
+
+      - name: Collect state upon failure
+        if: failure()
+        run: |
+          echo "Git:"
+          git status
+          echo "Env:"
+          env
+          echo "PWD:"
+          pwd
+          echo "Files:"
+          find * -ls

.gitignore

@@ -35,3 +35,8 @@ src/docs/excel
 src/docs/website/_site
 lib
 src/docs/resources/graphics/.DS_Store
+/.sdkmanrc
+.envrc
+*.log
+tmp/
+public/