New release

.github/workflows/build-docs.yml

@@ -4,7 +4,7 @@ on:
   # Trigger the workflow on push
   push:
     # Selected branches
-    branches: [develop, master, docs, patch]
+    branches: [master, develop, docs, patch]
     # Runs on creating a new tag starting with 'v', e.g. 'v1.0.3'
     tags:
       - 'v*'
@@ -18,20 +18,24 @@ concurrency:
     ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
+# Set the environment variables to be used in all jobs defined in this workflow
 env:
-  # Set the environment variables to be used in all jobs defined in this workflow
-  # Set the CI_BRANCH environment variable to be the branch name
-  # Set the NOTEBOOKS_DIR environment variable to be the directory containing the Jupyter notebooks
+  # CI_BRANCH - the branch name (used in mkdocs.yml)
+  # GITHUB_REPOSITORY - the repository name (used in mkdocs.yml)
+  # NOTEBOOKS_DIR - the directory containing the Jupyter notebooks (used in mkdocs.yml)
   CI_BRANCH: ${{ github.head_ref || github.ref_name }}
+  GITHUB_REPOSITORY: ${{ github.repository }}
   NOTEBOOKS_DIR: tutorials
+  DEV_DEPLOYMENT_URL:
+    https://easyscience.github.io/${{ github.event.repository.name }}
+  PROD_DEPLOYMENT_URL: https://docs.easydiffraction.org/lib
 
 jobs:
   # Job 1: Build the static files for the documentation site
   build-docs:
     strategy:
       matrix:
         os: [macos-14] # Use macOS to switch to dark mode for Plotly charts
-        python-version: ['3.13']
 
     runs-on: ${{ matrix.os }}
 
@@ -49,10 +53,6 @@ jobs:
           git fetch --tags --force
           echo "RELEASE_VERSION=$(git describe --tags --abbrev=0)" >> "$GITHUB_ENV"
 
-      # Without this step, GITHUB_REPOSITORY is not accessible from mkdocs.yml
-      - name: Set GITHUB_REPOSITORY env variable
-        run: echo "GITHUB_REPOSITORY=$GITHUB_REPOSITORY" >> "$GITHUB_ENV"
-
       # Activate dark mode to create documentation with Plotly charts in dark mode
       # Need a better solution to automatically switch the chart colour theme based on the mkdocs material switcher
       # Something similar to mkdocs_plotly_plugin https://haoda-li.github.io/mkdocs-plotly-plugin/,
@@ -64,85 +64,52 @@ jobs:
       #    dark-mode on
       #    dark-mode status
 
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+      - name: Set up pixi
+        uses: prefix-dev/setup-pixi@v0.9.0
         with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Upgrade package installer for Python
-        shell: bash
-        run: python -m pip install --upgrade pip
+          environments: >-
+            py313-docs
+          activate-environment: py313-docs
+          run-install: true
+          frozen: true
+          cache: false
+          post-cleanup: false
 
-      # Install EasyDiffraction Library to run Jupyter notebooks
-      # Install with the 'docs' and 'visualization' extras
-      - name: Install EasyDiffraction Library and its dependencies
-        run: python -m pip install .'[dev,docs,visualization]'
-
-      # Clone assets extra from:
-      # - easyscience/assets-docs
-      # - easyscience/assets-branding
       - name: Clone easyscience/assets-docs and easyscience/assets-branding
         run: |
           cd ..
           git clone https://github.com/easyscience/assets-docs.git
           git clone https://github.com/easyscience/assets-branding.git
 
-      # Add the extra files from the easyscience/assets-docs repository
-      - name: Add files from easyscience/assets-docs files
-        run: |
-          cp -R ../assets-docs/docs/assets/ docs/assets/
-          cp -R ../assets-docs/includes/ includes/
-          cp -R ../assets-docs/overrides/ overrides/
-
-      # Add the extra files from the easyscience/assets-branding repository
-      - name: Add files from easyscience/assets-branding files
-        run: |
-          mkdir -p docs/assets/images/
-          cp ../assets-branding/easydiffraction/hero/dark.png docs/assets/images/hero_dark.png
-          cp ../assets-branding/easydiffraction/hero/light.png docs/assets/images/hero_light.png
-          cp ../assets-branding/easydiffraction/logos/dark.svg docs/assets/images/logo_dark.svg
-          cp ../assets-branding/easydiffraction/logos/light.svg docs/assets/images/logo_light.svg
-          cp ../assets-branding/easydiffraction/icons/color.png docs/assets/images/favicon.png
-          mkdir -p overrides/.icons/
-          cp ../assets-branding/easydiffraction/icons/bw.svg overrides/.icons/easydiffraction.svg
-          cp ../assets-branding/easyscience-org/icons/eso-icon_bw.svg overrides/.icons/easyscience.svg
+      - name: Add files from cloned repositories
+        run: pixi run docs-assets
 
       # Convert python scripts in the notebooks directory to Jupyter notebooks
