Jupyter Book¶

Jupyter Book is a static page generator based on Sphinx – the documentation engine for Python. To get started with your first Prolog-infused Jupyter Book, clone the GitHub repository holding the source of this book (or your own fork or copy of the template) with

git clone https://github.com/simply-logical/prolog-book-template.git

Then, enter the book directory

cd prolog-book-template

before installing the dependencies and building the book.

Setup¶

To set up the environment we need to install two Python dependencies:

jupyter-book – the Jupyter Book platform; and
sphinx-prolog – our custom Prolog extension for Jupyter Book and Sphinx.

Jupyter Book is required in version 0.10.0 or higher, and Sphinx Python in version 0.5 or higher. You can install these dependencies manually with

pip install "jupyter-book>=0.10.0"
pip install "sphinx-prolog>=0.5"

or by using the requirements.txt file

pip install -r requirements.txt

Now, you can build the book by executing

jupyter-book build .

or

jb build .

for short. This will compose the HTML version of the book and place it in the _build/html directory. You can either open the _build/html/index.html file directly, or use the built-in Python HTTP server by executing

python -m http.server --directory _build/html

and then pointing your web browser to http://localhost:8000.

Configuration¶

The configuration of this Jupyter Book can be found in the _config.yml file. It holds the basic parameters and build options of the book. By default the build process will only copy the necessary files into the target directory (_build/html), which will then be deployed. To include auxiliary files needed for proper functioning of our GitHub Pages deployment, we need to list them under the sphinx.config.html_extra_path key in the _config.yml file.

sphinx:
  config:
    html_extra_path:
      - README.md
      - LICENCE
      - CNAME
      - .nojekyll

(While README.md and LICENCE are not necessary, they ensure a pleasant look of our gh-pages branch.)

Warning

When using this template, you should change the Google Analytics ID defined by the

  google_analytics_id: '261828628'

line (under the html key) in _config.yml or remove it altogether if you do not have your own Google Analytics token. Similarly, you should set the book repository URL to your own GitHub repository by amending the

  url: https://github.com/simply-logical/prolog-book-template

line found under the repository key.

See also

For more information about the _static directory see the official documentation.

Note

Additional important Jupyter Book configuration parameters are under the sphinx.extra_extensions and sphinx.config keys.

sphinx:
  extra_extensions:
    # Load sphinx-prolog <https://github.com/simply-logical/sphinx-prolog>
    - sphinx_prolog.infobox
    - sphinx_prolog.pprolog
    - sphinx_prolog.solex
    - sphinx_prolog.swish
  config:
    # Configure sphinx-prolog <https://github.com/simply-logical/sphinx-prolog>
    sp_exercise_directory: src/ex/
    sp_code_directory: src/code/
    sp_swish_url: https://swish.simply-logical.space/
    sp_swish_book_url: https://book-template.simply-logical.space/
    sp_swish_hide_examples: true

The first group loads external plugins – in particular, the four modules of our custom sphinx-prolog extension. The latter group configures Sphinx and its extensions – in our case, the behaviour of our extension. See the sphinx-prolog Extension section for more details.

Content¶

The book content is controlled by the _toc.yml file. It defines the part, chapter and section structure of the book, as well as their numbering and source paths. To improve the folder structure of the book template, all of the content building blocks are kept in the src directory:

src/img holds static images such as logos and favicons;
src/fig holds figures; and
src/text holds markdown files with the book text.

Note

The src directory holds two additional folders:

src/code with Prolog code snippets used to build interactive SWISH blocks and
src/ex with exercises and solutions content,

which are specific to our sphinx-prolog extension. They are discussed in more detail in SWISH Code and Query Blocks and Exercise and Solution Blocks sections respectively.

Interactive Prolog Book Example

Jupyter Book

Contents

Jupyter Book¶

Setup¶

Configuration¶

Content¶