Questions
Objectives
requirements.txt
We use git
for version control, if you are not familiar then see our lesson or the Software Carpentry.
To keep our repository clean, we exclude certain files to accidentally adding them to our lesson repositories. Since we are using notebooks, we will probably need to exclude checkpoint files *.ipynbc
, bytecode __pycache__
, the rendered notebook and published directories by creating and adding a .gitignore
in the root of our repository:
**/.ipynb_checkpoints
**/__pycache__
nbfancy
html
If your lesson has specific dependencies you should include these in a requirements.txt
. This will ensure that they are available for the automated build, and make it clear to your users what libraries they need. Unlike using !pip install <my_favourite_library>
in a notebook. For instance we have tried to minimise the dependencies for nbfancy
so its requirements is:
ipython>=6
jupyter
Automatically building your lesson reduces administration time and also serves to check that everything is building correctly. There is a huge amount of documentation available, travis-ci is comprehensive and includes links to set up each aspect of the process. You will also need to set up tokens for automatic deployment to github pages.
You will need to create and add a .travis.yml
in the root of your repository, ours looks like:
dist: xenial
language: python
python:
- "3.7"
install:
- pip install -r requirements.txt
- pip install nbfancy
script:
- nbfancy init --include none
- nbfancy rerun
- nbfancy render
- nbfancy html
deploy:
provider: pages
repo: USER/lesson
target-branch: gh-pages
local-dir: gh-pages/html
github_token: $GITHUB_TOKEN
skip-cleanup: true
on:
branch: master
Note that if you don't want to rerun notebooks you should omit this line in script
. In your requirements we recommend not including nbfancy
as we have here as it is required to build the lesson, not by your students in the lesson (that is, unless you're writing your own nbfancy lesson) and you will need to change USER to your username.
For descriptions of the different componenets of the file it is best to check out the Travis CI documentation