Guide for Contributors#
This guide is for contributing content to the tutorials.
First, clone this repository.
With HTTPS:
git clone https://github.com/scientific-python/executable-tutorials
With SSH:
git clone git@github.com:scientific-python/executable-tutorials
Overview#
Each tutorial is a directory under tutorials/
. It may contain one or more
Markdown (.md
) files with a mixture of narrative text and code. Each tutorial
directory may also contain supporting data files, scripts, illustrations,
solutions to exercises, etc.
$ tree .
├── conf.py
├── contributing.md
├── index.md
├── tutorials
│ ├── executable
│ │ ├── basics.md
│ ├── matplotlib
│ │ ├── interactive_mpl.md
│ │ └── static_mpl.md
│ └── static
│ └── static.md
...
Some of these Markdown files include a header that describes how to convert them into Jupyter notebooks and execute the code in them. This is described in more detail below.
Setup#
We use the pixi package manager to create an environment with dependencies from conda-forge and PyPI. We recommend installing pixi. Then just:
pixi install
But if you have a strong preference for a different package manager, peek
inside pixi.toml
to find the list of dependencies and install them however
you wish.
Build#
pixi run build
Note
Later, if the build results get into a broken state, use pixi run clean
to start fresh.
This creates:
Executed notebooks, generated from eligible Markdown files, under
_build/juptyer_execute/
HTML under
_build/html/
Open _build/html/index.html
in a web browser.
Develop#
pixi run jupyter lab
In the file browser, locate one of the examples under tutorials/
. Double
click to open.
Files like tutorials/static/static.md
are plain Markdown files. Files like
tutorials/executable/basics.md
have a YAML header which enables the
documentation build system to convert them to Jupyter notebooks and execute
them:
---
jupytext:
text_representation:
extension: .md
format_name: myst
format_version: 0.13
jupytext_version: 1.16.4
kernelspec:
display_name: Python 3 (ipykernel)
language: python
name: python3
---
One option is to simply edit these files in any text editor.
Another is to use Jupyter Lab, which can open these files as notebooks enabling you the interactively edit and execute them, saving the changes to Markdown.
Note that the cell outputs are not saved to disk. This is a feature, not a bug: the outputs are build products, and they do not belong in version control. During the build process, the Markdown document is converted to a Jupyter notebook format and executed.
Test#
The script test.sh
runs files with executable code from top to bottom and
prints any unexpected tracebacks.
pixi run ./test.sh tutorials/executable/basics.md
Note
Sometimes examples are expected to raise an exception. These can be marked up with a “tag” like so. With that tag, the build and test procedures will pass over the exception.
```{code-cell} ipython3
:tags: [raises-exception]
1 / 0
```
To test all examples, run:
pixi run ./test.sh --all
(Above, the script automatically discovers all Markdown files which have that YAML header marking them as executable.)
Deploy#
Once changes are merged to the main
branch, the GitHub Actions Publish workflow will:
Publish HTML to this site.
Uploaded the executed ipynb notebooks as a GitHub Artifact (useful for debugging) as an Artifact associated with the workflow run.
Push to [the
notebooks
branch of this repository][notebooks-branch] a version where all Markdown Jupytext files have been converted to.ipynb
format, usingpixi run ./convert-all ipynb
. This is suitable for use in environments where users need to be handed Jupyter Notebook files directly, such as Google Colab.