Contribute to our books

Contribute to our books#

py-edu-fr is based on few small websites for the trainings. For example, https://py-edu-fr.pages.heptapod.net/py-edu-fr-init is built from the sources hosted here https://foss.heptapod.net/py-edu-fr/py-edu-fr-init.

To learn how to get the source locally and send changes, read Heptapod and Mercurial.

Install and build locally#

One needs to install PDM and make.

commands

make

Local build

make format

Format sources

make jupyterlab

Start Jupyter Lab

make lock

Relock dependencies

About Jupyter Book and notebooks saved in MySt Markdown#

These “books” are based on Jupyter Book.

Most other files in the book directory are written in MyST Markdown (extension .md) since we use the same extension for

  1. simple Markdown files with static content and

  2. notebooks containing Python cells (stored in MyST Markdown).

The notebooks start with a frontmatter like:

---
jupytext:
  formats: md:myst
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.16.7
kernelspec:
  display_name: Python 3 (ipykernel)
  language: python
  name: python3
---

and content input code cells like

```{code-cell} ipython3
for idx in range(4):
    print(idx, end=", ")
```

The output of notebooks is not saved in the .md files (which is a sane behavior for us). These notebooks are executed during the book build (with a cache).

Tip

Using Jupyter Lab and Jupytext, one can open and edit the .md files corresponding to notebooks as standard notebooks. Run make jupyterlab, right click on a .md notebook file and choose “Open With -> Notebook”.

This can be very useful to contribute to a notebook and to execute cells interactively during the training.