UC Davis DataLab
Fall 2023
Instructor: Nick Ulle <naulle@ucdavis.edu>
Maintainer: Nick Ulle <naulle@ucdavis.edu>
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:
Check in with the reader's current maintainer and notify them about your intended changes. Maintainers might ask you to open an issue, use pull requests, tag your commits with versions, etc.
Run git pull
, or if it's your first time contributing, see
Setup.
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 the chapters/
directory.
Enter your text, code, and other information directly into the file. Make
sure your file:
##_topic-of-chapter.md/ipynb
(the only
exception is index.md/ipynb
, which contains the reader's front page).# 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/
or img/
.
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
:
img/
Then git commit
and git push
. This updates the main
branch 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/html
in a shell at the top
level of the repo to update the gh-pages
branch of the repo. This uses
the ghp-import
Python 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