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