Update workflow

Author: briling

.github/workflows/docs-build-test-deploy.yml

@@ -4,7 +4,7 @@ name: Python Package with caching
 
 # cancel any previous running or pending jobs from the same branch
 concurrency:
-  group: python-package-conda-cache-${{ github.head_ref }}
+  group: python-package-conda-cache-${{ github.ref }}
   cancel-in-progress: true
 
 on:
@@ -22,12 +22,13 @@ env:
   CACHE_NUMBER: 0  # increase to reset cache manually
 
 jobs:
+
   build:
 
+    # do not run twice when push to a branch linked to a PR
     # https://github.com/orgs/community/discussions/57827
     if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
 
-
     strategy:
       matrix:
         include:
@@ -52,7 +53,8 @@ jobs:
       - name: Set cache date
         run: echo "DATE=$(date +'%Y%m%d')" >> $GITHUB_ENV
 
-      - uses: actions/cache@v4
+      - name: Use env cache
+        uses: actions/cache@v4
         with:
           path: ${{ matrix.prefix }}
           key: ${{ matrix.label }}-conda-${{ hashFiles('environment.yml') }}-${{ env.DATE }}-${{ env.CACHE_NUMBER }}
@@ -65,3 +67,90 @@ jobs:
       - name: Run tests
         shell: bash -l {0}
         run: pytest ./tests
+
+
+  # maybe split back into two workflows depending on each other
+  build-docs:
+    needs: build
+
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            label: linux-64
+            prefix: /usr/share/miniconda3/envs/my-env
+
+    name: ${{ matrix.label }}
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Miniforge
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+            miniforge-version: latest
+            activate-environment: my-env
+
+      - name: Set cache date
+        run: echo "DATE=$(date +'%Y%m%d')" >> $GITHUB_ENV
+
+      - name: Restore doc env cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ matrix.prefix }}
+          key: ${{ matrix.label }}-conda-${{ hashFiles('environment.yml') }}-${{ hashFiles('docs/requirements.txt') }}-${{ env.DATE }}-${{ env.CACHE_NUMBER }}
+        id: cache-doc
+
+      - name: Restore env cache
+        if: steps.cache-doc.outputs.cache-hit != 'true'
+        uses: actions/cache/restore@v4
+        with:
+          path: ${{ matrix.prefix }}
+          key: ${{ matrix.label }}-conda-${{ hashFiles('environment.yml') }}-${{ env.DATE }}-${{ env.CACHE_NUMBER }}
+          fail-on-cache-miss: true
+        id: cache
+
+      - name: Install documentation requirements
+        if: steps.cache-doc.outputs.cache-hit != 'true'
+        shell: bash -l {0}
+        run: pip install -r docs/requirements.txt
+
+      - name: Save doc env cache
+        if: steps.cache-doc.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: ${{ matrix.prefix }}
+          key: ${{ matrix.label }}-conda-${{ hashFiles('environment.yml') }}-${{ hashFiles('docs/requirements.txt') }}-${{ env.DATE }}-${{ env.CACHE_NUMBER }}
+        id: cache-doc
+
+      - name: Build documentation src
+        shell: bash -l {0}
+        run: make build-src -C docs/
+
+      - name: Build HTML
+        shell: bash -l {0}
+        run: make html -C docs/
+
+      - name: Upload artifacts
+        if: github.ref == 'refs/heads/master' && github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html/
+
+  deploy:
+    if: github.ref == 'refs/heads/master' && github.event_name == 'push'
+    needs: build-docs
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+
+    permissions:
+      pages: write
+      id-token: write
+
+    steps:
+      - name: Deploy
+        uses: actions/deploy-pages@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}