The course reader is a live webpage, hosted through GitHub, where you can enter curriculum content and post it to a public-facing site for learners.
To make alterations to the reader:
-
Run
git pull, or if it's your first time contributing, see the Setup section of this document. -
Edit an existing chapter file or create a new one. Chapter files may be either Markdown files (
.md) or Jupyter Notebook files (.ipynb). Either is fine, but you must remain consistent across the reader (i.e. don't mix and match filetypes). Put all chapter filess in thechapters/directory. Enter your text, code, and other information directly into the file. Make sure your file:- Follows the naming scheme
##_topic-of-chapter.md/ipynb(the only exception isindex.md/ipynb, which contains the reader's front page). - Begins with a first-level header (like
# This). This will be the title of your chapter. Subsequent section headers should be second-level headers (like## This) or below.
Put any supporting resources in
data/orimg/. - Follows the naming scheme
-
Run the command
jupyter-book build .in a shell at the top level of the repo to regenerate the HTML files in the_build/. -
When you're finished,
git add:- Any files you edited directly
- Any supporting media you added to
img/
Then
git commitandgit push. This updates themainbranch of the repo, which contains source materials for the web page (but not the web page itself). -
Run the command
ghp-import -n -p -f _build/htmlin a shell at the top level of the repo to update thegh-pagesbranch of the repo. This uses theghp-importPython package, which you will need to install first (pip install ghp-import). The live web page will update automatically after 1-10 minutes.
We recommend using conda to manage Python dependencies. The env.yaml file
in this repo contains a list of packages necessary to build the reader. You can
create a new conda environment with all of the packages listed in that file
with this shell command:
conda env create --file env.yaml