diff --git a/HowTos/SharingYourNotebooks/SharingYourNotebooks.ipynb b/HowTos/SharingYourNotebooks/SharingYourNotebooks.ipynb index b07565b..17d1d6a 100644 --- a/HowTos/SharingYourNotebooks/SharingYourNotebooks.ipynb +++ b/HowTos/SharingYourNotebooks/SharingYourNotebooks.ipynb @@ -1,87 +1,136 @@ { "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ - "# How to share your notebooks with your students ?" + "# How to share your notebooks?" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This notebook describes the workflow you can adopt to work efficently on your notebooks with your colleagues, and how you can distribute them to your students.\n", "\n", + "`git` it is a version control system, designed to help team work on a set of shared files. There are two main uses of git:\n", + "1. Each member of the team can work on the files and send his/her changes to the files to a `git` server.\n", + "2. The `git` server can also be configured to allow a public read-only access to the files, allowing anyone to get a copy of the files." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Getting ready to use `git`\n", "**Note**: this notebook does not go into details on how to use `git`.\n", "\n", - "We recommand using a git server to store your work on your notebooks and to share them with colleagues and students.\n", + "We recommand using a `git` server to store your work on your notebooks and to share them with colleagues and students.\n", "\n", "![git server](Images/sharing_with_git.png)\n", "\n", "*figure: git server at the center of your workflow.*\n", "\n", - "\n", "# What git server should you use?\n", "\n", "There are many places around the web providing `git` services:\n", "\n", - "* EPFL's [`gitlab`](https://gitlab.epfl.ch/) - using your GASPAR account\n", "* EPFL's [`c4science`](https://gitlab.epfl.ch/) - using your GASPAR account\n", + "* EPFL's [`gitlab`](https://gitlab.epfl.ch/) - using your GASPAR account\n", "* [`github`](https://github.com/) - you need a `github` account\n", "\n", "While ![noto](../../Images/noto_inline_transparent.png) works perfectly with any of these `git` servers, we would like to stress out the fact that you should care about **where** in the the world your data is stored. By using EPFL's services you ensure your data stays in Switzerland and that your work will not be impacted by possible changes in the law on data protection.\n", "\n", "# Setting up your environment for working with git server\n", "\n", "## For public repositories\n", "\n", "Usually, once your `git` tool is installed on your personal computer (just like it is in ![noto](../../Images/noto_inline_transparent.png)), you are ready to go and you can clone right away any `git` public repository.\n", "Most public `git` repositories are read-only, meaning that you can not contribute back by sending the changes you made. To contribute (push your changes to the `git` server), you need to authenticate and ,of course, have write access on the `git` repository! (see next section)\n", "\n", "## Authenticating on a remote git server\n", "\n", "There are two ways to authenticate on a remote server: using a **username** and a **password** or to user **SSH keys**. While both methods will work from the command line (`git` command will ask your username and password), it is much more convenient to setup SSH keys: the `git` command will make use of your SSH keys and not ask for your password everytime and the `git` interface from Jupyterlab will be able to interact with the server.\n", "We recommend you take some time to set up SSH keys authentication - it not a long process and that will certainly speed up your \n", "\n", "Here are the required steps for having SSH keys authentication to work:\n", "\n", "* Make sure the remote URL of your git folder starts with `ssh://...`. When you clone and existing repository, use the `ssh://...` URL (not the `https://...` version).\n", "* Make sure your SSH keys on ![noto](../../Images/noto_inline_transparent.png) are ready (see the \"using git\" notebook in your Documentation directory)\n", "* Make sure you imported your public key over to your account on the remote server. On most `git` services, in your user's settings page, there is a place to add new SSH keys.\n", "\n", "This should be enough to have SSH key authentication working.\n", "Should you need to troubleshoot, the `jupyterlab-git` extension (then part that provide the JupyterLab integration with `git`) is unfortunately not really helpfull.\n", - "So, always give it a go in your Terminal for a more verbose feedback." + "So, always give it a go in your Terminal for a more verbose feedback.\n", + "\n", + "# Sharing your notebook repository\n", + "\n", + "On noto, you can use a mechanism called `nbgitpuller` (it *clones* or *pulls* your `git` repostory into the user's workspace and opens a notebook). This allows you to share your notebooks in a very convinient way: you distibute a link and anyone clicking this link gets to a specific notebook from your `git` repository.\n", + "\n", + "e.g.: as a teacher, you can publish a link to one of your notebooks in your course's Moodle page. Your students click and they get to the notebook directly.\n", + "\n", + "## Preparing and testing the `nbgitpuller` link\n", + "\n", + "In order to build the `nbgitpuller` link, you need to go to: [https://jupyterhub.github.io/nbgitpuller](https://jupyterhub.github.io/nbgitpuller/link?hub=https://noto.epfl.ch). Then you need to fill out the form with the following parameters (this example will point users to the COM303 course repository - adapt the parameters for *your* repository!):\n", + "\n", + "1. JupyterHub URL: https://noto.epfl.ch\n", + "1. Git Repository URL: https://github.com/prandoni/COM303-Py3 (<= without the '.git' extension !)\n", + "1. Branch: (none) (<= set this up as needed of leave blank)\n", + "1. File to open: DTMF/DTMF.ipynb (<= this is the path to your notebook inside your repository)\n", + "1. Application to Open: JupyterLab\n", + "\n", + "From the page, you will get a link similar to:\n", + "`https://noto.epfl.ch/hub/user-redirect/git-pull?repo=https%3A%2F%2Fgithub.com%2Fprandoni%2FCOM303-Py3&urlpath=lab%2Ftree%2FCOM303-Py3%2FDTMF%2FDTMF.ipynb`\n", + "\n", + "## Testing the link\n", + "By pasting the link in your web browser, you should get sent to the desired notebook.\n", + "**Note that is you already have an opened Noto session in your browser, jupyterlab will create a new session automatically.**\n", + "\n", + "## Choosing the `depth` of cloning\n", + "\n", + "By default, the entire history of the git repository is pulled in the user's workspace. This might be slow if your git repository is large or if a large number of students are going to pull at the same time. You can set this to 1 to pull only the latest commit on initial pull, like so:\n", + "\n", + "`https://noto.epfl.ch/hub/user-redirect/git-pull?repo=https%3A%2F%2Fgithub.com%2Fprandoni%2FCOM303-Py3&urlpath=lab%2Ftree%2FCOM303-Py3%2FDTMF%2FDTMF.ipynb&depth=1`\n", + "\n", + "(just by adding `&depth=1`)\n", + "\n", + "\n", + "## Sharing the link\n", + "\n", + "Once you are happy and ready to share your link, it is time to make it pretty! For that, open [go.epfl.ch](https://go.epfl.ch).\n", + "\n", + "`go.epfl.ch` is a URL shortening service. You can create there short and nice looking links that you will be able to distribute by email, your Moodle page, etc.\n", + "\n", + "It is also worth noting that you will get (basic but useful) statistics on your URLs, which is nice!" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "**End of the notebook**" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.6.8" } }, "nbformat": 4, - "nbformat_minor": 2 + "nbformat_minor": 4 }