# 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.

```{image} https://jupyterbook.org/en/stable/_static/logo-wide.svg
:width: 50%
```

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](https://executablebooks.org/en/latest/gallery/))


```{figure} /assets/img/struct_build_book_html.png
:align: center
:width: 50%
```

Le contenu type d'un répertoire de travail pour construire un livre Jupyter est le suivant (répartoire disponible [ici](https://gitlab.dsi.universite-paris-saclay.fr/bruno.denis/intro_jupyter/-/tree/main/assets/monlivre) 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 :

```yaml
# 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.

```yaml
# 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 :

```bash
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é : <a href="../monlivre/_build/html/index.html">index.html</a>

La {numref}`jupyter_book_exemple` présente deux vues des pages générés. La visualisation se fait à l'aide d'un navigateur web.

```{figure} /assets/img/jupyter_book_exemple.png
:align: center
:width: 80%
:name: jupyter_book_exemple

Vues de deux pages html générées
```