Content creation and sharing#

These sections describe ways that you can create content for your JupyterHub and share them with your users.

Distribute content with nbgitpuller#

You’ll often want to distribute content (such as notebooks, scripts, sample data, etc) to your users so they can do exercises, follow along with a lecture, or use as a starting point for their own work. This content is often constantly updated as time goes on, and needs to not overwrite your student’s work if you make an adjustment to content that has already been touched by the student.

nbgitpuller is the tool we recommend for this. The workflow goes something like this:

Ensure that nbgitpuller is installed in your user environment#

The default environment for 2i2c JupyterHubs has nbgitpuller pre-installed. However, if you define a custom environment for your hub’s users, you’ll need to ensure that nbgitpuller is installed in order for users to use it!

Put your content in a public GitHub repository#

Create a repository on GitHub and start putting your content there. This is the source of the content that will be distributed to your users. You can update it as often as you wish. While instructors will need to know how github works, your users will never have to interact with git directly.

Serve static web content with your hub#

2i2c hubs can serve static web content as a JupyterHub service. This is useful for hosting documentation for your hub’s community.

The content of your static site should live in a .git repository as a collection of static HTML files, and the website for these files will be available at a URL like:

https://<hub-address>/services/docs

Follow these steps to set up documentation for your hub.

Create your static HTML files#

There are many ways to create your own static HTML files, and this guide doesn’t cover a specific method. Here are a few services you should try out:

  • Jupyter Book is a tool for building rich computational narrative sites from the Jupyter community.

  • Sphinx is a popular documentation engine in Python

  • Hugo is a popular static website generator that is flexible and fast.

Put the generated HTML into a github repository in a dedicated branch (so the branch should only contain the HTML files). Ensure that the HTML files contain relative links, not absolute links.

Tip

We highly recommend storing your source files in one branch, and automatically generating the HTML for your site via GitHub Actions. This way, your HTML files will automatically be updated when you update your site content.

Ask a 2i2c engineer to enable the documentation service for your hub#

Your hub will need to be configured by a 2i2c engineer to enable the docs service (following these instructions).

  • Find the GitHub repository and the branch where your HTML files are stored.

  • Send a support request asking them to enable this, and provide the repository/branch you found above.

Once this is deployed, your hub’s documentation should be accessible at

https://<hub-address>/services/docs

Write public books that connect to a 2i2c JupyterHub#

You can create public content that is designed to connect with your 2i2c JupyterHub. For example, you can create lectures from Jupyter Notebooks, and allow students to grab their own copy of the notebook to interact with on the 2i2c Hub.

To connect your public content with a 2i2c JupyterHub, we recommend using Jupyter Book. This is an open-source project that allows you to share collections of notebooks and markdown files as an online website and book. Check out the Jupyter Book getting started guide for more information about Jupyter Book.

You can tell Jupyter Book to place links directly to your 2i2c JupyterHub on each page that is served from a notebook. To do so, follow the launch buttons for JupyterHubs instructions. Make sure that you configure your jupyterhub_url to point to the URL of your 2i2c JupyterHub (e.g., https://<your-hub>.pilot.2i2c.cloud). This will use automatically create nbgitpuller links for you.