Merge pull request #22 from sympy/jan_updates

Update SymPy version to 1.13.3. Also added dev instructions in README.
sympy · Jan 2, 2025 · 38e169e · 38e169e
2 parents dc3a874 + ce84152
commit 38e169e
Show file tree

Hide file tree

Showing 5 changed files with 77 additions and 68 deletions.
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -13,11 +13,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.11'
       - name: Install the dependencies
         run: |
           python -m pip install -r requirements.txt
@@ -26,30 +26,29 @@ jobs:
           jupyter lite build
       - name: Add custom index.html (live.sympy.org landing page) and static/ files
         run: |
-          pip install jinja2 babel
-          ls -ltr ./_output
           ./generateindex.py
-          ls -ltr ./_output
       - name: Add CNAME file containing live.sympy.org
         run: |
           echo "live.sympy.org" > ./_output/CNAME
       - name: Upload (dist)
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: jupyterlite-demo-dist-${{ github.run_number }}
           path: ./_output
+          if-no-files-found: error
 
   deploy:
     if: github.ref == 'refs/heads/main'
-    needs: [build]
+    needs: build
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v2.3.1
-      - uses: actions/download-artifact@v2
+      - uses: actions/download-artifact@v4
         with:
           name: jupyterlite-demo-dist-${{ github.run_number }}
           path: ./dist
+          merge-multiple: true
       - name: Deploy
         uses: JamesIves/github-pages-deploy-action@4.1.3
         with:

