Upgrade an Existing Book From Jupyter Book 1

Structure of a Legacy Book¶

Before we can upgrade a Legacy Book, we must first discuss its important files and structure.

Generating a Legacy Book¶

Jupyter Book 1 uses the Sphinx documentation engine to build each book into publication-quality books and documents. Sphinx was originally designed for documentation generation, such as https://docs.python.org, and has a long historical legacy. In order to hide the complexity that stems from making a documentation engine behave like a book authoring tool, Jupyter Book 1 introduced its own configuration files and CLI to build a book. Consequently, a Legacy Book is required to have a number of configuration files (see Table 1).

An example Legacy Book can be seen by running the legacy Jupyter Book create command:

$ jupyter book --version
Jupyter Book      : 1.0.2
External ToC      : 1.0.1
MyST-Parser       : 2.0.0
MyST-NB           : 1.1.1
Sphinx Book Theme : 1.1.3
Jupyter-Cache     : 1.0.0
NbClient          : 0.10.0

$ jupyter book create ./book
===============================================================================

Your book template can be found at

    book/

===============================================================================

If we inspect the contents of the generated book directory, it can be seen that a number of files have been created:

$ ls ./book
.
..
_config.yml
_toc.yml
intro.md
logo.png
markdown-notebooks.md
markdown.md
notebooks.ipynb
references.bib
requirements.txt

Configuration Files¶

The most important files in a Legacy Book are the _config.yml and _toc.yml files described in Table 1. These files control what a book contains and what it looks like.

# Book settings
# Learn more at https://jupyterbook.org/customize/config.html

title: My sample book
author: The Jupyter Book Community
logo: logo.png

# Force re-execution of notebooks on each build.
# See https://jupyterbook.org/content/execute.html
execute:
  execute_notebooks: force

# ...

# Table of contents
# Learn more at https://jupyterbook.org/customize/toc.html

format: jb-book
root: intro
chapters:
- file: markdown
- file: notebooks
- file: markdown-notebooks

Some advanced books may have chosen to stop using Jupyter Book’s configuration and use Sphinx directly. These books do not define a _config.yml, instead they utilise a Sphinx-style conf.py file.

Bibliography File¶

In addition to the configuration files, there is also a bibliography file called references.bib, which contains a list of references to academic publications.

@inproceedings{holdgraf_evidence_2014,
	address = {Brisbane, Australia, Australia},
	title = {Evidence for {Predictive} {Coding} in {Human} {Auditory} {Cortex}},
	booktitle = {International {Conference} on {Cognitive} {Neuroscience}},
	publisher = {Frontiers in Neuroscience},
	author = {Holdgraf, Christopher Ramsay and de Heer, Wendy and Pasley, Brian N. and Knight, Robert T.},
	year = {2014}
}

...

This file contains references written in the BibTeX File Format, which is well-understood by tools such as the LaTeX document preparation system that is used for PDF export.

Requirements File¶

Finally, a requirements.txt file is often used to define the Python packages required to build the book. This file is normally used both to install Jupyter Book (and related tools) and run any executable Python code.

jupyter-book
matplotlib
numpy

Structure of a New Book¶

Now that we know what a Legacy Book looks like, we can compare its structure with a New Book.

Configuration Files¶

The new Jupyter Book has a single configuration file myst.yml. See the Program 6 for the myst.yml that corresponds to Program 2.

version: 1
project:
  title: My sample book
  authors:
    - name: The Jupyter Book Community
  github: executablebooks/jupyter-book
  bibliography:
    - references.bib
  exports:
    - format: pdf
      template: plain_latex_book
      output: exports/book.pdf
  toc:
    - file: intro.md
    - file: markdown.md
    - file: notebooks.ipynb
    - file: markdown-notebooks.md
site:
  options:
    logo: logo.png
  template: book-theme

It can be seen that Program 6 has a toc section that looks very similar to Program 3. This style of defining a TOC is designed to be easier to read and write.

Bibliography File¶

Just like Jupyter Book 1, Jupyter Book 2 understands academic references defined in references.bib.

Requirements File¶

Neither Jupyter Book 1 and 2 do anything useful with a requirements.txt file, but it is useful when adding support for Binder connectivity.

Upgrading a Legacy Book¶

Whilst Jupyter Book 1 was built upon the Sphinx document engine, Jupyter Book 2 is built upon the MyST-MD engine. The reasons for this transition are outlined in . Unlike Jupyter Book 1, Jupyter Book 2 does not try to hide the fact that it is built on a different engine; MyST-MD is designed from the ground up to be good at technical writing, and the Executable Books team believe that it is both powerful and easy-to-use. As such, Jupyter Book 2 builds on top of MyST-MD, using the same CLI and myst.yml.

Jupyter Book will automatically upgrade a Legacy Book to a New Book by looking for the _config.yml file described in Structure of a Legacy Book. To do this, we need to run the new jupyter book command in the Legacy Book directory. Let’s try this tool with the example book given above.

First, let’s confirm that we’re now using the new Jupyter Book tool:

$ jupyter book --version

We can then run the jupyter book command, which will detect the Legacy Book and ask to perform an in-place upgrade:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
$ cd book
$ jupyter book
Welcome to the Jupyter Book (myst) CLI! 🎉 🚀

jupyter book init walks you through creating a myst.yml file.

You can use Jupyter Book (myst) to:

 - create interactive websites from markdown and Jupyter Notebooks 📈
 - build & export professional PDFs and Word documents 📄

Learn more about this CLI and MyST Markdown at: https://mystmd.org

? 📘 Found a legacy Jupyter Book. To proceed, myst needs to perform an upgrade which will:
‣ Upgrade any Sphinx-style glossaries to MyST-style glossaries
‣ Upgrade any case-insensitive admonition names to lowercase (Note → note)
‣ Migrate configuration from _config.yml and (if applicable) _toc.yml files
‣ Rename any modified or unneeded files so that they are hidden

Are you willing to proceed? (Y/n)

Pressing Y will start the upgrade process, during which time Jupyter Book reports the steps that take place, e.g. the lines highlighted in Program 8. For this particular book, the configuration files from the Legacy Book are migrated:

1
2
3
4
Are you willing to proceed? (Y/n) Yes
💾 Writing new config file: myst.yml
Migrating Jupyter Book configuration to myst.yml
Migrating TOC to myst.yml

We can see that the migration step has created some Hidden Files (see Program 9). This ensures that you can recover the original files if something goes wrong during the upgrade.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
$ ls -a
.
..
_build
._config.yml.myst.bak
intro.md
logo.png
markdown.md
markdown-notebooks.md
myst.yml
notebooks.ipynb
references.bib
requirements.txt
._toc.yml.myst.bak

Finally, Jupyter Book then asks us whether we’d like to run jupyter book start.

? Would you like to run myst start now?

We can press the y key in this terminal window to launch a MyST webserver. Clicking the generated link (or pasting it into a new browser tab) will allow us to preview our site and see changes quickly reflected in the browser (see Figure 1).