diff --git a/docs/images/nbgitpuller/binder-progress.png b/docs/images/nbgitpuller/binder-progress.png new file mode 100644 index 0000000..bc5045b Binary files /dev/null and b/docs/images/nbgitpuller/binder-progress.png differ diff --git a/docs/images/nbgitpuller/blank-application.png b/docs/images/nbgitpuller/blank-application.png new file mode 100644 index 0000000..a02f87c Binary files /dev/null and b/docs/images/nbgitpuller/blank-application.png differ diff --git a/docs/images/nbgitpuller/filepath-application.png b/docs/images/nbgitpuller/filepath-application.png new file mode 100644 index 0000000..2871ce5 Binary files /dev/null and b/docs/images/nbgitpuller/filepath-application.png differ diff --git a/docs/images/nbgitpuller/git-url-application.png b/docs/images/nbgitpuller/git-url-application.png new file mode 100644 index 0000000..d1bc1f3 Binary files /dev/null and b/docs/images/nbgitpuller/git-url-application.png differ diff --git a/docs/images/nbgitpuller/hub-url-application.png b/docs/images/nbgitpuller/hub-url-application.png new file mode 100644 index 0000000..f3d5930 Binary files /dev/null and b/docs/images/nbgitpuller/hub-url-application.png differ diff --git a/docs/images/nbgitpuller/pull-progress.png b/docs/images/nbgitpuller/pull-progress.png new file mode 100644 index 0000000..e96c8cc Binary files /dev/null and b/docs/images/nbgitpuller/pull-progress.png differ diff --git a/docs/index.rst b/docs/index.rst index f736999..53bb96e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,6 +34,16 @@ Ubuntu 18.04. We have a bunch of tutorials to get you started. You should use this if your cloud provider does not already have a direct tutorial, or if you have experience setting up servers. +Tutorials +========= + +Tutorials guide you step-by-step through accomplishing a specific task. + +.. toctree:: + :titlesonly: + + tutorials/nbgitpuller.rst + How-To Guides ============= diff --git a/docs/tutorials/nbgitpuller.rst b/docs/tutorials/nbgitpuller.rst new file mode 100644 index 0000000..2545c69 --- /dev/null +++ b/docs/tutorials/nbgitpuller.rst @@ -0,0 +1,111 @@ +.. _tutorials/nbgitpuller: + +================================================ +Distributing materials to users with nbgitpuller +================================================ + +Goal +==== + +A very common educational need when using JupyterHub for education is to easily +distribute study materials / lab notebooks to students. + +Students should be able to: + +1. Easily get latest version of materials, including any updates the instructor + has made to materials the student already has a copy of. +2. Be confident they won't lose any of their work. If an instructor has modified + something the student has also modified, the student's modification should + never be overwritten. +3. Not have to deal with manual merge conflicts or other complex operations. + +Instructors should be able to: + +1. Use modern collaborative version control tools to author & store their + materials. This currently means using Git. + +**nbgitpuller** is a Jupyter Notebook extension that helps achieve these goals. +This tutorial will walk you through the process of creating a magic +nbgitpuller link that users of your JupyterHub can click to fetch the latest +version of materials from a git repo. + +Pre-requisites +============== + +1. A JupyterHub set up with The Littlest JupyterHub +2. A git repository containing materials to distribute + +Step 1: Generate nbgitpuller link +================================= + +#. The easiest way to generate an nbgitpuller link is to use the + `mybinder.org based application `_. + Open it, and wait for it to load. + + .. image:: ../images/nbgitpuller/binder-progress.png + :alt: Progress bar as the binder application loads + +#. A blank form with some help text will open up. + + .. image:: ../images/nbgitpuller/blank-application.png + :alt: Blank application to make nbgitpuller links + +#. Enter the URL to your hub under ``hub_url``. Include ``http://`` or + ``https://`` as appropriate. + + .. image:: ../images/nbgitpuller/hub-url-application.png + :alt: Application with hub_url filled out + +#. Enter the URL to your Git repository. This could be from GitHub, + GitLab or any other git provider - including the disk of the + server The Littlest JupyterHub is installed on. As you start + typing the URL here, you'll notice that the link is already + being printed below! + + .. image:: ../images/nbgitpuller/git-url-application.png + :alt: Application with git_url filled out + +#. If your git repository is using a non-default branch name, + you can specify that under ``branch``. Most people do not + need to customize this. + +#. If you want to open a specific notebook when the user clicks + on the link, specify the path to the notebook under ``filepath``. + Make sure this file exists, otherwise users will get a 'File not found' + error. + + .. image:: ../images/nbgitpuller/filepath-application.png + :alt: Application with filepath filled out + + If you do not specify a file path, the user will be shown the + directory listing for the repository. + +#. By default, notebooks will be opened in the classic Jupyter Notebook + interface. You can select ``lab`` under ``application`` to open it in the + `JupyterLab `_ instead. + +The link printed at the bottom of the form can be distributed to students +now! You can also click it to test that it is working as intended, +and adjust the form values until you get something you are happy with. + +Step 2: Users click on the nbgitpuller link +=========================================== + +#. Send the link to your users in some way - email, slack, post a + shortened version (with `bit.ly `_ maybe) on the wall, or + put it on your syllabus page (like `UC Berkeley's data8 does `_). + Whatever works for you :) + +#. When users click the link, they will be asked to log in to the hub + if they have not already. + +#. Users will see a progress bar as the git repository is fetched & any + automatic merging required is performed. + + .. image:: ../images/nbgitpuller/pull-progress.png + :alt: Progress bar with git repository being pulled + +#. Users will now be redirected to the notebook specified in the URL! + +This workflow lets users land directly in the notebook you specified +without having to understand much about git or the JupyterHub interface. \ No newline at end of file