README.md 1.68 KB
Newer Older
Matthieu Boileau's avatar
Matthieu Boileau committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# nbcourse: publish your course based on Jupyter notebooks

## Features

`nbcourse` helps you building a static website to publish your course content in the form of jupyter notebooks (one notebook for one chapter).

Main features:

- all the configuration is described by a single `nbcourse.yml` file
- it is based on [doit](https://pydoit.org) in order to build efficently the html files
- chapters can be displayed in *preview mode* only so attendees can see the whole course program without being able to access content of the lessons to come
- notebooks can be:
    - rendered as static html files,
    - rendered as static reveal slideshows,
    - packaged with all their material in a downloadable archive,
    - compiled in a single pdf book using [bookbook](https://github.com/takluyver/bookbook)
- the theme can be easily customized (html files are templated using jinja)

See [this python course](https://mm2act.pages.math.unistra.fr/cours-python/) (in French) as an example.

## Installation

```bash
pip install nbcourse
```

## Usage

### Initiate an empty nbcourse project

```bash
nbcourse --init
```

### Configure your website

- Put your notebooks file in the `notebook/` directory
- Edit the `nbcourse.yml` file created by the `nbcourse --init` command.

### Build your website

```bash
nbcourse
```

Resulting files are in the `build/` directory.

### Get help

```bash
nbcourse --help
```

### Publish

Matthieu Boileau's avatar
Matthieu Boileau committed
56
Publishing with [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/) is as simple as adding a `.gitlab-ci.yml` file such as:
Matthieu Boileau's avatar
Matthieu Boileau committed
57
58
59
60
61
62
63
64
65
66
67
68

```yaml
pages:
  image: boileaum/jupyter
  script:
    - pip install nbcourse
    - nbcourse -n 5
    - mv build public
  artifacts:
    paths:
      - public
```