Migrate to pixi for development and Jupyter Book V2

.gitattributes

@@ -0,0 +1,2 @@
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true

.github/scripts/inject_matomo.py

@@ -0,0 +1,35 @@
+"""Inject the Matomo analytics snippet into every built HTML page.
+
+The MyST book-theme has no option for custom scripts, so the snippet in
+book/static/js/matomo.html is inserted before </head> after `myst build --html`.
+Safe to run twice: pages already containing the snippet are skipped.
+
+Usage: python inject_matomo.py <html_dir> [snippet_file]
+"""
+
+import sys
+from pathlib import Path
+
+MARKER = "<!-- Matomo -->"
+
+
+def main():
+    html_dir = Path(sys.argv[1])
+    snippet_file = (
+        Path(sys.argv[2])
+        if len(sys.argv) > 2
+        else Path(__file__).parents[2] / "book" / "static" / "js" / "matomo.html"
+    )
+    snippet = snippet_file.read_text(encoding="utf-8")
+    injected = 0
+    for page in sorted(html_dir.rglob("*.html")):
+        html = page.read_text(encoding="utf-8")
+        if MARKER in html or "</head>" not in html:
+            continue
+        page.write_text(html.replace("</head>", snippet + "</head>", 1), encoding="utf-8")
+        injected += 1
+    print(f"Injected Matomo snippet into {injected} pages under {html_dir}")
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/deploy.yml

@@ -5,32 +5,47 @@ on:
   push:
     branches:
     - main
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
 
 # This job installs dependencies, builds the book, and pushes it to `gh-pages`
 jobs:
   deploy-book:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write  # required to push to the gh-pages branch
     steps:
-    - uses: actions/checkout@v3
+      - name: checkout
+        uses: actions/checkout@v6
+        with: { submodules: recursive }
+      - uses: prefix-dev/setup-pixi@v0.9.3
+        with: { pixi-version: v0.72.0 }
+      - name: Build the book
+        run: |
+          cd book
+          pixi run -e dev jupyter-book build
 
-    # Install dependencies
-    - name: Set up Python 3.11
-      uses: actions/setup-python@v4
-      with:
-        python-version: 3.11
+      # The MyST book-theme has no custom-script option, so add Matomo after the build
+      - name: Inject Matomo analytics
+        run: python3 .github/scripts/inject_matomo.py book/_build/html
 
-    - name: Install dependencies
-      run: |
-        pip install -r requirements.txt
+      # Push the book's HTML to github-pages (only on pushes to main;
+      # pull requests just build as a check — their token is read-only)
+      - name: GitHub Pages action
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: book/_build/html
 
-    # Build the book
-    - name: Build the book
-      run: |
-        jupyter-book build book
-
-    # Push the book's HTML to github-pages
-    - name: GitHub Pages action
-      uses: peaceiris/actions-gh-pages@v3.9.3
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: book/_build/html
+      # Non-blocking link check: reports dead external links in the step log
+      # (red X on the step) without failing the workflow — some sites block or
+      # rate-limit the checker (ACS 403, PubChem 503, Crossref 429)
+      - name: Check links (non-blocking)
+        continue-on-error: true
+        run: |
+          cd book
+          pixi run -e dev myst build --strict --check-links

.github/workflows/execution-test.yml

@@ -0,0 +1,38 @@
+name: execution-test
+
+# Verifies that all notebooks still execute (external APIs drift over time —
+# e.g. CAS introduced an API-key requirement). Pages with `execute: skip: true`
+# frontmatter are exempt. The deployed site uses the committed notebook outputs;
+# this workflow only tests executability and never publishes anything.
+on:
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1" # weekly on Monday, 06:00 UTC
+
+jobs:
+  execute-notebooks:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write # to open an issue when a scheduled run fails
+    steps:
+      - name: checkout
+        uses: actions/checkout@v6
+        with: { submodules: recursive }
+      - uses: prefix-dev/setup-pixi@v0.9.3
+        with: { pixi-version: v0.72.0 }
+      - name: Execute all notebooks
+        run: |
+          cd book
+          pixi run -e dev myst build --execute --strict
+
+      # External APIs can break outside of any PR; make sure someone notices.
+      - name: Open an issue on scheduled failure
+        if: failure() && github.event_name == 'schedule'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh issue create --repo "$GITHUB_REPOSITORY" \
+            --title "Scheduled notebook execution test failed ($(date -u +%Y-%m-%d))" \
+            --body "The weekly notebook execution test failed — a web service used by a notebook may have changed or gone offline. See the run log: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"

.gitignore

@@ -1,7 +1,27 @@
 .idea
 .DS_Store
-book/_build
 book/manipulations/hiddensettings.py
 book/howtos/inchikeys.md
 book/.DS_Store
+book/nul
 Pipfile.lock
