CI: run workflow on docs changes only

Author: PrinceEGY

.github/workflows/docs.yml

@@ -3,25 +3,75 @@ on:
   push:
     branches:
       - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+      - "**/*.py" # Watch all Python files
   pull_request:
     branches:
       - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+      - "**/*.py" # Watch all Python files
+
 permissions:
   contents: write
+
 jobs:
   Docs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all history for comparing changes
+
+      - name: Check for docstring changes
+        id: check_changes
+        run: |
+          # Get the last two commits
+          CHANGED_FILES=$(git diff --name-only HEAD^ HEAD)
+
+          # Check if docs files changed directly
+          if echo "$CHANGED_FILES" | grep -q -E "^docs/|mkdocs.yml"; then
+            echo "Direct documentation changes found"
+            echo "should_deploy=true" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Check Python files for docstring changes
+          for file in $(echo "$CHANGED_FILES" | grep '\.py$'); do
+            if [ -f "$file" ]; then
+              if git diff HEAD^ HEAD "$file" | grep -q '^[+-][\t ]*['"'"'\"]\{3\}'; then
+                echo "Docstring changes found in $file"
+                echo "should_deploy=true" >> $GITHUB_OUTPUT
+                exit 0
+              fi
+            fi
+          done
+
+          echo "No relevant changes found"
+          echo "should_deploy=false" >> $GITHUB_OUTPUT
+
       - uses: actions/setup-python@v5
+        if: steps.check_changes.outputs.should_deploy == 'true'
         with:
           python-version: 3.x
+
       - uses: actions/cache@v4
+        if: steps.check_changes.outputs.should_deploy == 'true'
         with:
           key: ${{github.ref}}
           path: .cache
+
       - name: Install dependencies
+        if: steps.check_changes.outputs.should_deploy == 'true'
         run: |
           python -m pip install --upgrade pip
           pip install mkdocs-material mkdocstrings-python mkdocs-include-markdown-plugin
-      - run: mkdocs gh-deploy --force
+
+      - name: Deploy docs
+        if: steps.check_changes.outputs.should_deploy == 'true'
+        run: mkdocs gh-deploy --force