This beginner-level "how-to" will help you build custom lessons on your local computer using The Jupyter Notebook, push them to GitHub, and then create a link to share with your workshop participants. This approach is suitable for a set of 1-3 workshops. If you are teaching an entire course, we recommend using Jupyter Book to create a course website.
Getting started with GitHub
We will use GitHub Desktop to synchronize our remote repository on GitHub.com to our local repository (on your local machine).
- Download the installer for GitHub Desktop
- Install the software
- If you're new to GitHub, choose "Create your free account." Otherwise, choose "Sign in to GitHub.com.
Clone the Constellate repository
- Choose "Clone a Repository from the Internet..."
- Select URL, then enter the following text in the "URL or username/repository" field:
https://github.com/ithaka/tdm-notebooks.git. Under "Local Path," enter the place on your computer where you would like your project files stored. The click "Clone." The files will automatically be copied from the ITHAKA repository to your local machine.
Choosing which files to include
Choose "Show in Finder" or "Show in file explorer" to show the local files.
If you are running 1-3 workshops, not developing a full course website using Jupyter Book, you may safely remove the following files.
Remove Jupyter Book files (optional)
You may optionally delete the following folders and files:
Files or folders that start with a "." are "invisible" files. To show them in the Apple Mac OS X Finder, press command-shift-period at the same time. On Microsoft Windows 10, select View > Options > Change folder and search options. Select the View tab and, in Advanced settings, select Show hidden files, folders, and drives and OK.
Remove Jupyter Notebook files (optional)
- Remove any notebook files (.ipynb) that you do not care to include in your workshops
Essential folders and files to keep
src/Contains the source code for the Constellate Client
.gitignoreContains a list of files to exclude from your repository such as invisible python and system files
README.mdA description of the repository. Feel free to change this to reflect your workshop. Please do give credit to Constellate for the original source.
requirements.txtA list of libraries that are installed automatically for users. Feel free to remove unneeded lines, but we recommend retaining
progressbarto retain full compatibility with the Constellate Client.
startNecessary for the Constellate Client.
Install Python and The Jupyter Notebook
The easiest way to accomplish this step is to install Anaconda. If your computer is older or you do not wish to use up significant hard drive space (~5 GB), you can install Python and The Jupyter Notebook using the instructions in Create a Course Website.
Create and edit your lessons
- Open the Anaconda Navigator and choose "Launch" under Jupyter Notebook. A tab will open in your browser containing The Jupyter Notebook which shows the filesystem on your local computer.
- Navigate to the folder where you cloned your repository.
- Open any Jupyter Notebooks (.ipynb) and modify them to your satisfaction. 4. Before saving, it is a good practice to clear all cell outputs under the file menu: Cell > All Output > Clear
- Save changes!
The process for running The Jupyter Notebook will also run in a terminal/command line window. If you close or interrupt this window, then The Jupyter Notebook will crash. The best approach is just to minimize the window so it is out of your way. You can safely close the window after you have finished editing and have saved all changes.
Fork the repository
- When you return to GitHub Desktop, you will discover that there are changes ready to be committed and pushed. In the lower-lefthand corner, choose "create a fork."
- Choose "Fork This Repository."
- And finally "For my own purposes."
Push changes to GitHub
- Write a short description of the changes that were made to the repository. Then commit to master.
- Then "Push origin."
Create Constellate Binder Link
- Return to GitHub.com on your browser and confirm the changes were successfully pushed to your remote repository.
- Visit the Constellate Binder link generator page and enter your GitHub repository URL, e.g. https://github.com/YOURUSERNAME/YOURREPONAME.
- Click the clipboard to copy the link to create your Binder session.
- Paste this link into another tab to test it.
The first time the Binder session is launched it may take some significant time to load as the environment is created. After it is created the first time, an image is cached and it should load significantly faster each subsequent time. If you have made significant changes to your repository, we recommend launching the Binder once ahead of time to make sure the image is cached and will load quickly for your workshop participants.
Specifying a particular file
You may open directly into a particular notebook file by specifying it in the "Path to a notebook file (optional)" field.
Specifying Main Branch
The Constellate Binder link generator will assume that your main branch is the "master" branch, but GitHub has recently changed the default name to "main" branch. If you're building a new repository from scratch, you may need to enter "main" under "Git branch, tag, or commit" to create the proper link.