Skip to content

Latest commit

 

History

History
69 lines (35 loc) · 2.29 KB

README.md

File metadata and controls

69 lines (35 loc) · 2.29 KB
Raw

Jupyterbook Support

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] in gh-pages branch, every time a PR is merged into the master branch.

The GitHub workflow is defined in .github/workflows/publish-book.yml.

In order to build the book locally, you will need to do the following:

  1. Clone course-content repo

git clone https://github.com/NeuromatchAcademy/course-content.git --depth=1

  1. Download nmaci repo (main branch)

wget https://github.com/NeuromatchAcademy/nmaci/archive/refs/heads/main.tar.gz

tar -xzf main.tar.gz; rm -rf main.tar.gz

  1. Download precourse repo (main branch)

wget https://github.com/NeuromatchAcademy/precourse/archive/refs/heads/main.tar.gz

tar -xzf main.tar.gz; rm -rf main.tar.gz

  1. Install dependencies

cd course-content

pip install -r ../nmaci-main/requirements.txt

pip install -r requirements.txt

pip install jupyter-book==0.10.2

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

  1. Copy files from precourse to tutorials/

mv ../precourse-main/tutorials/W0D* tutorials/

cat ../precourse-main/tutorials/materials.yml tutorials/materials.yml > out.yml

mv out.yml tutorials/materials.yml

mv ../precourse-main/prereqs/ .

  1. Create a symlink in the book dir to the tutorials dir. From the repo (i.e., course-content) root directory:

ln -s ../tutorials book/tutorials

ln -s ../projects book/projects

ln -s ../prereqs book/prereqs

  1. Prepare repo for book building

python ../nmaci-main/scripts/generate_book.py arg

where arg can take either student or instructor as a value.

This will use the modified 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.

  1. Build the book

jupyter-book build book

This will create a book/_build directory. You can open the index.html in any browser to verify the book.