misc: Address review comments

Author: JDBetteridge

.github/actions/docker-run/action.yaml

@@ -43,7 +43,7 @@ runs:
         done <<< "$ENV_INPUT"
         # Remove the leading space from the first concatenation
         ENV_STRING="${ENV_STRING# }"
-        echo "env=$ENV_STRING" >> "$GITHUB_OUTPUT"
+        echo "docker_environment_args=$ENV_STRING" >> "$GITHUB_OUTPUT"
 
     - id: dockerrun
       name: "Run command ${{ inputs.command }} in ${{ inputs.tag }} docker container"
@@ -56,6 +56,6 @@ runs:
           ${{ inputs.args }} \
           --name "ci-${NAME:-${{ inputs.tag }}}-${{ inputs.uid }}" \
           --env-file=docker/coverage.env \
-          ${{ steps.processenv.outputs.env }} \
+          ${{ steps.processenv.outputs.docker_environment_args }} \
           "${{ inputs.tag }}_${{ inputs.uid }}" \
           ${{ inputs.command }}

.github/actions/readme.md

@@ -0,0 +1,109 @@
+# Devito Actions
+
+The Devito actions can either be used from the Github interface:
+```yaml
+uses: devitocodes/devito/.github/actions/docker-build@main
+```
+
+Or internally from within the repository:
+```yaml
+uses: ./.github/actions/docker-run
+```
+
+## `docker-build`
+
+Inputs:
+
+- `file`: Dockerfile containing build instructions (default: `Dockerfile`)
+- `tag`: Tag to add to the built image
+- `base`: Base docker image to build on top of
+- `args`: Arguments to pass to `docker build`
+
+Outputs:
+
+- `unique`: Unique identifier for the CI run (ie: `${{ steps.build.outputs.unique }}`)
+
+Example:
+
+```yaml
+jobs:
+  test:
+    steps:
+    - id: build
+      name: Build docker image for Devito
+      uses: ./.github/actions/docker-build
+      with:
+        file: docker/Dockerfile.devito
+        tag: tag-related-to-test-config
+        base: base-image-to-build-from
+        args: "--more-docker-build-args"
+```
+
+## `docker-run`
+
+Inputs:
+
+- `uid`: Unique identifier output from docker-build action
+- `tag`: Tag of the built image to use
+- `name`: Name substring for docker to use when running the command (optional)
+- `args`: Arguments to pass to `docker run`, `--init -t --rm` are always added
+- `env`: Environment variables to set inside the docker container, one environment variable per line
+-command: Command to execute inside of the docker container
+
+### Notes
+
+- The UID must be unique, easily obtained from build action
+- The tag must match built image, easily obtained from build action
+- If you provide a custom name `foo` the container name will be `ci-foo-UUUUUUUUUU` where UUUUUUUUUU is the UID
+- The default args `--init -t --rm` are _always_ added
+- Environment variables must be passed a single environment variable per line, best achieved with the (`|`) syntax in yaml
+- Only a single command is executed, not a list of commands. Using `;` or `&&` will result in subsequent commands being executed outside of the docker environment
+
+Example:
+
+```yaml
+jobs:
+  test:
+    steps:
+    - name: Run a command in a previously built Docker container
+      uses: ./.github/actions/docker-run
+      with:
+        uid: ${{ steps.build.outputs.unique }}
+        tag: tag-related-to-test-config
+        name: completely-optional-name
+        args: "--more-docker-run-args"
+        env: |
+          FOO=value1
+          BAR=value2
+        command: |
+          mpiexec -n 4 \
+            python \
+              my_complicated_script.py --arg1 -v
+```
+
+## `docker-clean`
+
+Inputs:
+
+- `uid`: Unique identifier output from docker-build action
+- `tag`: Tag of the built image to use
+
+### Notes
+
+- UID must be unique, easily obtained from build action
+- Tag must match built image, easily obtained from build action
+- Use `if: always()` to always clean up the image, even if the workflow fails
+
+Example:
+
+```yaml
+jobs:
+  test:
+    steps:
+    - name: Cleanup Docker image
+      if: always()
+      uses: ./.github/actions/docker-clean
+      with:
+        uid: ${{ steps.build.outputs.unique }}
+        tag: tag-related-to-test-config
+```

.github/workflows/docker-devito.yaml

@@ -178,7 +178,7 @@ jobs:
         run: |
          docker run ${{ matrix.flag }} --rm -t --name "${CONTAINER_NAME}" \
            devitocodes/devito:${{ matrix.tag }}-dev \
-           pytest ${{ matrix.test }}
+           pytest -v ${{ matrix.test }}
 
   deploy-devito-manifest:
     needs: deploy-devito
@@ -292,4 +292,4 @@ jobs:
         run: |
          docker run ${{ matrix.flag }} --rm -t --name "${CONTAINER_NAME}" \
            devitocodes/devito:${{ matrix.tag }}-dev \
-           pytest ${{ matrix.test }}
+           pytest -v ${{ matrix.test }}

.github/workflows/examples-mpi.yaml

@@ -71,15 +71,17 @@ jobs:
         ipcluster start --profile=mpi --engines=mpi -n 4 --daemonize
         # A few seconds to ensure workers are ready
         sleep 10
-        py.test --nbval examples/mpi
+        pytest -v --nbval examples/mpi
         ipcluster stop --profile=mpi
 
     - name: Test seismic examples
       run: |
