How to use "Jupyter Book" to create publication quality books and documents from .ipynb

What is Jupyter Book?

As the title suggests, "Jupyter Book" allows you to create beautiful publication-quality books and documents (HTML, PDF, etc.) from Jupyter Notebook files (.ipynb) and Markdown files (.md). ** The official reference for the URL is also created using the "Jupyter Book" **.

It's similar in name to Jupyter Notebook, but ** another **, one of the projects in "Project Jupyter" and "The Executable Book Project". As far as I could find, there was no Japanese reference, so I would like to give a brief introduction to the Jupyter Book.

Installation method

It's easy to install using pip. I'm using pip, Jupyter Lab and zsh on macOS, so I'll explain them with screenshots. This article is recommended for installing Jupyter Lab. First, start the terminal. スクリーンショット 2021-01-14 22.26.19.png Then install with the pip/conda command.

% pip install -U jupyter-book

スクリーンショット 2021-01-14 22.29.11.png

Basic commands

After installation, move to a directory of your choice and create a Jupyter Book project. Jupyter Book uses the jupyter-book or jb command. There is no difference between them, so we will use the short jb from now on.

jb create

Create a Jupyter Book project named "test_book" with jb create. You can change the project name. Although not used here, create can also add the --cookiecutter option.

% jb create test_book

A template Jupyter Book has been created in test_book /. スクリーンショット 2021-01-14 22.33.26.png

jb build You can build Jupyter Book with jb build.

% cd test_book
% jb build .

After a lengthy log is displayed, when the build is complete, you should see something like this: スクリーンショット 2021-01-14 22.35.50.png An HTML file has been created in test_book/_build/html. Let's display it with a browser such as Chrome. Type the HTML path directly into your browser or use a command like the one below.

% open /Applications/Google\ Chrome.app _build/html/index.html

You should see something like this: I was able to easily create a document. スクリーンショット 2021-01-13 21.09.46.png

Official demo book

An official demo book is also available. I personally recommend the option not to run at build time as it can cause errors at build time.

% git clone https://github.com/executablebooks/quantecon-mini-example
% cd quantecon-mini-example/mini_book
% cat _config.yml

Now rewrite execute_notebooks in _config.yml to"off". スクリーンショット 2021-01-14 22.40.49.png Let's build it and display it in the browser.

% jb build .
% open /Applications/Google\ Chrome.app _build/html/index.html

スクリーンショット 2021-01-14 3.01.12.png

Create a PDF

As with HTML, creating a PDF can be as easy. There are two methods, with some differences.

① How to create from a browser

When you view the HTML in your browser, there is a download button in the upper right corner. Click to specify the download format. You can save the PDF file by clicking .pdf. That's it. スクリーンショット 2021-01-14 16.44.38.png

② How to build and create

This method requires pyppeteer, so install it.

% pip install pyppeteer

Jupyter Book can also be built on a page-by-page basis. Let's convert notebook.ipynb in the test_book created earlier to PDF. Specify --builder pdf html at the time of build.

% cd test_book
% jb build notebooks.ipynb --builder pdfhtml

When the following is displayed, the PDF is complete. スクリーンショット 2021-01-14 22.43.26.png With this method, the bar displayed on the right side in ① was not displayed. スクリーンショット 2021-01-14 16.51.04.png Alternatively, you can create a ".tex" file or use $ \ LaTeX $ to create a PDF. See Official Reference PDF Page for more information.

Jupyter Book Customization

So far, I have introduced how to convert ".ipynb or .md" → "HTML or PDF". Here's how to change the page content and structure of the Jupyter Book. The code here is published on GitHub as we will discuss later, so if you want to copy it, please refer to it.

Add page

To add a page, add ".ipynb" or ".md" to the directory. Here, create "test_page.ipynb". For example, create it with the following contents. スクリーンショット 2021-01-15 23.32.30.png

