Lab Session 7: Jupyter Book#

  • Statistics 159/259, Spring 2022

  • Prof. F. Pérez and GSI F. Sapienza, Department of Statistics, UC Berkeley.

  • 03/24/2023

Today we are going to construct and deploy our first Jupyter Book! This is an incredible tool that allow us to transform contents in our project such as Jupyter notebooks, markdown files and figures into html and pdf files that can be then shared or even hosted on the web. Even if you haven’t use it yet, you had been exposed to Jupyter Book during all the semester: the course website is the Jupyter Book generated from the site repository.

We are going to put in practice the concepts we had covered in Jupyter Book 101. A complete documentation of how to create your first book can be found in the Jupyter Book documentation. We recommend you to use these two to create the books for this lab and use the course website as a guide.

We recommend you to use Jupyter book both in the Hub and in the local installation you have in your machine. In this last case, check you have installed jupyter-book (either enter which jupyter-book or jupyter-book --help from the terminal).

1. Create your first Book#

We are going to follow step by step the example in create your first book. For now, we are going to create a book in our machine (Hub or local computer) and then we are going to add these files into a GitHub repository.

  1. Create a new sample book using the command jupyter-book create mynewbook/.This will create a new template folder with some basic files used to deploy the book. Explore each one of the configuration files, specially _toc.yml and _config.yml. All these are explained in the tutorial.

  2. Build your book. Do this both from the Hub and your local machine.

    1. If you are working in your local machine, you can simply execute jupyter-book build mynewbook/.

    2. If you are working from the Stat159 Hub, you have to run Sphinx manually. Check on the lectures notes for this.

  3. Explore the markdown and Jupyter notebook created in your book. They both explain the different elements you can include in them.

2. Add some extra features#

Let’s customize our new Jupyter Book a little bit. After each change, remember to re-build your book.

  1. Add a new image to your book and use it as the logo of the Jupyter book.

  2. Add a new reference to references.bib and cite such reference in either a markdown or Jupyter notebook in your book. Check that when deployed, the reference appears in the right format in the book. How to add more than one citation at once? You can explore the Get started with references.

  3. Create a new Jupyter notebook inside your book and add it to the table of contents so it appears in the book.

  4. In _config.yml, there is an option to enable and disable the execution of notebooks when the book is build. Change the setup such that it both creates and static version and then a dynamical version that actually executes the code in the notebook.

  5. In a notebook, make an import of new library that is not already included in requirements.txt and add it to it so the notebook runs when the book is build. What is the difference between this requirement.txt and the requirement file usually named environmnet.yml we were using before?

3. Publish your book online#

For this part, use the tutorial Publish your book online. All the instructions of how to create a new repository in GitHub with the contents of your book are included there plus and explanation about how the hosting of the Jupyter book works. After following these instructions, you should see your book hosted in https://<user>.github.io/<myonlinebook>/. Add this link to the description of your GitHub repository.

4. Continuous Integration to keep book updated#

You can use the previous workflow any time you update the contents of you book or instead you can set a GitHub action that does this for you any time you make a change in the book repository. You can explore different ways of doing this in GitHub Pages and Actions.

In order to create a new action, go to the Actions window in your GitHub repository and do New workflow >  set up a workflow yourself. Create a new file .github/workflows/book.yml with the same contents we have in book.yml file in the site repository. Notice that in the site we are using book-requirement.txt while the default name for the requirement file for Jupyter book is requirement.txt. In order to GitHub actions to run without an error, you should standardize the name of the requirement file.

Now, when you push or make a new commit to the repository your changes should be reflected in the website after the corresponded GitHub action has been completed without errors (you can see this in the Actions window in GitHub).