Split add() into dedicated methods for experiment creation (#86)

* Refactor ExperimentFactory and Experiments classes for improved argument handling and creation methods

* Refactor Experiment initialization across tutorials to follow new API

* Refactor functional tests to follow new API

* Refactor unit tests to follow new API

* Remove unused pytest import

* Prevents building font cache info in docs build

* Refines workflow name for clarity

* Renames workflow for clarity and purpose

* Removes Pixi validation workflow. The user specific validation is in another workflow.

* More fixes for the functional tests

* Automates tutorial script conversion and deployment

* Update checkout action to version 5 in GitHub workflows

* Updates release workflow to use enhanced actions

* Enhances checkout action for full history fetching

* Streamlines GitHub Actions YAML syntax

* Removes push and pull_request triggers

* Removes feature branch from CI config

* Adds ID to draft release notes step

* Refines experiment documentation to follow new API

* Adds manual trigger to draft release notes workflow

* Restricts GitHub Actions to master and develop branches

* Simplifies experiment doc headings and clarifications

* Refactors test workflow and adds cron trigger

* Enables GitHub token for tutorial scripts

* Removes branch-specific logic from workflows

* Add tests for ExperimentFactory argument validation

* Bump dependencies

Author: AndrewSazonov

.github/workflows/build-docs.yml

@@ -6,8 +6,7 @@ on:
     # Selected branches
     branches: [master, develop, docs, patch]
     # Runs on creating a new tag starting with 'v', e.g. 'v1.0.3'
-    tags:
-      - 'v*'
+    tags: ['v*']
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -41,7 +40,7 @@ jobs:
 
     steps:
       - name: Check-out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0 # full history + tags. needed to get the latest release version
 
@@ -92,6 +91,12 @@ jobs:
       - name: Convert tutorial scripts to notebooks
         run: pixi run notebook-prepare
 
+      # The following step is needed to avoid the following message during the build:
+      # "Matplotlib is building the font cache; this may take a moment"
+      - name: Pre-build site step
+        run: pixi run python -c "import easydiffraction"
+
+      # Run the notebooks to generate the output cells using multiple cores
       - name: Run notebooks
         run: pixi run notebook-exec
 

.github/workflows/draft-release-notes.yml

@@ -7,6 +7,8 @@ on:
   # Runs on pushes targeting the default branch (updates the real draft release)
   push:
     branches: [master]
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
 
 jobs:
   draft-release-notes:
@@ -17,9 +19,34 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - name: Drafts the next release notes
-        uses: enhantica/drafterino@v1
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # full history with tags to get the version number by drafterino
+
+      - name: Set up pixi
+        uses: prefix-dev/[email protected]
+        with:
+          environments: >-
+            default
+          activate-environment: default
+          run-install: true
+          frozen: true
+          cache: false
+          post-cleanup: false
+
+      - name: Convert tutorial scripts to notebooks
+        run: pixi run notebook-prepare
+
+      - name: Clean up unnecessary script files
+        run: rm -rf tutorials/*.py
 
+      - name: Zip the tutorials directory
+        run: zip -9 -r tutorials.zip tutorials
+
+      - name: Drafts the next release notes
+        id: draft
+        uses: enhantica/drafterino@v2
         with:
           config: |
             title: 'easydiffraction $COMPUTED_VERSION'
@@ -43,3 +70,15 @@ jobs:
 
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create GitHub draft release
+        uses: softprops/action-gh-release@v2
+        with:
+          draft: true
+          tag_name: ${{ steps.draft.outputs.tag_name }}
+          name: ${{ steps.draft.outputs.release_name }}
+          body: ${{ steps.draft.outputs.release_notes }}
+          files: |
+            tutorials.zip
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish-pypi.yml

@@ -6,8 +6,7 @@ name: Publish to PyPI
 on:
   # Runs on creating a new tag starting with 'v', e.g. 'v1.0.3'
   push:
-    tags:
-      - 'v*'
+    tags: ['v*']
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -17,7 +16,7 @@ jobs:
 
     steps:
       - name: Check-out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: '0' # full history with tags to get the version number by versioningit
 

.github/workflows/scan-security.yml

@@ -7,8 +7,7 @@ name: Scan security (static analysis)
 on:
   # Trigger the workflow on pull request
   pull_request:
-    branches:
-      - '**'
+    branches: ['**']
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -20,7 +19,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           # We must fetch at least the immediate parents so that if this is
           # a pull request then we can checkout the head.

.github/workflows/test-code.yaml

@@ -6,7 +6,7 @@
 #    - Check code linting
 #    - Check code formatting
 #    - Check formatting of Markdown, YAML, TOML, etc. files
-# 2. run-tests:
+# 2. test-source:
 #    - Test the code base against the latest code in the repository
 #    - Create the Python package
 #    - Upload the Python package for the next job
@@ -21,16 +21,13 @@ on:
   # Trigger the workflow on push
   push:
     # Every branch
-    branches:
-      - '**'
+    branches: ['**']
     # But do not run this workflow on creating a new tag starting with
     # 'v', e.g. 'v1.0.3' (see publish-pypi.yml)
-    tags-ignore:
-      - 'v*'
+    tags-ignore: ['v*']
   # Trigger the workflow on pull request
   pull_request:
-    branches:
-      - '**'
+    branches: ['**']
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -57,9 +54,21 @@ jobs:
 
     runs-on: ${{ matrix.os }}
 
+    outputs:
+      pytest-marks: ${{ steps.set-mark.outputs.pytest_marks }}
+
     steps:
+      - name: Set mark for functional tests
+        id: set-mark
+        run: |
+          if [[ "${{ env.CI_BRANCH }}" != "master" && "${{ env.CI_BRANCH }}" != "develop" ]]; then
+            echo "pytest_marks=-m 'fast'" >> $GITHUB_OUTPUT
+          else
+            echo "pytest_marks=" >> $GITHUB_OUTPUT
+          fi
+
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up pixi (incl. environments and dependencies)
         uses: prefix-dev/[email protected]
@@ -136,7 +145,7 @@ jobs:
 
   # Job 2: Test code
   # TODO: Add coverage reporting with upload to Codecov?
-  run-tests:
+  test-source:
     needs: code-quality # previous job needs to be finished first
 
     strategy:
@@ -151,7 +160,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: '0' # full history with tags to get the version number by versioningit
 
@@ -172,12 +181,13 @@ jobs:
             pixi run -e $env unit-tests
           done
 
-      - name: Run functional tests
+      - name:
+          Run functional tests ${{ needs.code-quality.outputs.pytest-marks }}
         shell: bash
         run: |
           for env in ${{ env.PIXI_ENVS }}; do
             echo "🔹🔸🔹🔸🔹   Current env: $env   🔹🔸🔹🔸🔹"
-            pixi run -e $env func-tests
+            pixi run -e $env func-tests "${{ needs.code-quality.outputs.pytest-marks }}"
           done
 
       # Delete all local tags when not on a tagged commit to force versioningit
@@ -215,7 +225,7 @@ jobs:
 
   # Job 3: Test the package
   test-package:
-    needs: run-tests # the previous job needs to be finished first
+    needs: test-source # the previous job needs to be finished first
 
     strategy:
       fail-fast: false
@@ -260,18 +270,19 @@ jobs:
             pixi run -e $env easydiffraction version
           done
 
-      - name: Run unit tests (using built package from previous job)
+      - name: Run unit tests
         shell: bash
         run: |
           for env in ${{ env.PIXI_ENVS }}; do
             echo "🔹🔸🔹🔸🔹   Current env: $env   🔹🔸🔹🔸🔹"
             pixi run -e $env unit-tests
           done
 
-      - name: Run functional tests (using built package from previous job)
+      - name:
+          Run functional tests ${{ needs.code-quality.outputs.pytest-marks }}
         shell: bash
         run: |
           for env in ${{ env.PIXI_ENVS }}; do
             echo "🔹🔸🔹🔸🔹   Current env: $env   🔹🔸🔹🔸🔹"
-            pixi run -e $env func-tests
+            pixi run -e $env func-tests "${{ needs.code-quality.outputs.pytest-marks }}"
           done

.github/workflows/test-package-pypi.yaml

@@ -1,4 +1,4 @@
-name: Test unpinned package from PyPI
+name: Test unpinned PyPI package
 
 on:
   # Run daily, at 00:00.
@@ -52,11 +52,13 @@ jobs:
       - name: Run functional tests to verify the installation
         run: pixi run func-tests
 
-      - name: List the available EasyDiffraction tutorials
-        run: pixi run tutorials-list
-
-      - name: Fetch the EasyDiffraction tutorials
-        run: pixi run tutorials-fetch
+      # Github token to avoid hitting the unauthenticated API rate limit
+      - name: List and fetch the EasyDiffraction tutorials
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          pixi run tutorials-list
+          pixi run tutorials-fetch
 
       - name: Test tutorials as notebooks
         run: pixi run notebook-tests

.github/workflows/test-tutorials-colab.yaml

@@ -1,18 +1,6 @@
 name: Test tutorials on Colab
 
 on:
-  # Trigger the workflow on push
-  #push:
-  #  # Every branch
-  #  branches:
-  #    - '**'
-  #  # But do not run this workflow on creating a new tag starting with 'v', e.g. 'v1.0.3' (see publish-pypi.yml)
-  #  tags-ignore:
-  #    - 'v*'
-  # Trigger the workflow on pull request
-  #pull_request:
-  #  branches:
-  #    - '**'
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -37,7 +25,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5

.github/workflows/test-tutorials.yaml

@@ -3,17 +3,11 @@ name: Test tutorials
 on:
   # Trigger the workflow on push
   push:
-    # Every branch
-    branches:
-      - '**'
-    # But do not run this workflow on creating a new tag starting with
-    # 'v', e.g. 'v1.0.3' (see publish-pypi.yml)
-    tags-ignore:
-      - 'v*'
+    # Selected branches
+    branches: [master, develop]
   # Trigger the workflow on pull request
   pull_request:
-    branches:
-      - '**'
+    branches: ['**']
   # Trigger the workflow on workflow_call (to be called from other workflows)
   # Needed, as standard schedule triggers the master branch only, but we want
   # to run this workflow on develop branch.
@@ -39,7 +33,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up pixi
         uses: prefix-dev/[email protected]
@@ -82,7 +76,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up pixi
         uses: prefix-dev/[email protected]

.github/workflows/trigger-test-code.yaml

@@ -0,0 +1,30 @@
+name: Trigger scheduled test code
+
+on:
+  # Run daily, at 00:00.
+  schedule:
+    - cron: '0 0 * * *'
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  trigger-test-tutorials:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout develop branch
+        uses: actions/checkout@v5
+        with:
+          ref: develop
+
+      - name: Trigger test-tutorials workflow
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            await github.rest.actions.createWorkflowDispatch({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: "test-code.yaml",
+              ref: "develop"
+            });

.github/workflows/test-tutorials-nightly.yaml renamed to .github/workflows/trigger-test-tutorials.yaml

@@ -1,4 +1,4 @@
-name: Test tutorials nightly (develop)
+name: Trigger scheduled test tutorials
 
 on:
   # Run daily, at 00:00.
@@ -8,12 +8,12 @@ on:
   workflow_dispatch:
 
 jobs:
-  call-tutorials:
+  trigger-test-tutorials:
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout develop branch
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           ref: develop