[Documentation]: Adding advanced tutorial and improvements to documentation

.github/workflows/docs-gh-pages.yml

@@ -1,40 +1,101 @@
-name: Build and Deploy Documentation
+name: Docs — Build & Preview
 
 on:
   push:
-    branches:
-      - main
+    branches: [ main ]            # regular prod deploy
+    paths:
+      - 'mkdocs.yml'
+      - 'docs/**'
+  pull_request:                    # preview only when docs are touched
+    branches: [ '**' ]
+    paths:
+      - 'mkdocs.yml'
+      - 'docs/**'
 
 jobs:
-  build-and-deploy-docs:
+  build:
     runs-on: ubuntu-latest
+    outputs:
+      short_sha: ${{ steps.sha.outputs.short }}
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # Fetch all history for .git-restore-mtime to work correctly
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.x'
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.x' }
+      - uses: astral-sh/setup-uv@v6
 
-      - name: Install uv via GitHub Action
-        uses: astral-sh/setup-uv@v6
-
-      - name: Install mesa-frames + docs dependencies
+      - name: Install mesa-frames + docs deps
         run: |
           uv pip install --system .
           uv pip install --group docs --system
 
-      - name: Build MkDocs site (general documentation)
-        run: mkdocs build --config-file mkdocs.yml --site-dir ./site
+      - name: Convert jupytext .py notebooks to .ipynb
+        run: |
+          set -euxo pipefail
+          # Convert any jupytext .py files to .ipynb without executing them.
+          # Enable nullglob so the pattern expands to empty when there are no matches
+          # and globstar so we recurse into subdirectories (e.g., user-guide/).
+          shopt -s nullglob globstar || true
+          files=(docs/general/**/*.py)
+          if [ ${#files[@]} -eq 0 ]; then
+            echo "No jupytext .py files found under docs/general"
+          else
+            for src in "${files[@]}"; do
+              [ -e "$src" ] || continue
+              dest="${src%.py}.ipynb"
+              echo "Converting $src -> $dest"
+              # jupytext will write the .ipynb alongside the source file
+              uv run jupytext --to notebook "$src"
+            done
+          fi
+
+      - name: Build MkDocs site
+        run: uv run mkdocs build --config-file mkdocs.yml --site-dir ./site
+
+      - name: Build Sphinx docs (API)
+        run: uv run sphinx-build -b html docs/api site/api
 
-      - name: Build Sphinx docs (API documentation)
-        run: sphinx-build -b html docs/api site/api
+      - name: Short SHA
+        id: sha
+        run: echo "short=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
 
-      - name: Deploy to GitHub Pages
+      - name: Upload site artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: site
+          path: site
+
+  deploy-main:
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: site, path: site }
+      - name: Deploy to GitHub Pages (main)
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
           publish_dir: ./site
-          force_orphan: true
+          force_orphan: true
+
+  deploy-preview:
+    needs: build
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: site, path: site }
+      - name: Deploy preview under subfolder
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./site
+          destination_dir: preview/${{ github.head_ref || github.ref_name }}/${{ needs.build.outputs.short_sha }}
+          keep_files: true        # keep previous previews
+          # DO NOT set force_orphan here
+      - name: Print preview URL
+        run: |
+          echo "Preview: https://${{ github.repository_owner }}.github.io/$(basename ${{ github.repository }})/preview/${{ github.head_ref || github.ref_name }}/${{ needs.build.outputs.short_sha }}/"

.gitignore

@@ -154,3 +154,9 @@ cython_debug/
 *.code-workspace
 llm_rules.md
 .python-version
+docs/site
+docs/api/_build
+docs/general/user-guide/data_csv
+docs/general/user-guide/data_parquet
+docs/api/reference/**/mesa_frames.*.rst
+examples/**/results

CONTRIBUTING.md

@@ -58,28 +58,13 @@ Before you begin contributing, ensure that you have the necessary tools installe
 
 #### **Step 3: Install Dependencies** 📦
 
-It is recommended to set up a virtual environment before installing dependencies.
+We manage the development environment with [uv](https://docs.astral.sh/uv/):
 
-- **Using UV**:
+```sh
+uv sync --all-extras
+```
 
-  ```sh
-  uv add --dev .[dev]
-  ```
-
-- **Using Hatch**:
-
-  ```sh
-  hatch env create dev
-  ```
-
-- **Using Standard Python**:
-
-  ```sh
-  python3 -m venv myenv
-  source myenv/bin/activate  # macOS/Linux
-  myenv\Scripts\activate    # Windows
-  pip install -e ".[dev]"
-  ```
+This creates `.venv/` and installs mesa-frames with the development extras.
 
 #### **Step 4: Make and Commit Changes** ✨
 
@@ -99,21 +84,19 @@ It is recommended to set up a virtual environment before installing dependencies
 - **Run pre-commit hooks** to enforce code quality standards:
 
   ```sh
-  pre-commit run
+  uv run pre-commit run -a
   ```
 
 - **Run tests** to ensure your contribution does not break functionality:
 
   ```sh
-  pytest --cov
+  uv run pytest -q --cov=mesa_frames --cov-report=term-missing
   ```
 
-  - If using UV: `uv run pytest --cov`
-
 - **Optional: Enable runtime type checking** during development for enhanced type safety:
 
   ```sh
-  MESA_FRAMES_RUNTIME_TYPECHECKING=1 uv run pytest --cov
+  MESA_FRAMES_RUNTIME_TYPECHECKING=1 uv run pytest -q --cov=mesa_frames --cov-report=term-missing
   ```
 
   !!! tip "Automatically Enabled"
@@ -135,8 +118,7 @@ It is recommended to set up a virtual environment before installing dependencies
   - Preview your changes by running:
 
     ```sh
-    mkdocs serve
-    uv run mkdocs serve #If using uv
+    uv run mkdocs serve
     ```
 
   - Open `http://127.0.0.1:8000` in your browser to verify documentation updates.