-        mpirun ${{ matrix.mpiarg }} pytest examples/seismic/tti/tti_example.py
-        mpirun ${{ matrix.mpiarg }} pytest examples/seismic/elastic/elastic_example.py
-        mpirun ${{ matrix.mpiarg }} pytest examples/seismic/viscoacoustic/viscoacoustic_example.py
-        mpirun ${{ matrix.mpiarg }} pytest examples/seismic/viscoelastic/viscoelastic_example.py
+        mpirun ${{ matrix.mpiarg }} \
+          pytest -v \
+            examples/seismic/tti/tti_example.py \
+            examples/seismic/elastic/elastic_example.py \
+            examples/seismic/viscoacoustic/viscoacoustic_example.py \
+            examples/seismic/viscoelastic/viscoelastic_example.py
 
     - name: Test fwi examples with mpi
       run: |

.github/workflows/pytest-core-mpi.yaml

@@ -47,13 +47,22 @@ jobs:
     - name: Test with pytest
       run: |
         python3 scripts/clear_devito_cache.py
-        python3 -m pytest --cov --cov-config=.coveragerc --cov-report=xml -m parallel tests/
+        python3 -m pytest \
+          -v \
+          --cov \
+          --cov-config=.coveragerc \
+          --cov-report=xml \
+          -m parallel \
+          tests/
 
     - name: Test examples with MPI
       run: |
         python3 scripts/clear_devito_cache.py
-        DEVITO_MPI=1 mpirun -n 2 python3 -m pytest examples/seismic/acoustic
-        DEVITO_MPI=1 mpirun -n 2 python3 -m pytest examples/seismic/tti
+        DEVITO_MPI=1 mpirun -n 2 \
+          python3 -m pytest \
+            -v \
+            examples/seismic/acoustic \
+            examples/seismic/tti
 
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v5
@@ -104,27 +113,28 @@ jobs:
         env: |
           CODECOV_TOKEN=${{ secrets.CODECOV_TOKEN }}
           OMP_NUM_THREADS=1
-        command: "pytest tests/test_mpi.py"
-
-    - name: Test acoustic example with MPI
-      uses: ./.github/actions/docker-run
-      with:
-        uid: ${{ steps.build.outputs.unique }}
-        tag: ${{ matrix.name }}
-        env: |
-          DEVITO_MPI=1
-          OMP_NUM_THREADS=1
-        command: "mpiexec -n 2 pytest examples/seismic/acoustic"
-
-    - name: Test tti example with MPI
+        command: |
+          pytest \
+            -v \
+            --cov \
+            --cov-config=.coveragerc \
+            --cov-report=xml \
+            tests/test_mpi.py
+
+    - name: Test acoustic and TTI examples with MPI
       uses: ./.github/actions/docker-run
       with:
         uid: ${{ steps.build.outputs.unique }}
         tag: ${{ matrix.name }}
         env: |
           DEVITO_MPI=1
           OMP_NUM_THREADS=1
-        command: "mpiexec -n 2 pytest examples/seismic/tti"
+        command: |
+          mpiexec -n 2 \
+            pytest \
+              -v \
+              examples/seismic/acoustic \
+              examples/seismic/tti
 
     - name: Cleanup docker image
       if: always()

.github/workflows/pytest-core-nompi.yaml

@@ -161,6 +161,7 @@ jobs:
     - name: Test with pytest
       run: |
         pytest \
+          -v \
           -k "${{ matrix.test-set }}" \
           -m "not parallel" \
           --cov \
@@ -235,25 +236,6 @@ jobs:
         tag: ${{ matrix.name }}
         base: devitocodes/bases:cpu-${{ matrix.arch }}
 
-    - name: Get the Docker image Python version
-      uses: ./.github/actions/docker-run
-      with:
-        uid: ${{ steps.build.outputs.unique }}
-        tag: ${{ matrix.name }}
-        command: >
-          python3 --version | grep "Python " | cut -d' ' -f2 | cut -d'.' -f1,2 > dockerpythonversion.txt
-
-    - name: Check Docker image Python version
-      run: |
-        declared_pyver="${{ matrix.python-version }}"
-        actual_pyver=$(cat dockerpythonversion.txt)
-        echo "Declared Python version: $declared_pyver"
-        echo "Actual Python version: $actual_pyver"
-        if [ "$declared_pyver" != "$actual_pyver" ]; then
-          echo "Python version mismatch: declared $declared_pyver, image has $actual_pyver"
-          exit 1
-        fi
-
     - name: Test with pytest
       uses: ./.github/actions/docker-run
       with:
@@ -263,6 +245,7 @@ jobs:
           CODECOV_TOKEN=${{ secrets.CODECOV_TOKEN }}
         command: |
           pytest \
+            -v \
             -k "${{ matrix.test-set }}" \
             -m "not parallel" \
             --cov \

.github/workflows/pytest-gpu.yaml

@@ -115,8 +115,10 @@ jobs:
         uid: ${{ steps.build.outputs.unique }}
         tag: ${{ matrix.name }}
         args: ${{ matrix.dockerflags }}
-        env: |
-        command: pytest ${{ matrix.test_examples }}
+        command: |
+          pytest \
+            -v \
+            ${{ matrix.test_examples }}
 
     - name: Test examples with MPI
       uses: ./.github/actions/docker-run
@@ -125,9 +127,14 @@ jobs:
         tag: ${{ matrix.name }}
         args: ${{ matrix.dockerflags }}
         env: |
+          CI=true
           DEVITO_LOGGING=DEBUG
           DEVITO_MPI=1
-        command: mpiexec -n 2 pytest ${{ matrix.test_examples }}
+        command: |
+          mpiexec -n 2 \
+            pytest \
+              -v \
+              ${{ matrix.test_examples }}
 
     - name: Cleanup docker image
       if: always()