Building your book#
It is recommended that you first follow the steps outlined on the jupyterbook website starting from ‘overview’ through ‘create your own content file’ to get a feel for how a jupyter book is structured. In general, the Jupyterbook website is a useful reference.
Having familiarized yourself with the various files used in a jupyterbook, you can start creating your own book. We have prepared a template book you can use that preloads some of the necessary configurations in the _config.yml
file, please download it from here, fill it with your files and change the _toc.yml
accordingly.
On top of the files outlined in the steps on the Jupyterbook website: content, config and toc, the template book also contains a requirements.txt file. This file contains all the packages required to run the JB, including the Jupyter Books package itself. In order to build your book locally, you need to download these packages. It is recommended to download these packages into a closed environment to 1) prevent installation of the packages directly into your computer, cluttering it up and 2) ensuring that you have a clear overview of the packages your Jupyter Books require.
Create an environment#
In order to build your books, you have to create a closed environment for the necessary packages to be downloaded. There are several ways to achieve this. For the purpose of this tutorial, we will use a Conda environment.
First, navigate your command line to the root path of the book. Then, you can create and activate an environment by running the following commands (preferably one by one):
conda create --name=<env-name> python=3.7
conda activate <env-name>
conda install pip
pip install -r requirements.txt
In principle, the previous command will create and activate the environment. If something goes wrong, see if you can find a solution for the error messages online, or (if you cannot find a solution) contact the responsible department of TU Delft.
Delete an environment
If you want to remove an environment, run the following command:
conda remove --name <env-name> --all
Active environment#
Every time you want to build your build again, make sure you have the right environment activated by running the following command:
conda activate env-name
Deactivate an environment
If you want to deactivate an environment, run the following command:
conda deactivate <env-name>
Building your book locally#
Having installed all the necessary packages, you can now build the book locally by simply running the command:
jupyter-book build <book-path>
Which will generate your book as a fully functioning HTML website on your local computer. You can access it by navigating to that folder and opening it with your web browser.