# Documentation with Jupyter Books 101

Jupyter Book is a free python package that allows the user to generate an HTML or PDF version of a book by starting from a variety of files. Jupyter books can contain `.md` markdown files, `.ipynb` Jupyter notebooks, and `.bib` BibTeX bibliography files.

### Installing Jupyter Book

The jupyter book software can be installed directly from `pip` using the command:

pip install jupyter-book

or, for the anaconda users, directly from the `conda-forge` repository using the command:

conda install -c conda-forge jupyter-book

After the installation process the command `jupyter-book` should be accessible from the terminal.

### Creating a Jupyter Book

In order to create a working Jupyter Book project, two files must be created within a common folder: a configuration file named `_config.yml` and a table of content file `_toc.yml`.

The `_config.yml` file contains all the book configurations and information such as author and book name, the logo to be used throughout the book, and specific instructions on how to operate the provided interactive code cells, HTML, LaTeX, and Sphinx configurations and much more. The complete list of accepted arguments can be found in the [official documentation](https://jupyterbook.org/en/stable/customize/config.html).

A basic `_config.yml` file is reported in what follows:

title: The title
author: Your name
logo: logo.png
execute:
  execute_notebooks: force

The `execute_notebooks: force` instruction will ensure that all the interactive code cells will be executed at build time.

The `_toc.yml` file defines the structure of the book. In its basic form, the table of contents contains the starting page of the book (`root`) and all its chapters. More complex configurations are also possible and a full list of accepted commands and syntax can be found in the [official documentation](https://jupyterbook.org/en/stable/structure/toc.html).

A basic `_toc.yml` file is reported in what follows:

format: jb-book
root: my_main_page
chapters:
- file: my_first_chapter
- file: my_second_chapter

in which `my_main_page`, `my_first_chapter` and `my_second_chapter` must match the name of the chapter files available in the project directory.

A basic Jupyter Book project can be created automatically by running the command:

jupyter-book create mybook/

The command will create the project directory `mybook/` and a simple example project that can be edited by the user.

##### Adding code cells to a markdown file

Often it is convenient to embed code cells in a markdown file. This can be easily done by adopting the [MyST Markdown format](https://jupyterbook.org/en/stable/file-types/myst-notebooks.html). To do so, a preamble should be added to the file telling the interpreter to load the required code-executing kernel. An example suitable to be used with python is reported in what follows:

---
jupytext:
  formats: md:myst
  text_representation:
    extension: .md
    format_name: myst
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

Code cells can be created, and executed, marking the code cells as `{code-cell}`.

### Building a Jupyter Book

Once created, a jupyter book can be built directly in HTML format by running the command:

jupyter-book build mybook/

where `mybook/` represent the folder containing the project. The build process will create a `_build/html` folder inside the project folder in which all the required HTML files will be contained. By opening the `index.html` file, using the system browser, the book should be visible. The book can than be uploaded on any `http`-like server by copying the `html` folder content in the system-defined location.

If the book contains the documentation relative to a GitHub repository, it can be conveniently deployed using the integrated GitHub pages service. To do so, a `gh-pages` empty branch can be created and the content of the `html` folder can be directly copied into the branch root.

### Automatic documentation deploy using GitHub actions

If the documentation of a repository must be updated frequently, manually uploading a new build of the HTML book page on the `gh-pages` branch can be tedious. For this reason, an automatic building and deploy procedure is available using the built-in GitHub actions.

To do so, a properly formatted workflow file must be added under the `.github/workflows` directory to initialize a python environment, install the required dependencies, build the book and finally deploy the `html` directory to the `gh-pages` branch.

If, for example, the documentation of a repository is contained in a `docs/` folder under which a `requirements-doc.txt` file is nested:

├── docs
│   ├── _config.yml
│   ├── main_page.md
│   ├── requirements-doc.txt
│   ├── _toc.yml
│   └── <other documentation files>
├── LICENSE
└── README.md

the following build action can be used to automatically build and deploy the repository documentation to GitHub pages:

name: deploy-book

on:
  # Trigger the workflow on push to main branch
  push:
    branches:
      - main

# This job installs dependencies, build the book, and pushes it to `gh-pages`
jobs:
  build-and-deploy-book:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest]
        python-version: [3.8]
    steps:
    - uses: actions/checkout@v2

    # Install dependencies
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v1
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        pip install -r docs/requirements-doc.txt

    # Build the book
    - name: Build the book
      run: |
        jupyter-book build docs

    # Deploy the book's HTML to gh-pages branch
    - name: GitHub Pages action
      uses: peaceiris/actions-gh-pages@v3.6.1
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: docs/_build/html

where the `requirements-doc.txt` should contain at least the following requirements:

jupyter-book
matplotlib
numpy
ghp-import

In order to facilitate the creation of documentation with GitHub actions the `cookiecutter` [jupyter-book submodule](https://github.com/executablebooks/cookiecutter-jupyter-book) can also be used. The module can be installed using `pip` with the command:

pip install cookiecutter

and a working documentation repoitory can be generated, with interactive procedure, by running the command:

jupyter-book create --cookiecutter mybook/

Additional edits may be necessary to account for relative path in the repository.