[DLStreamer] New CI workflow for building DL Streamer documentation (#176)

Signed-off-by: dmichalo <dawid.michalowski@intel.com>

Author: dmichalo

.github/workflows/dls-build-documentation.yaml

@@ -0,0 +1,86 @@
+name: "[DLS] Documentation PR workflow"
+run-name: "[DLS] Documentation PR workflow (by @${{ github.actor }} via ${{ github.event_name }})"
+on:
+  push:
+    branches:
+      - 'main'
+    paths:
+      - 'libraries/dl-streamer/docs/**'
+  pull_request:
+    paths:
+      - 'libraries/dl-streamer/docs/**'
+permissions: read-all
+
+jobs:
+  build-docs:
+    name: Build DL Streamer documentation
+    runs-on: ubuntu-latest # Change to self-hosted when ready to unblock linkcheck: [self-hosted, linux]
+    steps:
+      - name: Check out edge-ai-libraries repository/libraries/dl-streamer
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 #4.2.2
+        with:
+          sparse-checkout: |
+            libraries/dl-streamer
+
+      - name: Run build script
+        run: |
+          ./libraries/dl-streamer/docs/build_html.sh "actions-gh-pages:latest" gh-pages
+          
+      - name: Documentation build summary
+        if: always()
+        run: |
+          summary_content=""
+          
+          # Check if index.html for documentation exists
+          index_file_path='./libraries/dl-streamer/docs/build-html/index.html'
+          if [ -f "$index_file_path" ]; then
+            result="Documentation built: YES :white_check_mark:"
+          else
+            result="Documentation built: NO :x:"
+          fi
+          echo "$result"
+          summary_content+="$result\n"
+          
+          # Check broken links in linkcheck
+          linkcheck_file_path='./libraries/dl-streamer/docs/build-linkcheck/output.txt'
+          broken_count=$(grep -o '\[broken\]' "$linkcheck_file_path" | wc -l)
+          if [ "$broken_count" -eq 0 ]; then
+            result="Broken links: $broken_count :white_check_mark:"
+          else
+            result="Broken links: $broken_count :x:"
+          fi
+          echo "$result"
+          summary_content+="$result\n"
+          
+          # Spelling
+          result="Spelling: check report from artifacts"
+          echo "$result"
+          summary_content+="$result\n"
+          
+          echo -e "$summary_content" >> $GITHUB_STEP_SUMMARY
+
+      - name: Upload linkcheck report
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 #4.6.2
+        if: always()
+        with:
+         name: docs_linkcheck_report
+         path: ./libraries/dl-streamer/docs/build-linkcheck/
+
+      - name: Upload spelling report
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 #4.6.2
+        if: always()
+        with:
+         name: docs_spelling_report
+         path: ./libraries/dl-streamer/docs/build-spelling/
+
+      - name: Upload pages
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 #4.6.2
+        if: always()
+        with:
+          name: docs_site
+          path: ./libraries/dl-streamer/docs/build-html
+
+      - name: Clean up
+        if: always()
+        run: |
+          rm -rf edge-ai-libraries-repo

libraries/dl-streamer/docs/.gitignore

@@ -1,4 +1,4 @@
-build**
+build**/
 
 source/_doxygen/src/
 source/_doxygen/src-api2.0/

libraries/dl-streamer/docs/build_html.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# ==============================================================================
+# Copyright (C) 2022-2025 Intel Corporation
+#
+# SPDX-License-Identifier: MIT
+# ==============================================================================
+
+IMAGE_NAME=${1:-"sphinx-docs:latest"}
+CONTAINER_NAME=${2:-docs_pages}
+DOCKER_PRIVATE_REGISTRY=${3:-""}
+
+ROOT="$(realpath "$(dirname "${0}")"/..)"
+DOCS_DIR=$ROOT/docs
+DOXYGEN_DIR=$ROOT/docs/source/_doxygen
+IMAGE_DOCS_DIR=/root/docs
+
+# Copy necessary files located outside of this folder
+echo "::group::Prepare for docker build"
+cp -r "$ROOT"/samples/model_index.yaml "$DOCS_DIR"
+cp -r "$ROOT"/samples/verified_models.json "$DOCS_DIR"
+mkdir -p "$DOXYGEN_DIR"/src
+cp -r "$ROOT"/gst-libs/gst/videoanalytics "$ROOT"/python/gstgva "$ROOT"/include/dlstreamer/gst/metadata "$DOXYGEN_DIR"/src
+mkdir -p "$DOXYGEN_DIR"/src-api2.0
+cp -r "$ROOT"/include/dlstreamer "$DOXYGEN_DIR"/src-api2.0
+echo "::endgroup::"
+
+# Build docker image
+echo "::group::Building docker image"
+docker_build="docker build \
+  -f $DOCS_DIR/_docker/Dockerfile \
+  -t $IMAGE_NAME \
+  --build-arg DOCKER_PRIVATE_REGISTRY=$DOCKER_PRIVATE_REGISTRY \
+  --build-arg DOCS_DIR=$IMAGE_DOCS_DIR \
+  $DOCS_DIR"
+echo "$docker_build"
+if ! $docker_build ; then
+  echo "::error::docker build failed"
+  exit 1
+fi
+echo "::endgroup::"
+
+echo "::group::Removing container"
+docker container rm "$CONTAINER_NAME"
+echo "::endgroup::"
+
+# Building
+echo "Building..."
+BUILD_TYPES="html,spelling,linkcheck"
+docker run --name "$CONTAINER_NAME" "$IMAGE_NAME" ./scripts/sphinx_build.sh "$BUILD_TYPES"
+RUN_RESULT=$?
+
+echo "::group::Gathering build result"
+IFS=',' read -ra BUILDS <<< "$BUILD_TYPES"
+for btype in "${BUILDS[@]}"; do
+  build_dir="build-$btype"
+  rm -rf "$build_dir"
+  # Copy
+  docker cp "$CONTAINER_NAME":$IMAGE_DOCS_DIR/"$build_dir" "$DOCS_DIR"
+  # Remove non-relevant things
+  rm -rf "$DOCS_DIR"/"$build_dir"/.buildinfo "$DOCS_DIR"/"$build_dir"/.doctrees/
+done
+echo "::endgroup::"
+
+echo "Done, exit code $RUN_RESULT"
+exit $RUN_RESULT