-      # Strip output from the notebooks, simpify cell ids and replace '# !pip' with '!pip'
-      # The notebooks are used to generate the documentation
-      - name:
-          Convert ${{ env.NOTEBOOKS_DIR }}/*.py to docs/${{env.NOTEBOOKS_DIR
-          }}/*.ipynb
-        run: |
-          cp -R ${{ env.NOTEBOOKS_DIR }}/data docs/${{ env.NOTEBOOKS_DIR }}/
-          jupytext ${{ env.NOTEBOOKS_DIR }}/*.py --from py:percent --to ipynb
-          nbstripout ${{ env.NOTEBOOKS_DIR }}/*.ipynb
-          python tools/prepare_notebooks.py ${{ env.NOTEBOOKS_DIR }}/
-          mv ${{ env.NOTEBOOKS_DIR }}/*.ipynb docs/${{ env.NOTEBOOKS_DIR }}/
-
-      # 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: |
-          export PYTHONPATH="$(pwd)/src${PYTHONPATH:+:$PYTHONPATH}"
-          python -c "import easydiffraction"
+      # Strip output from the notebooks
+      # Prepare the notebooks for documentation (add colab cell, etc.)
+      # Run the notebooks to generate the output cells using multiple cores
+      # The notebooks are then used to build the documentation site
+      - name: Convert tutorial scripts to notebooks
+        run: pixi run notebook-prepare
+
+      - name: Run notebooks
+        run: pixi run notebook-exec
+
+      - name: Move notebooks to docs/tutorials
+        run: pixi run docs-notebooks
 
       # Create the mkdocs.yml configuration file
       # The file is created by merging two files:
       # - assets-docs/mkdocs.yml - the common configuration (theme, plugins, etc.)
       # - docs/mkdocs.yml - the project-specific configuration (project name, TOC, etc.)
       - name: Create mkdocs.yml file
-        run: python tools/create_mkdocs-yml.py
+        run: pixi run docs-config
 
       # Build the static files
       # Input: docs/ directory containing the Markdown files
       # Output: site/ directory containing the generated HTML files
       - name: Build site with MkDocs
-        run: |
-          export JUPYTER_PLATFORM_DIRS=1
-          export PYTHONWARNINGS="ignore::RuntimeWarning"
-          export PYTHONPATH="$(pwd)/src${PYTHONPATH:+:$PYTHONPATH}"
-          mkdocs build
+        run: pixi run docs-build
 
       # Set up the Pages action to configure the static files to be deployed
       # NOTE: The repository must have GitHub Pages enabled and configured to build using GitHub Actions
@@ -155,17 +122,15 @@ jobs:
       # This artifact is named github-pages and is a single gzip archive containing a single tar file
       # The artifact is then used in the next job by actions/deploy-pages to deploy the static files to GitHub Pages
       # Unfortunately, the artifact is not available for download, so extra steps below are needed to do similar things
-      - name:
-          Upload built site as artifact for easyscience.github.io/${{
-          github.event.repository.name }} (all branches)
+      - name: Upload built site as artifact for DEV deployment (all branches)
         uses: actions/upload-pages-artifact@v3
         with:
           path: site/
 
       # Upload the static files from the site/ directory to be used in the next job
       # This artifact is only uploaded on tagged releases (tags starting with 'v', e.g., v1.0.3)
       # and is used to push content to gh_pages for custom domain deployment.
-      - name: Upload built site as artifact for gh_pages (tagged release)
+      - name: Upload built site as artifact for PROD deployment (tagged release)
         if: startsWith(github.ref, 'refs/tags/v')
         uses: actions/upload-artifact@v4
         with:
@@ -203,11 +168,14 @@ jobs:
       # restrictions on the branch name need to be set for desired branches on
       # https://github.com/easyscience/diffraction-lib/settings/environments
       # Deployed pages are available at https://easyscience.github.io/diffraction-lib
-      - name:
-          Deploy to easyscience.github.io/${{ github.event.repository.name }}
-          (all branches)
+      - name: DEV deployment (all branches)
         uses: actions/deploy-pages@v4
 
+      - name: Show DEV deployment url (all branches)
+        run:
+          echo "🔗 DEV deployment url [${{ env.DEV_DEPLOYMENT_URL }}](${{
+          env.DEV_DEPLOYMENT_URL }})" >> $GITHUB_STEP_SUMMARY
+
       # Download built site as artifact from a previous job for gh_pages (tagged release)
       # This artifact is only downloaded on tagged releases (tags starting with 'v', e.g., v1.0.3)
       # and is used to push content to gh_pages for custom domain deployment.
@@ -228,13 +196,17 @@ jobs:
       # Then the gh_pages branch is used to deploy the site to the custom domain.
       # Deploying is done with a webhook added via:
       # https://github.com/easyscience/diffraction-lib/settings/hooks
-      - name:
-          Deploy to gh_pages branch to trigger deployment to custom domain
-          (tagged release)
+      - name: PROD deployment to gh_pages for custom domain (tagged release)
         if: startsWith(github.ref, 'refs/tags/v')
         uses: s0/git-publish-subdir-action@develop
         env:
           GITHUB_TOKEN: ${{ secrets.GH_API_PERSONAL_ACCSESS_TOKEN }}
           REPO: self
           BRANCH: gh_pages
           FOLDER: site
+
+      - name: Show PROD deployment url (tagged release)
+        if: startsWith(github.ref, 'refs/tags/v')
+        run:
+          echo "🔗 PROD deployment url [${{ env.PROD_DEPLOYMENT_URL }}](${{
+          env.PROD_DEPLOYMENT_URL }})" >> $GITHUB_STEP_SUMMARY

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

@@ -6,9 +6,7 @@ name: Update release draft
 on:
   # Runs on pushes targeting the default branch (updates the real draft release)
   push:
-    branches:
-      - main
-      - master
+    branches: [master]
 
 jobs:
   draft-release-notes:

.github/workflows/publish-pypi.yml

@@ -29,7 +29,7 @@ jobs:
       - name: Upgrade package installer for Python
         run: pip install --upgrade pip
 
-      - name: Install build frontend
+      - name: Install build tool
         run: pip install --upgrade build
 
       - name: Create Python package