jupyak#

get a statically-hosted JupyterLite preview of pull requests from across the Jupyter stack

what does it do?#

This repo accepts pull requests that build static preview sites to the Jupyter(Lite) stack.

how do I get a preview site?#

  • Make a jupyak_config.toml

    • … with the Request Preview Site form

    • … or by manually forking and creating a new branch from your fork

  • Start a Pull Request (PR) including the jupyak_config.toml

  • Wait for the PR to build a site on ReadTheDocs (RTD)

  • Make changes to the PR to trigger re-building the preview site

where does it do it?#

  • https://github.com/deathbeds/jupyak

    • a GitHub repo where the source code for this package, and all Issues, Pull Requests, and source code are stored

  • https://deathbeds.github.io/jupyak

    • a GitHub Pages site, rebuilt nightly, which provides a form for building preview site requests

  • https://jupyak--{:pr-number}.org.readthedocs.build/en/{:pr-number}

    • ReadTheDocs sites generated for each Pull Request

      • this will either be a

        • PR-based preview site

        • preview of the docs for the site itself

  • https://jupyak.rtfd.io

    • a ReadTheDocs site for more information about how this all works

The above works on at least one Ubuntu 22.03 LTS machine, but little care has been taken to make anything run on any other system, and likely won’t be tested anywhere else.

how does it work?#

Delivering a preview site uses a few different GitHub Actions workflows and ReadTheDocs configurations. Once a PR is created:

  • A GitHub Actions (GHA) job will create a link to the custom domain site

    • This will initially return 404, as the site isn’t built yet

    • Clicking instead on the ReadTheDocs check at the bottom of the Pull Request will show build logs, but these are intentionally sparse, capturing most output as logs to present in the built site.

  • RTD will check out the PR and build a preview JupyterLite site on a custom domain

    • If the preview site fails to build (or even check out due to conflicts), the built RTD site will contain human-readable error logs

  • Additional commits on the PR can trigger a rebuild of the site

what can it build?#

jupyak understand how to work with one or more fragments of human-readable GitHub URLs of the forms:

  • /pull/{:pull-id}

  • /tree/{:branch}

  • /releases/tag/{:tag}

    • note that the /tree/{:tag} form will fail loudly

…from the following repos to see novel behavior.

repo

browser UI

kernel

https://github.com/ipython/comm

✅

https://github.com/ipython/ipython

✅

https://github.com/ipython/traitlets

✅

https://github.com/jupyter-widgets/ipywidgets

✅

✅

https://github.com/jupyter/jupyter_core

✅

https://github.com/jupyter/nbformat

✅

https://github.com/jupyter/notebook

✅

https://github.com/jupyterlab/jupyterlab

✅

https://github.com/jupyterlab/jupyterlab_pygments

✅

✅

https://github.com/jupyterlab/lumino

✅

https://github.com/jupyterlite/jupyterlite

✅

https://github.com/jupyterlite/pyodide-kernel

✅

✅

what about configuring JupyterLite?#

Additionally, a single GitHub Gist can be used as the contents of the preview site. If the gist contains jupyter_lite_config.json and/or jupyter-lite.json, these will be merged into the configuration used to build and host the site.

what does it not build?#

The following repos are cloned and installed to satisfy build-time requirements, but have little measurable experience the UI.

repo

why not?

https://github.com/ipython/ipykernel

heavy deps, patched in pyodide

https://github.com/jupyter-lsp/jupyterlab-lsp

needs mock JS server

https://github.com/jupyter-server/jupyter_server

heavy deps

https://github.com/jupyter-server/jupyter_server_terminals

what’s a process?

https://github.com/jupyterlab/jupyterlab_server

heavy deps

https://github.com/jupyter/nbconvert

heavy deps, no data_files

what else is it not building?#

For each repo, a few more things could be built, and might be interesting to evaluate a PR stack. However, each of these would come at the expense of a lower chance of a usable JupyterLite site at the end of each PR build. These include:

  • test reports

  • examples

  • documentation

  • lint reports

  • anything that doesn’t work in the browser

  • anything that requires a c/rust/emscripten compiler or other heavy dependencies such as pandas

documentation contents#