Contribute to our books

Contribute to our books#

py-edu-fr is based on few small websites for the trainings. For example, https://python-cnrs.netlify.app/edu/init is built from sources in the directories https://foss.heptapod.net/py-edu-fr/py-edu-fr/-/tree/branch/default/books/init and https://foss.heptapod.net/py-edu-fr/py-edu-fr/-/tree/branch/default/src/en (i.e. in our main repository containing the pedagogical content, https://foss.heptapod.net/py-edu-fr/py-edu-fr).

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

Install and build locally#

This assumes that you read Heptapod and Mercurial and followed the instructions. One also needs PDM, UV and make (see Development tools).

hg clone ssh://hg@foss.heptapod.net/py-edu-fr/py-edu-fr
cd py-edu-fr/books/init
# build the website
make

Once the book has been built, the sources are in the book directory (as symbolic links).

ls book
# modify the sources (with jupyter-lab or any editor)
# format and rebuild
make format html

Note

The notebooks are actually stored in the directory src at the root of the repository. However, it is equivalent to modify the files in the book directory.

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

On this page