ci: Add GitHub Workflow to build and publish documentation

Author: jcfr

.github/workflows/build-and-publish-doxygen.yml

@@ -0,0 +1,154 @@
+name: Build and Publish
+
+on:
+  # Allows running this workflow manually from the Actions tab
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version of Slicer documentation to build and publish"
+        required: true
+
+permissions:
+  # Needed in the publish step to update gh-pages branch
+  contents: write
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Collect Inputs
+        id: collect_inputs
+        run: |
+          echo "EVENT_NAME [$EVENT_NAME]"
+          if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
+            version=${{ github.event.inputs.version }}
+          else
+            echo "::error ::Unsupported EVENT_NAME [$EVENT_NAME]"
+            exit 1
+          fi
+          echo "version=$version" >> $GITHUB_OUTPUT
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: gh-pages
+          path: gh-pages
+
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          repository: Slicer/Slicer
+          path: Slicer
+          ref: ${{ steps.collect_inputs.outputs.version }}
+
+      - uses: ssciwr/doxygen-install@527824132256e685f03ec80c0851fe79937eb1d6 # v1.6.3
+        with:
+          version: "1.10.0"
+
+      # The "dot" binary is provided by Graphviz
+      - uses: ts-graphviz/setup-graphviz@b1de5da23ed0a6d14e0aeee8ed52fdd87af2363c # v2.0.2
+
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          repository: Slicer/slicer-apidocs-builder
+          path: slicer-apidocs-builder
+          ref: 1744509e91fa66186d34e4c6968ee684131c51d1
+
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: '3.13'
+          cache: 'pip'
+
+      - name: Install slicer-apidocs-builder
+        run: |
+         pip install ./slicer-apidocs-builder
+
+      - name: Generate Documentation
+        id: generate
+        run: |
+          WARNING_LOG_FILE=/tmp/Slicer-Slicer-$SLICER_REPO_BRANCH-build/Utilities/Doxygen/UserDoxygenWarnings.txt
+          mkdir -p $(direname $WARNING_LOG_FILE)
+
+          slicer-apidocs-builder \
+            --skip-publish \
+            --slicer-repo-dir $(pwd)/Slicer \
+            --slicer-repo-branch "$SLICER_REPO_BRANCH" \
+            --slicer-repo-tag "${SLICER_REPO_TAG}" 2> >(tee $WARNING_LOG_FILE >&2)
+
+          echo "warning_log_file=$WARNING_LOG_FILE" >> $GITHUB_OUTPUT
+        env:
+          SLICER_REPO_BRANCH: ${{ steps.collect_inputs.outputs.version }}
+          SLICER_REPO_TAG: ""
+
+      - name: Parse and annotate Doxygen warnings
+        run: |
+          echo "WARNING_LOG_FILE [$WARNING_LOG_FILE]"
+          if [[ -f $WARNING_LOG_FILE ]]; then
+            buffer=""
+            while IFS= read -r line || [[ -n "$line" ]]; do
+              # If a buffer exists, prepend the buffered line to this line
+              if [[ -n "$buffer" ]]; then
+                line="$buffer$line"
+                buffer=""
+              fi
+
+              # Extract file, line number, and warning message
+              FILE=$(echo "$line" | grep -oP "^[^:]+" || true)
+              LINE=$(echo "$line" | grep -oP ":(\d+):" | tr -d ":" || true)
+              MESSAGE=$(echo "$line" | grep -oP "warning:.*" || true)
+
+              # If MESSAGE is found, process further
+              if [[ -n "$MESSAGE" ]]; then
+                MESSAGE=${MESSAGE#warning: }  # Strip "warning: " prefix
+
+                # Aggregate all subsequent lines starting with at least a space
+                while IFS= read -r continuation || [[ -n "$continuation" ]]; do
+                  if [[ "$continuation" =~ ^[[:space:]] ]]; then
+                    MESSAGE="${MESSAGE}%0A${continuation}"
+                  else
+                    # Buffer the line to be processed in the main loop
+                    buffer="$continuation"
+                    break
+                  fi
+                done
+              fi
+
+              # Annotate in GitHub Actions
+              if [[ -n "$FILE" && -n "$LINE" && -n "$MESSAGE" ]]; then
+                echo "::warning file=$FILE,line=$LINE::$MESSAGE"
+              elif [[ -n "$MESSAGE" ]]; then
+                echo "::warning ::$MESSAGE"
+              else
+                echo "Skipped unmatched line: $line"
+              fi
+
+            done < "$WARNING_LOG_FILE"
+          else
+            echo "No Doxygen warnings log found."
+          fi
+        env:
+          WARNING_LOG_FILE: ${{ steps.generate.outputs.warning_log_file }}
+
+      - uses: actions/create-github-app-token@c1a285145b9d317df6ced56c09f525b5c2b6f755 # v1.11.1
+        id: app-token
+        with:
+          app-id: ${{ vars.SLICER_APP_ID }}
+          private-key: ${{ secrets.SLICER_APP_PRIVATE_KEY }}
+
+      - name: Publish documentation
+        run: |
+          slicer-apidocs-builder \
+            --skip-build \
+            --slicer-repo-dir $(pwd)/Slicer \
+            --slicer-repo-name ${SLICER_REPO_NAME} \
+            --slicer-repo-branch "${SLICER_REPO_BRANCH}" \
+            --slicer-repo-tag "${SLICER_REPO_TAG}" \
+            --publish-github-repo-name "Slicer/${PUBLISH_GITHUB_PROJECT_NAME}" \
+            --publish-github-repo-branch gh-pages
+        env:
+          PUBLISH_GITHUB_PROJECT_NAME: apidocs.slicer.org
+          PUBLISH_GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+          SLICER_REPO_NAME: Slicer/Slicer
+          SLICER_REPO_BRANCH: ${{ steps.collect_inputs.outputs.version }}
+          SLICER_REPO_TAG: ""
+