We use jupyterbook to create a condensed, single interface to all our course materials. This book will be autogenerated and published to [https://neuromatchacademy.github.io/course-content-dl] every time a pull request is merged into the main branch.
The Github workflow is defined in .github/workflows/publish-book.yaml.
In order to build the book locally, you will need to do the following:
- Install dependencies
pip install jupyter-book==0.10.2
Do not install jupyter-book 0.11 or later at this point, as there are breaking changes in how it handles the table of contents file we generate.
- Create a symlink in the book dir to the tutorials dir. From the repo root
directory (
course-content-dl):
ln -s ../tutorials book/tutorials
- Prepare repo for book building (assuming than
nmaciis placed in the same directory ascourse-content-dl)
python ../nmaci/scripts/generate_book_precourse.py
This will use the tutorials/materials.yml to create the _toc.yml file in the book directory. It will also be responsible for creating any additional markdown files or modifying any tutorial notebooks specifically for book generation.
No changes created by this script should be committed to the repo.
- Build the book
jupyter-book build book