Merge pull request #73 from jupyterhub/nbgitpuller-doc-1

Add tutorial on how to use nbgitpuller

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
 =============
 

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 <https://mybinder.org/v2/gh/jupyterhub/nbgitpuller/master?urlpath=apps/binder%2Flink_generator.ipynb>`_.
+   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 <https://github.com/jupyterlab/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 <https://bit.ly>`_ maybe) on the wall, or
+   put it on your syllabus page (like `UC Berkeley's data8 does <http://data8.org/sp18/>`_).
+   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.