Livre Jupyter

Contrairement aux convertions classiques des carnets Jupyter qui transforme un carnet en un autre document, le projet Jupyter Book propose de rassembler un ensemble de carnets en un livre unique cohérent.

A cette fin, Jupyter Book est le logiciel qui structure à la fois des carnets Jupyter et des fichiers texte en un « livre », c’est-à-dire

• un document au format latex ou pdf, ou

• des pages html faciles à héberger sur un site web statique (voir la galerie d’exemples)

Le contenu type d’un répertoire de travail pour construire un livre Jupyter est le suivant (répartoire disponible ici dans le dépôt git) :

monlivre/                 <- répertoire du libre
 │
 ├── _config.yml          )   fichiers de
 ├── _toc.yml             )  configuration
 │
 ├── intro.md             )
 ├── chap1.md             )  Contenu du livre,
 ├── chap2.ipynb          )  des carnets Jupyter
 ├── section2.1.md        )  ou des fichiers textes
 ├── section2.2.ipynb     )  (CommonMark,
 └── chap3.ipynb          )  MyST Markdown, ...)

Le fichier _toc.yml (table of content) organise le contenu en parties, chapitres, sections. Exemple :

# fichier _toc.yml
format: jb-book       # format du livre
root: intro           # page d'accueil du livre
chapters:             # une liste de chapitres va suivre
- file: chap1         # fichier qui contient les chapitre 1
- file: chap2         # fichier qui contient les chapitre 2
  sections:           # une liste de sections va suivre
  - file: section2.1
  - file: section2.2
- file: chap3         # fichier qui contient les chapitre 3

Le fichier _config.yml contient des informations et des directives pour l’application Jupyter Book. L’exemple minimal suivant fourni des informations pour la génération des hauts et des bas de page.

# fichier _config.yml
title:     Introduction à l'écosystème Jupyter
author:    Bruno DENIS (ENS Paris-Saclay)
logo:      https://jupyterbook.org/en/stable/_static/logo-wide.svg
execute:
  execute_notebooks: force

Pour générer le livre, il n’y a pas d’interface graphique utilisateur, il faut donc utiliser la ligne de commande. La génération type se fait par la commande suivante :

jupyter book build monlivre/

où monlivre est le chemin d’accès au répertoire qui contient le livre. Par défaut, Jupyter Book construit l’ensemble des pages html nécessaires pour le site web du livre. Les fichiers sont placés dans le répertoire _build/html

monlivre/
 └──_build
    └── html
       ├── _images
       ├── _static
       ├── index.html
       ├── intro.html
       ...

lien vers la page d’acceuil du livre généré : index.html

La Fig. 21 présente deux vues des pages générés. La visualisation se fait à l’aide d’un navigateur web.

Fig. 21 Vues de deux pages html générées