📚 tutorials: fetch include/ helpers if not present

Readers who copy-paste cells into their own notebook, rather than
cloning the repo, had no include/ folder, so setup_tutorial.py,
input.yaml and the shared task/workflow modules were missing and every
notebook failed on its first include/ reference.

Each module's setup cell now downloads setup_tutorial.py when it is
absent; setup_tutorial.py then fetches the remaining include/ files via
the GitHub contents API. Both checks are guarded, so a repo clone and
the docs build make no network call. Module 0, which has no setup cell,
fetches its two example inputs directly.

The source ref is pinned to the PR branch for now (TODO in
setup_tutorial.py); switch it to the release tag on merge.

Author: GeigerJ2

docs/source/tutorials/include/setup_tutorial.py

@@ -25,11 +25,13 @@
 """
 
 import hashlib
+import json
 import os
 import pathlib
 import shutil
 import sys
 import time
+import urllib.request
 from contextlib import suppress
 
 from aiida import load_profile
@@ -41,6 +43,29 @@
 from aiida.manage.configuration import create_profile, get_config
 from aiida.orm import Computer, InstalledCode, load_code, load_computer
 
+
+def _ensure_tutorial_helpers() -> None:
+    """Fetch any missing tutorial helper files into ``include/``.
+
+    Lets a notebook running outside the tutorial repository (for example, cells
+    pasted into your own notebook) import the shared helpers. No-op when they
+    are already present, as in a repo clone or the docs build.
+    """
+    include_dir = pathlib.Path('include')
+    if all((include_dir / name).exists() for name in ('workflows.py', 'tasks.py', 'input.yaml')):
+        return
+    # TODO: switch to 'aiidateam/aiida-core' at the release tag once PR #7205 merges.
+    repo, ref = 'GeigerJ2/aiida-core', 'docs/integrate-tutorials'
+    api = f'https://api.github.com/repos/{repo}/contents/docs/source/tutorials/include?ref={ref}'
+    include_dir.mkdir(exist_ok=True)
+    for entry in json.loads(urllib.request.urlopen(api).read()):
+        if entry['type'] == 'file' and not (include_dir / entry['name']).exists():
+            urllib.request.urlretrieve(entry['download_url'], include_dir / entry['name'])
+
+
+_ensure_tutorial_helpers()
+
+
 # Derive a short suffix from the mtimes of all setup scripts: stable across
 # all modules in one build, but bumped whenever any setup logic changes,
 # so stale profiles from older builds don't get reused.

docs/source/tutorials/module0.md

@@ -85,6 +85,16 @@ seed: 42         # RNG seed for the initial perturbation
 ```{code-cell} ipython3
 # In a Jupyter notebook, a line starting with `!` runs a shell command.
 # Make a scratch directory to work in and copy the example input into it.
+# (Outside the tutorial repo, first fetch the example inputs into include/.)
+from pathlib import Path
+import urllib.request
+
+_base = 'https://raw.githubusercontent.com/GeigerJ2/aiida-core/docs/integrate-tutorials/docs/source/tutorials/include'
+Path('include').mkdir(exist_ok=True)
+for _name in ('input.yaml', 'input_bad.yaml'):
+    if not (Path('include') / _name).exists():
+        urllib.request.urlretrieve(f'{_base}/{_name}', Path('include') / _name)
+
 !mkdir -p /tmp/aiida-tutorial
 !cp include/input.yaml /tmp/aiida-tutorial/input.yaml
 ```

docs/source/tutorials/module1.md

@@ -64,22 +64,32 @@ It sets up a lightweight local profile with sensible defaults for all three: SQL
 For more advanced high-throughput production setups, see the {ref}`installation guide <installation>`.
 
 This tutorial, though, runs in its own **isolated sandbox profile**, kept separate from any profile you already have, so the data you create here never mixes with your real work and every module reproduces exactly.
-Run the cell below to create it (later modules load the same one):
+
+The cell below creates that profile and loads AiiDA's `%verdi` Jupyter magic.
+If you are running outside the tutorial repository (for example, cells pasted into your own notebook), it first downloads `setup_tutorial.py`, which in turn fetches the other `include/` helpers it needs; inside the repo, as in these rendered docs, that step is skipped.
+Every module runs this same cell, so the data you create now is still available in later modules:
 
 ```{code-cell} ipython3
-# Create (or load) the tutorial's isolated sandbox profile. It stays separate
-# from any AiiDA profile you already have, so nothing here touches your real
-# work. Every module loads this same profile, so data you create now is still
-# there in later modules.
-# `%load_ext aiida` enables the `%verdi` magic used throughout the tutorial.
-#
-# Prefer to use your own existing profile? Replace the `%run` line with:
-#     from aiida import load_profile
-#     load_profile()
+# Set up the tutorial's isolated sandbox profile.
+from pathlib import Path
+
+if not Path('include/setup_tutorial.py').exists():
+    import urllib.request
+
+    Path('include').mkdir(exist_ok=True)
+    urllib.request.urlretrieve(
+        'https://raw.githubusercontent.com/GeigerJ2/aiida-core/docs/integrate-tutorials/docs/source/tutorials/include/setup_tutorial.py',
+        'include/setup_tutorial.py',
+    )
+
 %load_ext aiida
 %run -i include/setup_tutorial.py
 ```
 
+:::{tip}
+Prefer to use an AiiDA profile you already have? Replace the `%run` line with `from aiida import load_profile` followed by `load_profile()`.
+:::
+
 You can verify that the profile is set up correctly with `verdi status`:
 
 ```{code-cell} ipython3

docs/source/tutorials/module2.md

@@ -55,6 +55,17 @@ uv pip install aiida-core aiida-shell
 
 ```{code-cell} ipython3
 # Set up the tutorial's isolated sandbox profile (see Module 1 for details).
+from pathlib import Path
+
+if not Path('include/setup_tutorial.py').exists():
+    import urllib.request
+
+    Path('include').mkdir(exist_ok=True)
+    urllib.request.urlretrieve(
+        'https://raw.githubusercontent.com/GeigerJ2/aiida-core/docs/integrate-tutorials/docs/source/tutorials/include/setup_tutorial.py',
+        'include/setup_tutorial.py',
+    )
+
 %load_ext aiida
 %run -i include/setup_tutorial.py
 ```

docs/source/tutorials/module3a.md

@@ -59,6 +59,17 @@ uv pip install aiida-core aiida-shell aiida-workgraph
 
 ```{code-cell} ipython3
 # Set up the tutorial's isolated sandbox profile (see Module 1 for details).
+from pathlib import Path
+
+if not Path('include/setup_tutorial.py').exists():
+    import urllib.request
+
+    Path('include').mkdir(exist_ok=True)
+    urllib.request.urlretrieve(
+        'https://raw.githubusercontent.com/GeigerJ2/aiida-core/docs/integrate-tutorials/docs/source/tutorials/include/setup_tutorial.py',
+        'include/setup_tutorial.py',
+    )
+
 %load_ext aiida
 %run -i include/setup_tutorial.py
 ```

docs/source/tutorials/module3b.md

@@ -47,6 +47,17 @@ uv pip install aiida-core aiida-shell aiida-workgraph
 
 ```{code-cell} ipython3
 # Set up the tutorial's isolated sandbox profile (see Module 1 for details).
+from pathlib import Path
+
+if not Path('include/setup_tutorial.py').exists():
+    import urllib.request
+
+    Path('include').mkdir(exist_ok=True)
+    urllib.request.urlretrieve(
+        'https://raw.githubusercontent.com/GeigerJ2/aiida-core/docs/integrate-tutorials/docs/source/tutorials/include/setup_tutorial.py',
+        'include/setup_tutorial.py',
+    )
+
 %load_ext aiida
 %run -i include/setup_tutorial.py
 ```

docs/source/tutorials/module4.md

@@ -55,6 +55,17 @@ uv pip install aiida-core aiida-shell
 
 ```{code-cell} ipython3
 # Set up the tutorial's isolated sandbox profile (see Module 1 for details).
+from pathlib import Path
+
+if not Path('include/setup_tutorial.py').exists():
+    import urllib.request
+
+    Path('include').mkdir(exist_ok=True)
+    urllib.request.urlretrieve(
+        'https://raw.githubusercontent.com/GeigerJ2/aiida-core/docs/integrate-tutorials/docs/source/tutorials/include/setup_tutorial.py',
+        'include/setup_tutorial.py',
+    )
+
 %load_ext aiida
 %run -i include/setup_tutorial.py
 ```

docs/source/tutorials/module5.md

@@ -48,6 +48,17 @@ It reuses the sweep data created in {ref}`Module 2 <tutorial:module2>`.
 
 ```{code-cell} ipython3
 # Set up the tutorial's isolated sandbox profile (see Module 1 for details).
+from pathlib import Path
+
+if not Path('include/setup_tutorial.py').exists():
+    import urllib.request
+
+    Path('include').mkdir(exist_ok=True)
+    urllib.request.urlretrieve(
+        'https://raw.githubusercontent.com/GeigerJ2/aiida-core/docs/integrate-tutorials/docs/source/tutorials/include/setup_tutorial.py',
+        'include/setup_tutorial.py',
+    )
+
 %load_ext aiida
 %run -i include/setup_tutorial.py
 ```

docs/source/tutorials/module6a.md

@@ -43,6 +43,17 @@ uv pip install aiida-core aiida-shell aiida-workgraph
 
 ```{code-cell} ipython3
 # Set up the tutorial's isolated sandbox profile (see Module 1 for details).
+from pathlib import Path
+
+if not Path('include/setup_tutorial.py').exists():
+    import urllib.request
+
+    Path('include').mkdir(exist_ok=True)
+    urllib.request.urlretrieve(
+        'https://raw.githubusercontent.com/GeigerJ2/aiida-core/docs/integrate-tutorials/docs/source/tutorials/include/setup_tutorial.py',
+        'include/setup_tutorial.py',
+    )
+
 %load_ext aiida
 %run -i include/setup_tutorial.py
 ```

docs/source/tutorials/module6b.md

@@ -41,6 +41,17 @@ uv pip install aiida-core aiida-shell aiida-workgraph
 
 ```{code-cell} ipython3
 # Set up the tutorial's isolated sandbox profile (see Module 1 for details).
+from pathlib import Path
+
+if not Path('include/setup_tutorial.py').exists():
+    import urllib.request
+
+    Path('include').mkdir(exist_ok=True)
+    urllib.request.urlretrieve(
+        'https://raw.githubusercontent.com/GeigerJ2/aiida-core/docs/integrate-tutorials/docs/source/tutorials/include/setup_tutorial.py',
+        'include/setup_tutorial.py',
+    )
+
 %load_ext aiida
 %run -i include/setup_tutorial.py
 ```