+
+# generated data from tests and builds
+# notebooks write their outputs to a files/generated/ folder (relative to the
+# kernel cwd: the notebook's folder interactively, book/ during myst execution)
+**/files/generated/
+book/_build
+book/manipulations/.excel_import.md.bak
+
+# pixi environments
+.pixi/*
+!.pixi/config.toml
+
+# MyST build outputs
+_build
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# local files
+TODO.md

CONTRIBUTING.md

@@ -2,10 +2,73 @@
 
 We welcome all community contributions to this work, whether it be a minor typo correction or a complex demonstration notebook.  There are a variety of ways you can help improve this resource, including:
 
-# Issues
+## Issues
 
 If you spot something wrong or missing, please let us know through an [issue](https://github.com/IUPAC/WFChemCookbook/issues).  No coding required.  Just drop a line so we can follow up and make sure the resource is even better for the next person who comes along.
 
-# Pull Requests
+## Pull Requests
 
-More advanced practitioners should consider putting together a [pull request](https://github.com/IUPAC/WFChemCookbook/pulls).  Direct contributions are the fastest way to improve this work, whether it be because there's a quick editorial improvement or because we're missing the latest, greatest library.  
+More advanced practitioners should consider putting together a [pull request](https://github.com/IUPAC/WFChemCookbook/pulls).  Direct contributions are the fastest way to improve this work, whether it be because there's a quick editorial improvement or because we're missing the latest, greatest library.
+
+## Installation
+
+This project can be downloaded directly from the repository website or via
+
+```sh .noeval
+git clone git@github.com:IUPAC/WFChemCookbook.git
+```
+
+Install [pixi](https://pixi.prefix.dev/dev/installation/) and install the dependencies via pixi.
+
+```sh .noeval
+pixi install
+```
+
+To explore the cookbook locally run:
+
+```sh .noeval
+pixi run serve
+```
+
+### Further pixi tasks
+
+Add a module:
+
+```sh .noeval
+pixi add <module name>
+```
+
+or
+
+```sh .noeval
+pixi add --pypi <module name>
+```
+
+Install packages
+
+```sh .noeval
+pixi run install
+```
+
+Clean cached packages
+
+```sh .noeval
+pixi run clean
+```
+
+Build the website (without serving) and check for broken links
+
+```sh .noeval
+pixi run build
+```
+
+If nothing works it is sometimes helpful to delete the `pixi.lock` file and clean the `.pixi` folder
+
+The cache of the jupyter book build can be cleared (deletes `book/_build` folder)
+
+TODO:: The build option "should" execute the notebooks and raise errors. This does not seem to work properly.
+In addition the validity of links is checked.
+
+```sh .noeval
+pixi run execute
+```

README.md

@@ -1,4 +1,5 @@
 # IUPAC FAIR Chemistry Cookbook
+
 The IUPAC FAIR Chemistry Cookbook is an open, collaborate, community focused resource on how to work with FAIR data in chemistry.
 FAIR means findable, accessible, interoperable, and reusable and is the new paradigm for how chemists should share their data.
 
@@ -8,10 +9,6 @@ See the [cookbook](https://iupac.github.io/WFChemCookbook/) for a user-friendly,
 
 The contents of this repository are designed to use the [Jupyter Book](https://jupyterbook.org/) framework to generate a simple to navigate and easy to maintain set of reference materials for getting started leveraging common and powerful chemical information tooling.
 
-## Developer instructions
-
-See the [contributing guide](./CONTRIBUTING.md).
-
 ## About this project
 
 The Committee on Data of the International Science Council ([CODATA](https://codata.org/)) and the Research Data Alliance ([RDA](https://rd-alliance.org/)) have recently launched the [WorldFAIR Initiative](https://worldfair-project.eu/) to advance implementation of the [FAIR data principles](https://force11.org/info/the-fair-data-principles/) within and across research domains.
@@ -24,3 +21,27 @@ All presented code should execute as written, and if it does not please [let us
 General purpose software engineering strategies and techniques (_e.g._, Python language semantics, branch management in Git) are out of scope for this reference material, but an effort will be made to reference relevant external materials.
 
 *WorldFAIR “Global cooperation on FAIR data policy and practice” is funded by the EC HORIZON-WIDERA-2021-ERA-01-41 Coordination and Support Action under Grant Agreement No. 101058393.*
+
+## Contributing
+
+See the [contributing guide](./CONTRIBUTING.md) with further information on how to contribute to this project, as wells as installation and development instructions.
+
+## Installation
+
+This project can be downloaded directly from the repository website or via
+
+```sh .noeval
+git clone git@github.com:theoechem/article_MAHE_2024_IL_pitfalls.git
+```
+
+Install [pixi](https://pixi.prefix.dev/dev/installation/) and install the dependencies via pixi.
+
+```sh .noeval
+pixi install
+```
+
+To explore the Jupyter notebooks in `book` interactively use your favorite IDE or start jupyter via:
+
+```sh .noeval
+pixi run jupyter lab
+```

binder/requirements.txt

@@ -0,0 +1,13 @@
+# Environment for Binder (repo2docker) — used when launching the notebooks
+# from the website. repo2docker reads config exclusively from this binder/
+# folder (root config files are ignored while it exists). Not used for
+# building the site; that is done with pixi (see pixi.toml).
+# Keep the jcamp pin in sync with pixi.toml.
+jcamp==1.3.2
+matplotlib==3.10.8
+numpy>=2,<3
+openbabel==3.2.1
+pandas==2.3.3
+rdkit==2025.9.4
+requests>=2
+seaborn==0.13.2