JupyterLite as a "lite" alternative to Quatro docs

nbdev
1

In some cases, JupyterLite can actually be a really nice lightweight alternative to using Quatro.

With nbdev, the actual notebook that we get after running nbdev_clean provides a decent checkpoint to use as documentation. Think of JupyterLite documentation as what you’d get from Quatro if you never use #| hide and always use #|exports. Just with all the pros and cons of the Jupyter UI.

I’ll show how to re-purpose the Jupyter notebook itself as the documentation that’s published in GitHub Pages. The main benefit of this is that it gets around some limitations in the GitHub notebook viewer. Mostly that we can now share a deep-link to a notebook anchor.

Here’s a rough outline of the .github/workflows/docs.yaml GitHub Actions workflow. It’s not exactly as simple as the JupyterLite demo template shows. And there are a few assumptions written into it about where you notebook files live.

name: JupyterLite to GitHub Pages
on:
  push:
    branches: [ "master" ]
  workflow_dispatch:
jobs:
  docs:
    runs-on: ubuntu-latest
    steps: # From [uses: fastai/workflows/quarto-ghp@master]
    ...
    - name: Install the dependencies
      run: |
        # python -m pip install -r requirements.txt
        python -m pip install jupyterlite[all]
    - name: Build the JupyterLite site
      run: |
        mkdir -p lite/files
        jupyter lite init --lite-dir lite
        cp *.ipynb lite/files
        jupyter lite build --lite-dir lite
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.TOLKIEN }}
        force_orphan: true
        publish_dir: ./lite/_output
        # The following lines assign commit authorship to the official
        # GH-Actions bot for deploys to `gh-pages` branch.
        # You can swap them out with your own user credentials.
        user_name: github-actions[bot]
        user_email: 41898282+github-actions[bot]@users.noreply.github.com

Now navigate to:

  • https://<github_pages_hostname>/retro/tree,
  • or https://<github_pages_hostname>/retro/notebooks/?path=index.ipynb,
  • or just to https://<github_pages_hostname> (for the JupyterLab UI)

We can extend this GitHub Actions workflow by mixing and matching Quatro pages with the JupyterLite notebooks. The default index can be to Quatro and it can link into the JupyterLite notebooks as an alternative view. But that’s a little too fancy for what I’m trying to demonstrate here.

Please note that this is not intended as a replacement for documenting your python libraries or for your external API documentation!

But I believe there is a large use-case for nbdev in private internal repositories, which aren’t traditionally documented carefully. In these repositories, the benefits of using literate/exploratory programming are enough as far as documentation goes.