feat: adding docs change validation step in reuseable CI (#390)

### Description

Added a new job validate-docs-change.
This job will attempt to serve the documentation and fail if there are
any errors.
If errors occur, they will be printed in the check logs step.

Another stage, enforce-docs-changes, reviews the result of
validate-docs-change and uses run metadata to determine whether the job
should fail the pipeline.

When the PR targets the main branch, enforce-docs-changes will enforce
failure on broken documentation and block merge.
For other branches, it serves as an indicator of documentation issues
without blocking the merge.

### Checklist

- [ ] `README.md` has been updated or is not required
- [ ] push trigger tests
- [ ] manual release test
- [ ] automated releases test
- [ ] pull request trigger tests
- [ ] schedule trigger tests
- [ ] workflow errors/warnings reviewed and addressed

### Testing done 
(for each selected checkbox, the corresponding test results link should
be listed here)

Author: siddharth-khatsuriya

.github/workflows/reusable-build-test-release.yml

@@ -321,6 +321,44 @@ jobs:
           splunk_version_list=$(echo '${{ steps.determine_splunk.outputs.matrixSplunk }}' | jq -r '.[].version')
           sc4s_version_list=$(echo '${{ steps.matrix.outputs.supportedSC4S }}' | jq -r '.[].version')
           echo -e "## Summary of Versions Used\n- **Splunk versions used:** (${splunk_version_list})\n- **SC4S versions used:** (${sc4s_version_list})\n- Browser: Chrome" >> "$GITHUB_STEP_SUMMARY"
+  
+  validate-docs-change:
+    runs-on: ubuntu-latest  
+    container:
+      image: python:3.9
+    outputs:
+      status: ${{ steps.validate.outputs.status }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: false
+          persist-credentials: false
+      - name: Installing requirements
+        run: |
+          pip install pip -U
+          pip install mkdocs==1.6.1 mkdocs-material==9.6.9 poetry
+      - name: validate
+        id: validate
+        run: |
+          if poetry run mkdocs build --strict; then
+            echo "status=success" >> "$GITHUB_OUTPUT"
+            echo "status :: success"
+          else
+            echo "status=failure" >> "$GITHUB_OUTPUT"
+            echo "status :: failure"
+          fi
+
+  enforce-docs-checks:
+    runs-on: ubuntu-latest  
+    needs: validate-docs-change
+    if: github.ref == 'refs/heads/main' || github.event_name == 'pull_request'
+    steps:
+      - name: Fail if validate-docs-change failed
+        run: |
+          if [ "${{ needs.validate-docs-change.outputs.status }}" == "failure" ]; then
+            exit 1
+          fi
+
   fossa-scan:
     runs-on: ubuntu-latest
     steps:
@@ -2956,6 +2994,7 @@ jobs:
       - run-ucc-modinput-tests
       - run-ui-tests
       - validate-pr-title
+      - enforce-docs-checks
     runs-on: ubuntu-latest
     env:
       NEEDS: ${{ toJson(needs) }}
@@ -2973,6 +3012,11 @@ jobs:
               echo "run-publish=false" >> "$GITHUB_OUTPUT"
               echo "Publish conditions are not met."
           fi
+          if ${{ github.base_ref == 'main' }} && ${{ needs.enforce-docs-checks.result != 'success' }};
+          then
+            echo " There are documentation changes that break mkdocs deploy. please check validate-docs-change step."
+            exit 1
+          fi
 
   publish:
     if: ${{ !cancelled() && needs.pre-publish.outputs.run-publish == 'true' && (github.event_name == 'push' || needs.validate-custom-version.result == 'success') }}