Merge pull request #135 from easyscience/hot-fix

Fix missing install step in notebooks for documentation (Colab support)

Author: AndrewSazonov

.copier-answers.yml

@@ -1,6 +1,6 @@
 # WARNING: Do not edit this file manually.
 # Any changes will be overwritten by Copier.
-_commit: v0.10.1-25-ga5301e9
+_commit: v0.10.1-33-g0f85abf
 _src_path: gh:easyscience/templates
 app_docs_url: https://easyscience.github.io/diffraction-app
 app_doi: 10.5281/zenodo.18163581
@@ -12,7 +12,7 @@ home_repo_name: diffraction
 lib_docs_url: https://easyscience.github.io/diffraction-lib
 lib_doi: 10.5281/zenodo.18163581
 lib_package_name: easydiffraction
-lib_python_max: '3.13'
+lib_python_max: '3.14'
 lib_python_min: '3.11'
 lib_repo_name: diffraction-lib
 project_contact_email: support@easydiffraction.org

.github/copilot-instructions.md

@@ -104,8 +104,8 @@
 
 - Jupyter notebooks (`docs/docs/tutorials/*.ipynb`) are **generated
   artifacts** — never edit them by hand. Edit only the corresponding
-  `*.py` script, then run `pixi run notebook-convert` followed by
-  `pixi run notebook-prepare` to regenerate the notebook.
+  `*.py` script, then run `pixi run notebook-prepare` to regenerate the
+  notebook.
 
 ## Changes
 

.github/workflows/issues-labels.yml

@@ -16,6 +16,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
       - name: Setup easyscience[bot]
         id: bot
         uses: ./.github/actions/setup-easyscience-bot

.github/workflows/pypi-test.yml

@@ -45,9 +45,9 @@ jobs:
       - name: Init pixi project
         run: pixi init easydiffraction
 
-      - name: Add Python 3.13 from Conda
+      - name: Add Python 3.14 from Conda
         working-directory: easydiffraction
-        run: pixi add "python=3.13"
+        run: pixi add "python=3.14"
 
       - name: Add other Conda dependencies
         working-directory: easydiffraction

.github/workflows/test.yml

@@ -44,8 +44,8 @@ concurrency:
 # Set the environment variables to be used in all jobs defined in this workflow
 env:
   CI_BRANCH: ${{ github.head_ref || github.ref_name }}
-  PY_VERSIONS: '3.11 3.13'
-  PIXI_ENVS: 'py-311-env py-313-env'
+  PY_VERSIONS: '3.11 3.14'
+  PIXI_ENVS: 'py-311-env py-314-env'
 
 jobs:
   # Job 1: Set up environment variables

docs/architecture/architecture.md

@@ -771,9 +771,8 @@ All examples below are drawn from the actual tutorials (`tutorials/`).
 
 > **Notebook workflow:** Jupyter notebooks (`*.ipynb`) in
 > `docs/docs/tutorials/` are generated artifacts. Edit only the
-> corresponding `*.py` script, then run `pixi run notebook-convert`
-> followed by `pixi run notebook-prepare` to regenerate the notebook.
-> Never edit `*.ipynb` files by hand.
+> corresponding `*.py` script, then run `pixi run notebook-prepare` to
+> regenerate the notebook. Never edit `*.ipynb` files by hand.
 
 ### 8.1 Project Setup
 

docs/docs/installation-and-setup/index.md

@@ -4,7 +4,8 @@ icon: material/cog-box
 
 # :material-cog-box: Installation & Setup
 
-## Requirements
+**EasyDiffraction** is a cross-platform Python library compatible with
+**Python 3.11** through **3.14**.
 
 EasyDiffraction is a cross-platform Python library compatible with
 **Python 3.11 through 3.13**.  
@@ -13,6 +14,93 @@ installation.
 
 ## Environment Setup <small>optional</small> { #environment-setup data-toc-label="Environment Setup" }
 
