Demoing JupyterLab Extensions from an Extension Repo Using Github Pages and JupyterLite

Following on from Notes on the JupyterLab Notebook HTML DOM Model, Part 9: Building and Distributing a Pre-Built Extension, in which the build process generated a platform independent Python package wheel, jupyterlab_empinken_extension-0.1.1-py3-none-any.whl, I pushed it to pypi using a simple pypi-publish Github Action (you need to set a PYPI_PASSWORD API key (minted in your PyPi account from Account Settings (scroll down..) API tokens ) in the repo Secrets > Actions > Repository secrets settings in order to push packages to PyPi.

I generally set a PyPi token with permissions on all repos, push the package for the first time using that token, then mint a repo specific token and update the repo settings; I keep thinking there must be a more sensible way?!)

name: Publish Python distributions to PyPI

on:
  release:
    types: [published]
  workflow_dispatch:

jobs:
  build-n-publish:
    name: Build and publish Python distribution to PyPI
    runs-on: ubuntu-18.04
    
    steps:
    - uses: actions/checkout@master
    - name: Set up Python 3.8
      uses: actions/setup-python@v1
      with:
        python-version: 3.8
        
    - name: Build a binary wheel and a source tarball
      run: |
        python3 -m pip install --user --upgrade setuptools wheel
        python3 -m pip install build
        python3 -m build
    - name: Publish distribution to PyPI
      # if: startsWith(github.event.ref, 'refs/tags')
      uses: pypa/gh-action-pypi-publish@master
      with:
        password: ${{ secrets.pypi_password }}

I also use a jupyterlite-pages action to push a JupyterLite distribution demoing the extension to Github Pages:

name: JupyterLite Build and Deploy

on:
  release:
    types: [published]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup Python
        uses: actions/setup-python@v2
        with:
          python-version: 3.8
      - name: Install the dependencies
        run: |
          python -m pip install -r requirements-jupyterlite.txt
      - name: Build the JupyterLite site
        run: |
          cp README.md content
          jupyter lite build --contents content
      - name: Upload (dist)
        uses: actions/upload-artifact@v2
        with:
          name: jupyterlite-demo-dist-${{ github.run_number }}
          path: ./_output

  deploy:
    if: github.ref == 'refs/heads/main'
    needs: [build]
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2.3.1
      - uses: actions/download-artifact@v2
        with:
          name: jupyterlite-demo-dist-${{ github.run_number }}
          path: ./dist
      - name: Deploy
        uses: JamesIves/github-pages-deploy-action@4.1.3
        with:
          branch: gh-pages
          folder: dist

To use Github Pages (a website published from a specified repo branch and directory), you need to ensure that they are enabled from your repo Settings:

My actions are triggered by a release or (more usually) manually:

I really should make sure that the JupyterLite build follows on from a package release or an update to the content/ directory.

You might notice the JupyterLite distribution action references a requirements file (requirements-jupyterlite.txt). This file needs to include the JupyterLab and JuptyerLite packages, as well as any other (prebuilt) packages you want to install:

# Base install
ipywidgets>=7.7,<8
jupyterlab~=3.3.0
jupyterlite==0.1.0b4

# Extension package we want to demo
jupyterlab-empinken-extension

If the package you want to demo in JupyterLite is not available from PyPi, I wonder, can you specfy the wheel URL in the requirements file (eg https://raw.githubusercontent.com/innovationOUtside/jupyterlab_empinken_extension/main/dist/jupyterlab_empinken_extension-0.1.1-py3-none-any.whl? If not, add a line to the jupyterlite distribution action along the lines of pip3 install https://raw.githubusercontent.com/innovationOUtside/jupyterlab_empinken_extension/main/dist/jupyterlab_empinken_extension-0.1.1-py3-none-any.whl).

Any files you want included as part of the distribution, such as a demo notebook, should be placed in the repo content/ directory.

When the site is published, (and you might need to check in the repo settings that you have enabled Pages appropriately), you should be able to test your extension running in JupyterLab in your browser. For example, my innovationOUtside/jupyterlab_empinken_extension demo is at https://innovationoutside.github.io/jupyterlab_empinken_extension/