Jupyter Book#

In this lectures we are going to cover another amazing tool of the Jupyter ecosystem: Jupyter Book.

eratosthenes

The Jupyter Book team has done a terrific job in documenting how to create, edit and deploy a Jupyter Book. For this lectures we are going to follow this documentation and add a few comments as we go thought it.

What is Jupyter Book?#

Jupyter Book allows grabbing a collection of notebooks, markdown files, etc intro an enriched explorable book or article that can be deployed online. JB is a tool that

  • Display notebook content in a more familiar, beautiful, and accessible form.

  • Focus on authoring,reading, and publishing.

  • Connect with interactive computation.

  • Community-driven, workflow- and vendor-agnostic.

1. Create a book#

If you are working in the Stat159 JupyterHub, your already have Jupyter Book installed. You can check this by entering

jupyter-book --help

in your terminal. If you are working in your local machine, you will have to install Jupyter Book.

Tip

You can use either jupyter-book or jb to call Jupyter Book. For example, you can run the previous command with

jb --help

You can create a minimalistic book with the following command

jupyter-book create mybook/

This will create a new folder with some basic contents that are required to create and deploy the book. Besides the content files of your book, there are two key files that together determine the structure and configuration of your book:

  • _toc.yml: Stands for table of contents. It is where we organize the contents of the books, having notebooks and markdown files organized by sections and chapters.

  • _config.yml: It’s the general configuration file. It includes different options, like if we want to execute the notebooks with the code within them every time we build the book (execute_notebooks).

You can take a look of how these two files look like in the repository that contains this book.

2. Build the book#

Once the book files had been configured correctly, we can just build the HTML files for the book with

jb build <BOOK PATH>

If you working directory is the home directory of the book, you can simply do jb build .. This will generate a static HTML version of the book inside the folder build/_html in your book home directory. If you are working in local, you can just open these files. If you are working in the cloud, you have to follow the next steps.

Warning

If we do this from the Star159 Hub, we won’t be able to open the html file. This is because we are logged in from the cloud server.

There are two different ways of opening your book html files in the Hub. The first one consists in opening a new Desktop tab from the JupyterLab launcher. This will open a virtual desktop from which you can open your html files.

An alternative way of doing this is by manually creating the book with sphinx:

jupyter-book config sphinx .

This will write a new file called conf.py in our book directory. This configuration files allow us to make the configuration in the cloud and trigger sphinx manually with this configuration file. Once we have this conf.py file, we do

sphinx-build  . _build/html  -D html_baseurl=${JUPYTERHUB_SERVICE_PREFIX}/proxy/absolute/8000

which builds the website that will be available trough a different address.

We can then see the Jupyter Book by running

cd _build/html
python -m http.server

and then heading to this URL https://stat159.datahub.berkeley.edu/user-redirect/proxy/8000/index.html.

Alternatively, you can open the display the book by opening a new Desktop from your Launcher in JupyterLab.

Once you are able to visualize your book, you are ready to start making edits and changes to both the contents and the configuration of the book.

Warning

When adding new files to the table of contents _toc.yml, you need to build the book with the extra flag --all.

3. Deploy you book online#

GitHub Pages allow us to host online websites and then publish our documentation online. This is exactly what Jupyter Book uses.

There are ways in you can integrate new changes using continuous integration supported by GitHub actions. We are going to put this in practice using Jupyter Book.