Run each example in one CI job

.github/workflows/docs.yml

@@ -10,27 +10,71 @@ on:
     - cron: '0 8 * * 1' # run every Monday at 8am UTC
 
 jobs:
+  generate-example:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        example-name: [lode_linear, roy_gch, sample_selection, gaas_map, cp2k_run_batch]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: setup rust
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+
+      - name: setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: install tox
+        run: python -m pip install tox
+
+      - name: install cp2k
+        if: matrix.example-name == 'cp2k_run_batch'
+        run: sudo apt-get install -y cp2k
+
+      - name: build example
+        run: tox -e ${{ matrix.example-name }}
+
+      - name: store example as a github artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: example-${{ matrix.example-name }}
+          path: docs/src/examples/*  # folders for each example will be merged later
+          overwrite: true  # only keep the latest version of the example
+
   build-and-publish:
+    needs: generate-example
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: setup rust
         uses: actions-rs/toolchain@v1
         with:
           profile: minimal
           toolchain: stable
       - name: setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
-      - name: install dependencies
-        run: |
-          sudo apt-get install -y cp2k
-          python -m pip install tox
+          python-version: "3.12"
+
+      - name: install tox
+        run: python -m pip install tox
+
+      - name: load github artifact for each example
+        uses: actions/download-artifact@v4
+        with:
+          path: docs/src/examples
+          pattern: example-*
+          merge-multiple: true
+
       - name: build documentation
-        run: tox -e docs
+        run: tox -e build_docs
 
-      - name: store documentation as github artifacts
+      - name: store documentation as github artifact to be downloaded by users
         uses: actions/upload-artifact@v4
         with:
           name: documentation

.github/workflows/lint.yml

@@ -14,12 +14,14 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
-        python-version: "3.10"
-    - run: pip install tox
+        python-version: "3.12"
 
-    - name: Test Lint
+    - name: install dependencies
+      run: pip install tox
+
+    - name: test lint
       run: tox -e lint

examples/cp2k_run_batch/environement.yml → examples/cp2k_run_batch/environment.yml

@@ -4,3 +4,4 @@ dependencies:
   - pip
   - pip:
     - ase
+    - matplotlib

examples/gaas_map/environement.yml → examples/gaas_map/environment.yml

@@ -5,7 +5,8 @@ dependencies:
   - pip:
     - ase
     - chemiscope
-    - skmatter
-    - scikit-learn
+    - matplotlib
     - metatensor
+    - skmatter
     - rascaline @ git+https://github.com/Luthaf/rascaline@ca957642f512e141c7570e987aadc05c7ac71983
+    - scikit-learn

examples/lode_linear/environement.yml → examples/lode_linear/environment.yml

@@ -4,6 +4,7 @@ dependencies:
   - pip
   - pip:
     - ase
-    - metatensor
     - equisolve @ git+https://github.com/lab-cosmo/equisolve.git@c858bedef4b2799eb445e4c92535ee387224089a
+    - matplotlib
+    - metatensor
     - rascaline @ git+https://github.com/Luthaf/rascaline@ca957642f512e141c7570e987aadc05c7ac71983

examples/lode_linear/lode_tutorial.py

@@ -36,9 +36,10 @@
 # certain direction in the subsequent structures.
 #
 # For speeding up the calculations we already selected the first 130
-# structures of the charge-charge structures.
+# :download:`structures <charge-charge.xyz>` of the charge-charge molecule
+# pairs.
 
-frames = ase.io.read("dataset/charge-charge.xyz", ":")
+frames = ase.io.read("charge-charge.xyz", ":")
 
 
 # %%

examples/roy_gch/environement.yml → examples/roy_gch/environment.yml

@@ -5,6 +5,7 @@ dependencies:
   - pip:
     - ase
     - chemiscope
-    - skmatter
+    - matplotlib
     - metatensor
     - rascaline @ git+https://github.com/Luthaf/rascaline@ca957642f512e141c7570e987aadc05c7ac71983
+    - skmatter

examples/sample_selection/environement.yml → examples/sample_selection/environment.yml

@@ -5,6 +5,7 @@ dependencies:
   - pip:
     - ase
     - chemiscope
+    - matplotlib
     - skmatter
     - metatensor
     - rascaline @ git+https://github.com/Luthaf/rascaline@ca957642f512e141c7570e987aadc05c7ac71983

examples/sample_selection/sample_selection.py

@@ -31,9 +31,9 @@
 # Load 500 example BTO structures from file, reading them using
 # `ASE <https://wiki.fysik.dtu.dk/ase/>`_.
 
-# Load a subset of structures of the example dataset
+# Load a subset of :download:`structures <input-fps.xyz>` of the example dataset
 n_frames = 500
-frames = ase.io.read("./dataset/input-fps.xyz", f":{n_frames}", format="extxyz")
+frames = ase.io.read("input-fps.xyz", f":{n_frames}", format="extxyz")
 
 # %%
 # Compute SOAP descriptors using rascaline

tox.ini

@@ -13,9 +13,9 @@ lint_folders =
     "{toxinidir}/examples"
 
 install_conda_env =
-    conda env update --file examples/{envname}/environement.yml --prefix {envdir}/conda --verbose
+    conda env update --file examples/{envname}/environment.yml --prefix {envdir}/conda --verbose
     # install sphinx-gallery and its dependencies
-    {envdir}/conda/bin/python -m pip install sphinx-gallery sphinx pillow matplotlib
+    {envdir}/conda/bin/python -m pip install sphinx-gallery sphinx pillow
 
 generate_gallery =
     {envdir}/conda/bin/python generate-gallery.py examples/{envname}
@@ -26,15 +26,8 @@ allowlist_externals =
     conda
     {envdir}/conda/bin/python
 
-commands =
-    # error if the user gives a wrong testenv name in `tox -e`
-    python -c "import sys; print('environement {env_name} does not exist'); sys.exit(1)"
-
-
 [testenv:docs]
-deps =
-    -r docs/requirements.txt
-
+description = Run all examples and build the documentation
 allowlist_externals = tox
 commands =
     # transform all examples to rst
@@ -44,35 +37,47 @@ commands =
     tox -e gaas_map
     tox -e cp2k_run_batch
 
-    sphinx-build {posargs:-E} -W -b html docs/src docs/build/html
+    # Build the documentation
+    tox -e build_docs
+
+[testenv:build_docs]
+description = Build the documentation (examples must be generated before)
+deps = -r docs/requirements.txt
+commands = sphinx-build {posargs:-E} -W -b html docs/src docs/build/html
 
 
 [testenv:lode_linear]
+description = Build the `lode_linear` example
 commands =
     {[testenv]install_conda_env}
     {[testenv]generate_gallery}
 
 [testenv:roy_gch]
+description = Build the `roy_gch` example
 commands =
     {[testenv]install_conda_env}
     {[testenv]generate_gallery}
 
 [testenv:gaas_map]
+description = Build the `gaas_map` example
 commands =
     {[testenv]install_conda_env}
     {[testenv]generate_gallery}
 
 [testenv:sample_selection]
+description = Build the `sample_selection` example
 commands =
     {[testenv]install_conda_env}
     {[testenv]generate_gallery}
 
 [testenv:cp2k_run_batch]
+description = Build the `cp2k_run_batch` example
 commands =
     {[testenv]install_conda_env}
     {[testenv]generate_gallery}
 
 [testenv:lint]
+description = Run linters and type checks
 deps =
     black
     blackdoc
@@ -92,8 +97,7 @@ commands =
 
 
 [testenv:format]
-# Abuse tox to do actual formatting. Users can call `tox -e format` to run
-# formatting on all files
+description = Abuse tox to do actual formatting on all files.
 deps =
     black
     blackdoc