+    - **Ease of use**: Pixi simplifies the installation process, making it
+      accessible even for users with limited experience in package management.
+    - **Python version control**: Pixi allows specifying and managing different
+      Python versions for each project, ensuring compatibility.
+    - **Isolated environments**: Pixi creates isolated environments for each
+      project, preventing conflicts between different package versions.
+    - **PyPI and Conda support**: Pixi can install packages from both PyPI and
+      Conda repositories, providing access to a wide range of libraries.
+
+An alternative installation method using the traditional **pip** package
+manager is also provided.
+
+## Installing with Pixi <small>recommended</small> { #installing-with-pixi data-toc-label="Installing with Pixi" }
+
+This section describes the simplest way to set up EasyDiffraction using
+**Pixi**.
+
+#### Installing Pixi
+
+- Install Pixi by following the instructions on the
+  [official Pixi Installation Guide](https://pixi.prefix.dev/latest/installation).
+
+#### Setting up EasyDiffraction with Pixi
+
+<!-- prettier-ignore-start -->
+
+- Choose a project location (local drive recommended).
+
+    ??? warning ":fontawesome-brands-windows: Windows + OneDrive"
+
+        We **do not recommend creating a Pixi project inside OneDrive or other
+        synced folders**.
+
+        By default, Pixi creates the virtual environment inside the project
+        directory (in `.pixi/`). On Windows, synced folders such as OneDrive
+        may cause file‑system issues (e.g., path-length limitations or
+        restricted link operations), which can lead to unexpected install
+        errors or environments being recreated.
+
+        Instead, create your project in a **local directory on your drive**
+        where you have full write permissions.
+
+<!-- prettier-ignore-end -->
+
+- Initialize a new Pixi project and navigate into it:
+  ```txt
+  pixi init easydiffraction
+  cd easydiffraction
+  ```
+- Set the Python version for the Pixi environment (e.g., 3.14):
+  ```txt
+  pixi add python=3.14
+  ```
+- Add EasyDiffraction to the Pixi environment from PyPI:
+  ```txt
+  pixi add --pypi easydiffraction
+  ```
+- Add a Pixi task to run EasyDiffraction commands easily:
+  ```txt
+  pixi task add easydiffraction "python -m easydiffraction"
+  ```
+
+#### Updating Pixi and EasyDiffraction
+
+- To update all packages in the Pixi environment, including
+  EasyDiffraction:
+  ```txt
+  pixi update
+  ```
+- To update Pixi itself to the latest version:
+  ```txt
+  pixi self-update
+  ```
+
+#### Uninstalling Pixi
+
+- Follow the
+  [official Pixi Guide](https://pixi.prefix.dev/latest/installation/#uninstall).
+
+## Classical Installation
+
+This section describes how to install EasyDiffraction using the
+traditional method with **pip**. It is assumed that you are familiar
+with Python package management and virtual environments.
+
+### Environment Setup <small>optional</small> { #environment-setup data-toc-label="Environment Setup" }
+
 We recommend using a **virtual environment** to isolate dependencies and
 avoid conflicts with system-wide packages. If any issues arise, you can
 simply delete and recreate the environment.

docs/docs/tutorials/ed-1.ipynb

@@ -1,5 +1,24 @@
 {
  "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8dbf8e63",
+   "metadata": {
+    "tags": [
+     "hide-in-docs"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# Check whether easydiffraction is installed; install it if needed.\n",
+    "# Required for remote environments such as Google Colab.\n",
+    "import importlib.util\n",
+    "\n",
+    "if importlib.util.find_spec('easydiffraction') is None:\n",
+    "    %pip install easydiffraction"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "0",

docs/docs/tutorials/ed-10.ipynb

@@ -1,5 +1,24 @@
 {
  "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f42176f2",
+   "metadata": {
+    "tags": [
+     "hide-in-docs"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# Check whether easydiffraction is installed; install it if needed.\n",
+    "# Required for remote environments such as Google Colab.\n",
+    "import importlib.util\n",
+    "\n",
+    "if importlib.util.find_spec('easydiffraction') is None:\n",
+    "    %pip install easydiffraction"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "0",

docs/docs/tutorials/ed-11.ipynb

@@ -1,5 +1,24 @@
 {
  "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b38dbf4f",
+   "metadata": {
+    "tags": [
+     "hide-in-docs"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# Check whether easydiffraction is installed; install it if needed.\n",
+    "# Required for remote environments such as Google Colab.\n",
+    "import importlib.util\n",
+    "\n",
+    "if importlib.util.find_spec('easydiffraction') is None:\n",
+    "    %pip install easydiffraction"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "0",