diff --git a/README.md b/README.md
@@ -1,87 +1,90 @@
-# JupyterLite Shell for Sympy Live 
-
-This repo contains the [JupyterLite](https://jupyterlite.readthedocs.io) config
-files used by the new SymPy Live. The code is deployed as a static site to GitHub Pages.
+# JupyterLite Shell for SymPy Live 
 
+This repo contains the code that powers the [SymPy Live Shell](https://live.sympy.org/),
+which is based on the [JupyterLite](https://jupyterlite.readthedocs.io) application,
+and deployed as a static site to GitHub Pages.
 
 
 ## ✨ Try it in your browser ✨
 
 - **https://live.sympy.org/**
 
-Alternative URLs:
+Other interesting URLs:
 - https://www.sympy.org/en/shell.html
 - [evaluate command](https://www.sympy.org/en/shell.html?evaluate=diff(sin(x)%2C%20x)%0A%23--%0A)
 
 
-## Requirements
-
-JupyterLite is being tested against modern web browsers:
-
-- Firefox 90+
-- Chromium 89+
 
+## Developer information
 
+The SymPy Live shell is a thin wrapper around the `repl` app in the JupyterLite.
+In order to reduce the maintenance needs,
+we leverage the code from the [`jupyterlite/demo`](https://github.com/jupyterlite/demo) project,
+and provide only minimal customization: a custom landing page that loads the REPL in an iframe.
 
-## Commands
 
-See Developer instructions below for installing the prerequisites.
+### Configs
 
-Run jupyter lite locally:
-```bash
-jupyter lite serve
-```
-
-Build ready for distribution via static serve:
-
-```bash
-jupyter lite build
-```
+The operation of JupyterLite is configured in several places:
+- `requirements.txt`: specifies the version `jupyterlab`, `jupyterlite-core` and `jupyterlite-pyodide-kernel`.
+- `jupyter_lite_config.json`: general configs for the Jupyter lite build system
+- `repl/jupyter-lite.json`: configs specific to the REPL app. See [example here](https://github.com/ivanistheone/live/blob/357e60a228b43ac28ef835953d00f4495a429d78/repl/jupyter-lite.json).
+- `overrides.json`: customizations of the JupyterLite UI
 
-The files will be saved in `_output/`.
+In addition to the above, the SymPy Live shell depends on the following customizations:
+- Custom landing page [index.html](https://github.com/sympy/live/blob/main/templates/index.html) that embeds the JupyterLite REPL.
+- Automatic import `from sympy import *` and init commands in [index.html template](https://github.com/sympy/live/blob/main/templates/index.html#L6-L11).
+- JavaScript code to decode evaluate query string, see [here](https://github.com/sympy/live/blob/main/templates/index.html#L49-L56).
 
+> [!NOTE]
+> The versions of `jupyterlab` and `jupyterlite-core` determine which version of JupyterLite we are running.
+> Use the [upstream requirements file](https://github.com/jupyterlite/demo/blob/main/requirements.txt) as reference.
 
-You can test the files using any static server, for example:
+> [!NOTE]
+> The version of SymPy running on [live.sympy.org/](https://live.sympy.org/) depends on the package version included in Pyodide.
+> See [here](https://pyodide.org/en/stable/usage/packages-in-pyodide.html) for the current package versions.
+> Updating the SymPy version requires first updating the [SymPy package in Pyodide](https://github.com/pyodide/pyodide/tree/main/packages/sympy).
+> See this [PR](https://github.com/pyodide/pyodide/pull/5098) for example. 
+> Once the new version of `jupyterlite-pyodide-kernel` is released (which can take months),
+> we can update the version in `requirements.txt` and deploy the updated SymPy Live Shell following the instructions below.
 
-```bash
-cd _output/
-python -m http.server
-```
 
 
-## Configs
+### Deploying in production
 
-The operation of JupyterLite can be configured in several places:
-- `jupyter_lite_config.json`: general configs for the jupyter lite build system
-- `repl/jupyter-lite.json`: configs specific to the REPL app. See [example here](https://github.com/ivanistheone/live/blob/357e60a228b43ac28ef835953d00f4495a429d78/repl/jupyter-lite.json).
-- `overrides.json`: customizations of the JupyterLite UI
-- `requirements.txt`: Python packages needed to build this project (used by CI)
+SymPy Live Shell is hosted as a static website on GitHub Pages with a custom domain.
+Deployment to production is automated by the Github actions workflow [deploy.yml](https://github.com/sympy/live/blob/main/.github/workflows/deploy.yml),
+which performs the following steps:
 
+ 1. Installs Python and dependencies listed in `requirements.txt`
+ 2. Runs the command `jupyter lite build` to build the JupyterLab static site, placing the results in `_output/`.
+ 3. Runs `./generateindex.py` to overwrite the index file `_output/index.html` with the custom SymPy Live Shell landing page.
+ 4. Adds the file `_output/CNAME` containing `live.sympy.org`.
+ 5. Deploys the contents of `_output` to GitHub pages (`gh-pages` branch hosted at https://live.sympy.org).
 
-### Further Information and Updates
+The last step (deploy to `gh-pages`) runs only on push to the `main` branch.
 
-For more info, keep an eye on the JupyterLite documentation:
 
-- Configuring: https://jupyterlite.readthedocs.io/en/latest/configuring.html
-- Deploying: https://jupyterlite.readthedocs.io/en/latest/deploying.html
+### Running locally
 
+The local development steps are similar to the production steps,
+but you'll run local web server to view the static files in `_output`,
+and modify one line in `templates/index.html` to load the iframe from localhost (127.0.0.1):
 
-## Deploy a new version of JupyterLite
+ 1. Install Python and dependencies listed in `requirements.txt`
+ 2. Runs the command `jupyter lite build` to build the JupyterLab static site, placing the results in `_output/`.
+ 3. Edit [`templates/index.html`](https://github.com/sympy/live/blob/main/templates/index.html#L3)
+    to change the value of `host` from `https://www.sympy.org/live` to `http://127.0.0.1:8000`.
+ 4. Run `./generateindex.py` to overwrite the index file `_output/index.html` with the custom SymPy Live Shell landing page.
+ 5. Run a local web server in the directory `_output/`. For example, you can run `cd _output/` followed by `python3 -m http.server 8000`.
+ 6. Open `http://127.0.0.1:8000/index.html` in your browser.
 
-To change the version of the prebuilt JupyterLite assets, update the `jupyterlite`
-package version in the [requirements.txt](./blob/main/requirements.txt) file.
 
-The `requirements.txt` file can also be used to add extra prebuilt ("federated")
-JupyterLab extensions to the deployed JupyterLite website.
 
-Commit and push any changes. The site will be deployed on the next push to the `main` branch.
+### More information
 
+For more info, keep an eye on the JupyterLite documentation:
 
-## Development
+- Configuring: https://jupyterlite.readthedocs.io/en/stable/quickstart/configure.html
+- Deploying to GitHub pages: https://jupyterlite.readthedocs.io/en/stable/quickstart/deploy.html
 
-1. Create a new conda environment using virualenv or conda.
-2. Install Python requirements:
-   ```bash
-   python -m pip install -r requirements.txt
-   ```
-3. You can now run `jupyter lite` commands like `check`, `build`, `serve`, etc.
diff --git a/requirements.txt b/requirements.txt
@@ -1,3 +1,10 @@
-jupyterlab~=3.5.3
-jupyterlite-core>=0.1.0,<0.2.0
-jupyterlite-pyodide-kernel>=0.0.6,<0.1.0
+# Core modules (mandatory)
+jupyterlab~=4.2.5
+jupyterlite-core>=0.4.5,<0.5
+
+# Python kernel (optional)
+jupyterlite-pyodide-kernel>=0.4.7,<0.5
+
+# Specific to generating SymPy Live index page
+jinja2==3.1.5
+babel==2.16.0
diff --git a/templates/base.html b/templates/base.html
@@ -91,7 +91,7 @@ <h3>{% trans %}Follow Us{% endtrans %}<h3>
       </aside>
     </section>
     <footer class="row">
-      <p>Copyright &copy; 2022 SymPy Development Team. </p>
+      <p>Copyright &copy; 2025 SymPy Development Team. </p>
       <p>
         {% trans url='https://github.com/sympy/live' %}This page is open source. Fork <a href="{{ url }}">the project on GitHub</a> to edit it.{% endtrans %}
       </p>

diff --git a/templates/index.html b/templates/index.html
@@ -1,7 +1,7 @@
 {% extends "base.html" %}
 
-{% set host = "https://www.sympy.org" %}
-{% set path = "live/repl/" %}
+{% set host = "https://www.sympy.org/live" %}
+{% set path = "/repl/" %}
 {% set query = "?toolbar=1&kernel=python" %}
 {% set code1 = "from sympy import *" %}
 {% set code2 = "init_printing()" %}
@@ -45,7 +45,7 @@
 
   $(document).ready(function() {
     // default iframe src with SymPy initcode
-    var iframe_src = "{{ host }}/{{ path }}{{ query }}&code={{ initcode|urlencode }}";
+    var iframe_src = "{{ host }}{{ path }}{{ query }}&code={{ initcode|urlencode }}";
     // check if we have additional statements to evaluate in the query string
     var statements = getURLParameter('evaluate');
     if (statements) {