Git and Continuous Integration

Overview:

• Teaching: 10 min
• Exercises: 0 min

Questions

• How can I use continuous integration to deploy my lesson?

Objectives

• Learn which files exclude git repository
• Manage dependencies with requirements.txt
• Use travis to deploy a lesson as a webpage on github

.gitignore

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

Dependencies

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

Continuous Integration

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

Key Points:

• Use a gitignore to avoid local builds, checkpoints, bytecode files
• Use requirements.txt for the dependencies for your lesson
• For github with travis CI include a .travis.yml and set up your CI

Previous

Schedule

Next