Comments and version update in deploy.yml (#4)

tschm · renovate[bot] · web-flow · commit 1f95beddcf78 · 2025-06-02T10:04:19.000-04:00
* ignore .idea

* renovate for updates

* deployment with comments

* Update renovate.json

* chore(deps): update astral-sh/setup-uv action to v6

* cleaning comments in deploy.yml

* moving build script

* build with comments now

* Update build.py

---------

Co-authored-by: renovate[bot] &lt;29139614+renovate[bot]@users.noreply.github.com&gt;
diff --git a/.github/renovate.json b/.github/renovate.json
@@ -0,0 +1,12 @@
+{
+  "extends": [
+    "config:recommended",
+    ":enablePreCommit",
+    ":dependencyDashboard",
+    ":semanticCommits",
+    ":pinVersions"
+  ],
+  "enabledManagers": [
+    "github-actions"
+  ]
+}
diff --git a/.github/scripts/build.py b/.github/scripts/build.py
@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""
+Build script for marimo notebooks.
+
+This script exports marimo notebooks to HTML/WebAssembly format and generates
+an index.html file that lists all the notebooks. It handles both regular notebooks
+(from the notebooks/ directory) and apps (from the apps/ directory).
+
+The script can be run from the command line with optional arguments:
+    python .github/scripts/build.py [--output-dir OUTPUT_DIR]
+
+The exported files will be placed in the specified output directory (default: _site).
+"""
+
+import os
+import subprocess
+import argparse
+from typing import List, Optional, Dict, Any, Union
+from pathlib import Path
+
+
+def export_html_wasm(notebook_path: str, output_dir: str, as_app: bool = False) -> bool:
+    """Export a single marimo notebook to HTML/WebAssembly format.
+
+    This function takes a marimo notebook (.py file) and exports it to HTML/WebAssembly format.
+    If as_app is True, the notebook is exported in "run" mode with code hidden, suitable for
+    applications. Otherwise, it's exported in "edit" mode, suitable for interactive notebooks.
+
+    Args:
+        notebook_path (str): Path to the marimo notebook (.py file) to export
+        output_dir (str): Directory where the exported HTML file will be saved
+        as_app (bool, optional): Whether to export as an app (run mode) or notebook (edit mode).
+                                Defaults to False.
+
+    Returns:
+        bool: True if export succeeded, False otherwise
+    """
+    # Convert .py extension to .html for the output file
+    output_path: str = notebook_path.replace(".py", ".html")
+
+    # Base command for marimo export
+    cmd: List[str] = ["marimo", "export", "html-wasm"]
+
+    # Configure export mode based on whether it's an app or a notebook
+    if as_app:
+        print(f"Exporting {notebook_path} to {output_path} as app")
+        cmd.extend(["--mode", "run", "--no-show-code"])  # Apps run in "run" mode with hidden code
+    else:
+        print(f"Exporting {notebook_path} to {output_path} as notebook")
+        cmd.extend(["--mode", "edit"])  # Notebooks run in "edit" mode
+
+    try:
+        # Create full output path and ensure directory exists
+        output_file: str = os.path.join(output_dir, output_path)
+        os.makedirs(os.path.dirname(output_file), exist_ok=True)
+
+        # Add notebook path and output file to command
+        cmd.extend([notebook_path, "-o", output_file])
+
+        # Run marimo export command
+        print(cmd)
+        subprocess.run(cmd, capture_output=True, text=True, check=True)
+        return True
+    except subprocess.CalledProcessError as e:
+        # Handle marimo export errors
+        print(f"Error exporting {notebook_path}:")
+        print(e.stderr)
+        return False
+    except Exception as e:
+        # Handle unexpected errors
+        print(f"Unexpected error exporting {notebook_path}: {e}")
+        return False
+
+
+def generate_index(all_notebooks: List[str], output_dir: str) -> None:
+    """Generate an index.html file that lists all the notebooks.
+
+    This function creates an HTML index page that displays links to all the exported
+    notebooks. The index page includes the marimo logo and displays each notebook
+    with a formatted title and a link to open it.
+
+    Args:
+        all_notebooks (List[str]): List of paths to all the notebooks
+        output_dir (str): Directory where the index.html file will be saved
+
+    Returns:
+        None
+    """
+    print("Generating index.html")
+
+    # Create the full path for the index.html file
+    index_path: str = os.path.join(output_dir, "index.html")
+
+    # Ensure the output directory exists
+    os.makedirs(output_dir, exist_ok=True)
+
+    try:
+        # Open the index.html file for writing
+        with open(index_path, "w") as f:
+            # Write the HTML header and page structure
+            f.write(
+                """<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>marimo</title>
+    <link href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css" rel="stylesheet">
+  </head>
+  <body class="font-sans max-w-2xl mx-auto p-8 leading-relaxed">
+    <div class="mb-8">
+      <img src="https://raw.githubusercontent.com/marimo-team/marimo/main/docs/_static/marimo-logotype-thick.svg" alt="marimo" class="h-20" />
+    </div>
+    <div class="grid gap-4">
+"""
+            )
+            # Process each notebook and create a card for it
+            for notebook in all_notebooks:
+                # Extract the notebook name from the path and remove the .py extension
+                notebook_name: str = notebook.split("/")[-1].replace(".py", "")
+
+                # Format the display name by replacing underscores with spaces and capitalizing
+                display_name: str = notebook_name.replace("_", " ").title()
+
+                # Write the HTML for the notebook card
+                f.write(
+                    f'      <div class="p-4 border border-gray-200 rounded">\n'
+                    f'        <h3 class="text-lg font-semibold mb-2">{display_name}</h3>\n'
+                    f'        <div class="flex gap-2">\n'
+                    f'          <a href="{notebook.replace(".py", ".html")}" class="px-3 py-1 bg-gray-100 hover:bg-gray-200 rounded">Open Notebook</a>\n'
+                    f"        </div>\n"
+                    f"      </div>\n"
+                )
+            # Write the HTML footer
+            f.write(
+                """    </div>
+  </body>
+</html>"""
+            )
+    except IOError as e:
+        # Handle file I/O errors
+        print(f"Error generating index.html: {e}")
+
+
+def main() -> None:
+    """Main function to build marimo notebooks.
+
+    This function:
+    1. Parses command line arguments
+    2. Finds all marimo notebooks in the 'notebooks' and 'apps' directories
+    3. Exports each notebook to HTML/WebAssembly format
+    4. Generates an index.html file that lists all the notebooks
+
+    Command line arguments:
+        --output-dir: Directory where the exported files will be saved (default: _site)
+
+    Returns:
+        None
+    """
+    # Set up command line argument parsing
+    parser: argparse.ArgumentParser = argparse.ArgumentParser(description="Build marimo notebooks")
+    parser.add_argument(
+        "--output-dir", default="_site", help="Output directory for built files"
+    )
+    args: argparse.Namespace = parser.parse_args()
+
+    # Initialize empty list to store all notebook paths
+    all_notebooks: List[str] = []
+
+    # Look for notebooks in both the notebooks/ and apps/ directories
+    for directory in ["notebooks", "apps"]:
+        dir_path: Path = Path(directory)
+        if not dir_path.exists():
+            print(f"Warning: Directory not found: {dir_path}")
+            continue
+
+        # Find all Python files recursively in the directory
+        all_notebooks.extend(str(path) for path in dir_path.rglob("*.py"))
+
+    # Exit if no notebooks were found
+    if not all_notebooks:
+        print("No notebooks found!")
+        return
+
+    # Export each notebook to HTML/WebAssembly format
+    # Files in the apps/ directory are exported as apps (run mode)
+    # Files in the notebooks/ directory are exported as notebooks (edit mode)
+    for nb in all_notebooks:
+        export_html_wasm(nb, args.output_dir, as_app=nb.startswith("apps/"))
+
+    # Generate the index.html file that lists all notebooks
+    generate_index(all_notebooks, args.output_dir)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -1,56 +1,74 @@
+# This workflow builds and deploys marimo notebooks to GitHub Pages
+# It runs automatically when changes are pushed to the main branch or can be triggered manually
+
 name: Deploy to GitHub Pages
 
+# Defines when the workflow will run
 on:
   push:
-    branches: ['main']
-  workflow_dispatch:
+    branches: ['main']  # Trigger on pushes to main branch
+  workflow_dispatch:    # Allow manual triggering from the GitHub UI
 
+# Concurrency settings to manage multiple workflow runs
 concurrency:
-  group: 'pages'
-  cancel-in-progress: false
+  group: 'pages'             # Only one workflow in the 'pages' group can run at a time
+  cancel-in-progress: false  # Don't cancel in-progress runs when a new one is triggered
 
+# Environment variables used by the workflow
 env:
-  UV_SYSTEM_PYTHON: 1
+  UV_SYSTEM_PYTHON: 1   # Use system Python with uv package manager
 
 jobs:
+  # The build job exports marimo notebooks to static HTML/WebAssembly
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-latest  # Use the latest Ubuntu runner
     steps:
+      # Check out the repository code
       - uses: actions/checkout@v4
 
+      # Install uv package manager for faster Python package installation
       - name: 🚀 Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v6
 
+      # Set up Python environment
       - name: 🐍 Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.12
+          python-version: 3.12  # Use Python 3.12 for the build
 
+      # Install marimo and other required dependencies
       - name: 📦 Install dependencies
         run: |
           uv pip install marimo
 
+      # Run the build script to export notebooks to WebAssembly
       - name: 🛠️ Export notebooks
         run: |
-          python scripts/build.py
+          python .github/scripts/build.py  # This script exports all notebooks to the _site directory
 
+      # Upload the generated site as an artifact for the deploy job
       - name: 📤 Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: _site
+          path: _site  # Directory containing the built site
 
+  # The deploy job publishes the built site to GitHub Pages
   deploy:
-    needs: build
+    needs: build  # This job depends on the build job completing successfully
 
+    # Required permissions for the GitHub Pages deployment
     permissions:
-      pages: write
-      id-token: write
+      pages: write      # Permission to deploy to Pages
+      id-token: write   # Permission to verify the deployment
 
+    # Configure the deployment environment
     environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
+      name: github-pages                             # Deploy to the github-pages environment
+      url: ${{ steps.deployment.outputs.page_url }}  # Use the URL from the deployment step
+
+    runs-on: ubuntu-latest  # Use the latest Ubuntu runner
     steps:
+      # Deploy the site to GitHub Pages using the official action
       - name: 🚀 Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+        id: deployment                 # ID used to reference this step's outputs
+        uses: actions/deploy-pages@v4  # GitHub's official Pages deployment action
diff --git a/.gitignore b/.gitignore
@@ -167,7 +167,7 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
 
 # PyPI configuration file
 .pypirc
diff --git a/README.md b/README.md
@@ -37,10 +37,10 @@ df = pl.read_csv(mo.notebook_location() / "public" / "penguins.csv")
 
 ## 🧪 Testing
 
-To test the export process, run `scripts/build.py` from the root directory.
+To test the export process, run `.github/scripts/build.py` from the root directory.
 
 ```bash
-python scripts/build.py
+python .github/scripts/build.py
 ```
 
 This will export all notebooks in a folder called `_site/` in the root directory. Then to serve the site, run:
diff --git a/scripts/build.py b/scripts/build.py
