Skip to content

Editing qc‐workbook

Jump to bottom
Yutaro Iiyama edited this page Mar 5, 2025 · 4 revisions

Structure overview

As of February 2025, qc-workbook is maintained as a set of Jupyter notebooks saved in Jupytext Markdown format. The notebooks are compiled into a html using jupyter-book, and published as a GitHub Pages website. The website is made interactive (executable) using the Binder technology, with the compute server hosted at mybinder.org.

Here are slightly more detailed description of the involved tools:

  • Jupyter Notebook: File format that mixes Markdown text, executable code, and graphics.
  • Jupytext: A tool (a python library and a Jupyter Lab addon) that "link" Jupyter notebook (.ipynb) and Markdown (.md) files. Jupyter Notebooks are visual and easy to edit but difficult to version-control. We therefore edit the workbook using Jupyter locally but save the converted markdown files on GitHub.
  • Jupyter Book: A library that converts a set of Jupyter Notebooks (and Markdown files linked by Jupytext) into a website using Sphinx. The inputs (which compose most of the contents of this GitHub repository) are:
    • A table of contents file describing the structure of the website
    • Source notebooks
    • A configuration file (which also sets up interactive features)
  • GitHub Actions: Scripts that can be run over a repository on the cloud (server hosted by GitHub). We compile the website (run the jupyterbook command) and publish the website (upload to GitHub pages) in an action triggered manually in the repository Actions page.
  • GitHub Pages: Web hosting service run by GitHub.
  • Binder: Free JupyterHub hosting service. Users can open and execute Jupyter Notebook files in any GitHub repository through MyBinder.
  • Thebe: Engine for executable web pages. Our Jupyter Book website uses Thebe with MyBinder.org as the compute backend to provide the interactive feature.

Jupyter Book compilation can be done locally in a properly set up environment. One can then upload the compiled website data to some web server for tests. Our production website is however compiled on the cloud and hosted on GitHub pages, as described above.

Setting up the local environment and editing the source

  1. Clone this repository:
git clone git@github.com:UTokyo-ICEPP/qc-workbook
  1. Create an isolated environment with anaconda or venv:
conda create -n qc-workbook python==3.12
conda activate qc-workbook

or

python -m venv qc-workbook
source qc-workbook/bin/activate

Then install Jupyter and the repository requirements:

pip install jupyterlab jupytext
pip install -r qc-workbook/build-runner/requirements.txt
  1. Start jupyter lab and edit the notebooks:
jupyter lab

The notebook files are under source/ja and source/en directories (for Japanese and English versions, respectively). Right-click on the file you want to edit, and select Open With > Notebook to display the Markdown file as a Jupyter notebook. To create a new Markdown notebook, open the Launcher tab (the big "+" button on top of the file explorer side bar) and select MyST Markdown at the bottom (under the heading "Jupytext").

Commit and push the files as necessary. We allow direct pushes to the UTokyo-ICEPP original repo.

  1. Compile and publish the updates: Go to the "publish" action in the Actions tab and click the Run workflow button. Select the master branch. Check the workflow status in the same page. If all goes well, your updates will be visible on the public website within a few minutes.

Clone this wiki locally