Set Up

To enable interactivity on webpages, nbinteract relies on the free Binder service. To configure Binder to run your webpages, we will create a GitHub repository which will also allow you to host your converted webpages publicly.

Creating an Account and Repo

To begin, visit https://github.com/ and create an account. If you already have an account, you should log in.

Then, create a new repo. You may do this using the GitHub UI or visiting https://github.com/new . Name the repo nbinteract-tutorial. If you'd like a different name, feel free to name it something else; just keep in mind that we will use this repo name in later parts of the tutorial.

Make sure your repo is public, and click the checkbox to initialize your repo with a README. Your page should look like:

Now, click on the Settings link for the repo near the top of the page, scroll down to the GitHub Pages section, and select the master branch as the GitHub pages source. Click the Save button to save your changes.

Now, any file you upload to this repo will have a public URL. For example, the README.md file in the repo has the following URL:

{username}.github.io/nbinteract-tutorial/README.md

Where {username} is replaced with your GitHub username. For example, if my username is SamLau95, my URL is:

SamLau95.github.io/nbinteract-tutorial/README.md

If you can visit that URL and the page contains text (and not a 404 error) you've set up your GitHub repo correctly.

Cloning Your Repo

Now, visit http://mybinder.org/ and paste in the URL to your repo. It should look like:

https://github.com/{username}/nbinteract-tutorial

Where {username} is replaced with your GitHub username.

Launch the Binder server to open Jupyter.

If you are working locally, you should instead run the following commands in your terminal:

# Clone the repo
git clone https://github.com/{username}/nbinteract-tutorial

# Move into the repo directory
cd nbinteract-tutorial

# Start Jupyter
jupyter notebook

Initializing nbinteract

Via the notebook interface, click on New -> Terminal. This should open a terminal prompt. Run the following commands:

# Installs nbinteract
pip install nbinteract

# Initializes nbinteract. When prompted, create a requirements.txt file. Since we aren't
# adding additional packages in this tutorial, re-run the command to finish initialization.
nbinteract init

git add -A
git commit -m "Setup nbinteract"
git push origin master

This initializes the nbinteract package and pushes the configuration files to GitHub.

If you are working locally, skip the pip install command above and run the remaining commands in your terminal.