_config.yml Edit _config.yml. This file describes the Jupyter Book settings. See the official reference config page (https://jupyterbook.org/customize/config.html) for more information. Here I edited title, author, and execute_notebooks. By the way, I added it at the bottom so that I can use the formula. スクリーンショット 2021-01-16 15.38.11.png

_toc.yml Edit _toc.yml. This file describes the structure of the Jupyter Book. See the official reference toc page (https://jupyterbook.org/customize/toc.html) for more information. Here, the page structure is as follows. スクリーンショット 2021-01-14 23.12.18.png If you build with this content, it will be displayed as follows. I was able to add pages and change the structure of the table of contents. スクリーンショット 2021-01-15 23.36.32.png

MyST Markdown

The Jupyter Book allows you to use an extended Markdown called MyST Markdown. Here, I will explain Directives and Roles, which are frequently used personally.

For normal Markdown, see Qiita official How to write Markdown. MyST Markdown also has Official Reference and Cheat Sheet, so be sure to check them out as well.

Directives Directives is a feature that allows you to create content blocks like the one at the bottom of the "test page" earlier. The format is as follows. スクリーンショット 2021-01-16 13.55.38.png Create a file called directives.md to introduce the types and formats. You can create a content block by writing:

admonition is a special format that allows you to freely set the title and class. In this example, : class: tip specifies the content block of tip.

If you specify code-block and the language, it will be displayed according to each language.

スクリーンショット 2021-01-15 0.32.01.png スクリーンショット 2021-01-16 14.06.02.png The content block looks like this. Here, in the content block, the word to be written in {} is written. Please note that if there is no content, an error will occur. スクリーンショット 2021-01-15 0.33.54.png スクリーンショット 2021-01-15 0.37.00.png If you specify {code-cell} instead of {code-block} and write JupytText at the beginning of the .md file, not only the code will be displayed but also the execution result will be displayed. can also do. It can also be nested. スクリーンショット 2021-01-16 14.02.35.png スクリーンショット 2021-01-16 15.40.34.png スクリーンショット 2021-01-16 15.41.23.png

There are many other formats, see the Jupyter Book MyST Markdown page (https://jupyterbook.org/content/myst.html) and the MyST Directives page (https://myst-parser.readthedocs.io/en/latest/using/syntax.html#directives-a-block-level-extension-point).

Roles

Roles, unlike Derectives, are written like this on one line. スクリーンショット 2021-01-16 14.01.16.png For example, you can display a check mark by writing the following. スクリーンショット 2021-01-16 14.17.31.png スクリーンショット 2021-01-16 14.18.30.png There are many other formats, see the MyST Roles page (https://myst-parser.readthedocs.io/en/latest/using/syntax.html#roles-an-in-line-extension-point).

Publication of Jupyter Book

Jupyter Book generates HTML so you can configure static websites. Here, let's publish the Jupyter Book using GitHub Pages.

Repository initialization

Create a new repository for Jupyter Book on GitHub. Please access the following page.

https://github.com/new

This time, I created a repository named test_book_online. Edit the repository part of _config.yml to change the link to the repository in Jupyter Book. スクリーンショット 2021-01-16 15.39.08.png Set up the repository from here. First, set the master branch with the following command. Replace your username and repository name with your own.

% cd test_book
% git init
% git add .
% git commit -m "adding my first book"
% git remote add origin https://github.com/<User name>/<Repository name>.git
% git push origin master

You have now set up the repository. Next, set up GitHub Pages using Python's ghp-import package. You don't need to run git branch gh-pages etc ** as ghp-import will automatically create a gh-pages branch.

% pip install ghp-import
% ghp-import -n -p -f _build/html

After a short wait, go to https: // <username> .github.io/<repository name> and you should see the contents of test_book. In my case, replace it with https://magolors.github.io/test_book_online.

I was able to publish it. If you like, I would be grateful if you could add Star ★ to the ** repository. ** You can jump to the repository from the GitHub mark on the upper right.

Repository update

If you want to update the source code of Jupyter Book, please execute as follows.

% cd test_book
% jb build .
% git checkout master
% git add .
% git commit -m "comment"
% git push origin master

If you want to update GitHub Pages, please do as follows. You don't need to run git checkout gh-pages **.

% cd test_book
% jb build .
% git checkout master
% ghp-import -n -p -f _build/html

In addition to this method, there is also a method called Automatically update GitHub Pages when Jupyter Book is updated using GitHub Actions.

Finally

So far, I have briefly introduced the Jupyter Book. There are so many other features besides the ones mentioned here, so be sure to check out the Official Reference (https://jupyterbook.org/index.html). Also, if there are other types of Directives or if you have any mistakes, please let us know in the comments.

Thank you for reading this far. If you find it interesting, please press LGTM and it will be encouraging: smile:

Recommended Posts

How to use "Jupyter Book" to create publication quality books and documents from .ipynb
How to use Jupyter Notebook
How to create and use static / dynamic libraries in C
How to use SWIG from waf
How to install and use Tesseract-OCR
How to use .bash_profile and .bashrc
How to install and use Graphviz
How to create a clone from Github
How to install and use pandas_datareader [Python]
[TF] How to use Tensorboard from Keras
How to use jupyter notebook with ABCI
python: How to use locals () and globals ()
Jupyter Notebook Basics of how to use
How to create a repository from media
How to use Python zip and enumerate
[Introduction to pytorch-lightning] How to use torchvision.transforms and how to freely create your own dataset ♬
How to use Jupyter notebook [Super Basic]
How to use is and == in Python
How to use pandas Timestamp and date_range
How to use lists, tuples, dictionaries, and sets
Introducing Sinatra-style frameworks and how to use them
How to create a function object from a string
How to create explanatory variables and objective functions
[Python] How to read data from CIFAR-10 and CIFAR-100
[Python] How to use hash function and tuple.
How to Git from GCP's Jupyter Lab to GSR
How to install Cascade detector and how to use it
How to use NUITKA-Utilities hinted-compilation to easily create an executable file from a Python script
How to create an article from the command line
How to use Keras ~ From simple model generation to CNN ~
Beginners! Basic Linux commands and how to use them!
How to use Azure Table storage from Django (PTVS)
How to use the grep command and frequent samples
How to instantly launch Jupyter Notebook from the terminal
Julia Quick Note [01] How to use variables and constants
[Python] How to create Correlation Matrix and Heat Map
How to use jupyter lab in Windows 10 local environment
How to use argparse and the difference between optparse
How to use Decorator in Django and how to make it
How to create a kubernetes pod from python code
How to use xml.etree.ElementTree
How to use Python-shell
How to use tf.data
How to use virtualenv
How to use Seaboan
How to use image-match
How to use shogun
How to use Virtualenv
How to use numpy.vectorize
How to use pytest_report_header
How to use partial
How to use Bio.Phylo
How to use SymPy
How to use x-means
How to use WikiExtractor.py
How to use IPython
How to use virtualenv
How to use Matplotlib
How to use iptables
How to use numpy
How to use TokyoTechFes2015