diff --git a/HowTos/ShareNotebooks/0-ShareNotebooks-TableOfContents.ipynb b/HowTos/ShareNotebooks/0-ShareNotebooks-TableOfContents.ipynb index f95e520..a203d30 100644 --- a/HowTos/ShareNotebooks/0-ShareNotebooks-TableOfContents.ipynb +++ b/HowTos/ShareNotebooks/0-ShareNotebooks-TableOfContents.ipynb @@ -1,91 +1,89 @@ { "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "

How to share notebooks with students?

\n", - "

Table of contents

\n", + "

Table of contents

\n", "
    \n", - "
  1. Create a git repository on c4science
    2. \n", - "
  2. Access your repository from noto
    3. \n", - "
  3. Add your files to the repository
    4. \n", - "
  4. Share the repository with students on noto
    5. \n", + "
  5. Create a git repository on c4science
    6. \n", + "
  6. Access your repository from noto
    7. \n", + "
  7. Share the repository with students on noto
    8. \n", "
\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# How to share notebooks with students?\n", "\n", "Noto supports **notebook sharing through a tool called `git`**, which is specifically designed for:\n", - "* *working collaboratively* on notebooks,\n", - "* ensuring *no modification is ever lost* (version control).\n", + "* working collaboratively on notebooks,\n", + "* ensuring no modification is ever lost (version control).\n", "\n", - "With `git`, you can manage who can see or contribute to your notebooks and you can easily share them with students through a simple URL.\n", + "With `git`, you can manage who can see or contribute to your notebooks and you can easily **share them with students through a simple URL**.\n", "\n", "This tutorial will guide you through the steps necessary for creating your `git` repository, configure it adequately, populate it and then share it with your students. \n", "\n", "
\n", "\n", "
\n", " \n", "**This tutorial assumes that you know how to use `git`** and does _not_ go into details on how `git` works.
\n", "If you are not familiar with `git`, have a look at other resources on the web, for instance [this tutorial on how to share Jupyter Notebooks with `git`](https://reproducible-science-curriculum.github.io/sharing-RR-Jupyter/01-sharing-github/) and [these tutorials on how to use `git` in general](https://try.github.io/).\n", " \n", "
\n", "\n", "
\n", "\n", - "This tutorial includes 4 steps:\n", + "This tutorial includes 3 steps:\n", "
    \n", - "
  1. Create a git repository on c4science
    2. \n", - "
  2. Access your repository from noto
    3. \n", - "
  3. Add your files to the repository
    4. \n", - "
  4. Share the repository with students on noto
    5. \n", + "
  5. Create a git repository on c4science
    6. \n", + "
  6. Access your repository from noto
    7. \n", + "
  7. Share the repository with students on noto
    8. \n", "
\n", " \n", "After following this tutorial, this is the configuration in which you will be: \n", "\n", "\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", " Table of contents\n", "    |   \n", - " 1. Create a git repository on c4science >>>\n", + " 1. Create a git repository on c4science >>>\n", "
" ] } ], "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.9" } }, "nbformat": 4, "nbformat_minor": 4 } diff --git a/HowTos/ShareNotebooks/1-ShareNotebooks-CreateGitRepo.ipynb b/HowTos/ShareNotebooks/1-ShareNotebooks-CreateGitRepo.ipynb index b560dc6..6e7c9ca 100644 --- a/HowTos/ShareNotebooks/1-ShareNotebooks-CreateGitRepo.ipynb +++ b/HowTos/ShareNotebooks/1-ShareNotebooks-CreateGitRepo.ipynb @@ -1,183 +1,182 @@ { "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "

How to share notebooks with students?

\n", - "

Table of contents

\n", + "

Table of contents

\n", "
    \n", - "
  1. Create a git repository on c4science
    2. \n", - "
  2. Access your repository from noto
    3. \n", - "
  3. Add your files to the repository
    4. \n", - "
  4. Share the repository with students on noto
    5. \n", + "
  5. Create a git repository on c4science
    6. \n", + "
  6. Access your repository from noto
    7. \n", + "
  7. Share the repository with students on noto
    8. \n", "
\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# 1. Create a git repository on c4science\n", "\n", "The goal of this phase is for you to **create a git repository** and **set it up with the appropriate settings**, in particular for sharing notebooks with students.\n", "\n", "This is done in four very short steps:\n", "* [Log on your git server](#logon)\n", "* [Create a new git repository](#create)\n", "* [Configure access settings](#settings)\n", "* [Activate your repository](#activate)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 1.a. Log on your git server  \n", "\n", "**We recommend that you use the EPFL git server [c4science](http://c4science.ch).**
\n", "\n", "Of course, there are many othe `git` servers available around the internet, such as [GitHub](https://github.com/) for instance.\n", "While Noto 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. \n", "The main advantage of [c4science](http://c4science.ch) is that it is hosted on the EPFL campus, which is important for data protection concerns. \n", "\n", "The remaining of this page will guide you on how to setup your `git` repository on [c4science](http://c4science.ch).\n", "\n", "Log on http://c4science.ch using your EPFL Gaspar account.\n", "\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 1.b. Create a new git repository \n", "\n", "From the home page, go to the `Applications > Repositories` menu on the left pane, then click on `+ Create Repository` at the top right of the page.\n", "\n", "\n", "\n", "In the list of repository types, choose `Create Git Repository`.\n", "\n", "\n", "\n", "In the following form, **the only information you are required to provide is the `Name`** of the repository. This is the name that students will see as folder name when they will access your notebooks on Noto. \n", "We advise you to choose a short informative name such as the code or name of your course for instance (e.g. `COM303-19-20` or `HeatTransfer`). It is important to **avoid spaces**. You can use characters such as `-` or `_` in replacement, or put upper case letters at the beginning of each word to separate them. \n", "\n", "Click on the `Create Repository` button. \n", "\n", "\n", "\n", "Your repository is now created. \n", "**An essential next step is to configure WHO can access your repository.** Then you will be ready to activate your repository." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 1.c. Configure access settings \n", "\n", "In the left menu, click on `Policies`.\n", "\n", "\n", "\n", "Then click on `Edit Policies` on the right side of the window.\n", "\n", "\n", "\n", "There are three types of policies:\n", "* `Visible To`: defines who can see and access your notebooks (without being able to modify them).\n", "* `Editable By`: defines who can manage the repository i.e. change settings such as the access policies.\n", "* `Can Push`: defines who can modify the notebooks and other files inside the repository i.e. contribute to notebooks.\n", "\n", "By default, these policies are all set to `Repository Author`, which means only you can see, manage and modify notebooks. \n", "We recommend you to change the following settings, depending on your needs.\n", "\n", "

For allowing students to access your notebooks without being able to modify them:

\n", "\n", "You should set the **`Visible To` parameter to `Public (No Login Required)`**. \n", "This means that students (as well as anyone else) can see your notebooks, which is **essential for sharing them**.\n", "On the other hand, they will not be able to modify your version of the notebooks (they can still modify their own local copy, without impact on yours).\n", "\n", "

If you want other teachers and teaching assistants to be able to contribute to your notebooks:

\n", "\n", "First make sure that these persons have an account on [c4science](http://c4science.ch).
\n", "Then **modify the `Can Push` setting**:\n", "* Either create a `Custom Policy` listing all the persons who can contribute to your notebooks - see screen capture below. \n", " **/!\\ Watch out:** do not forget to **add yourself** to your `Custom Policy`, otherwise you will not be able to push your own modifications...\n", "* Or create a `Project` which groups persons contributing to your notebooks, and then give the `Can Push` access to all members of the project. \n", "\n", "\n", "\n", "\n", "\n", "\n", "Click on `Save Changes`. You are now ready to **activate your repository**." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 1.d. Activate your repository  \n", "\n", "In the left menu, click on `Basics`.\n", "\n", "\n", "\n", "Then in the right pane, click on `Activate Repository`.\n", "\n", "\n", "\n", "A popup like the one below should appear, click on `Activate Repository`.\n", "\n", "\n", "\n", "The status of your repository will now be `Waiting For Update`. You should now **wait for a few seconds** then refresh the page. The status should **switch to `Updates OK`**. If not, wait a few more minutes.\n", "\n", "\n", "\n", "\n", "Once the status is set to `Updates OK` (all status indicators should be green), then you are ready to **clone and initialize your repository in Noto !**" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", - " <<< Table of contents\n", + " <<< Table of contents\n", "    |   \n", " 1. Create a git repository on c4science\n", "    |   \n", - " 2. Access your repository from noto >>>\n", + " 2. Access your repository from noto >>>\n", "
" ] } ], "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.9" } }, "nbformat": 4, "nbformat_minor": 4 } diff --git a/HowTos/ShareNotebooks/2-ShareNotebooks-ConnectGitNoto.ipynb b/HowTos/ShareNotebooks/2-ShareNotebooks-ConnectGitNoto.ipynb index 8bf74c3..9141e7a 100644 --- a/HowTos/ShareNotebooks/2-ShareNotebooks-ConnectGitNoto.ipynb +++ b/HowTos/ShareNotebooks/2-ShareNotebooks-ConnectGitNoto.ipynb @@ -1,377 +1,376 @@ { "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "

How to share notebooks with students?

\n", - "

Table of contents

\n", + "

Table of contents

\n", "
    \n", - "
  1. Create a git repository on c4science
    2. \n", - "
  2. Access your repository from noto
    3. \n", - "
  3. Add your files to the repository
    4. \n", - "
  4. Share the repository with students on noto
    5. \n", + "
  5. Create a git repository on c4science
    6. \n", + "
  6. Access your repository from noto
    7. \n", + "
  7. Share the repository with students on noto
    8. \n", "
\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# 2. Access your repository from noto\n", "\n", "The goal of this phase is for you to **access your git repository from noto**. This is particularly useful to edit your notebooks without installing anything on your computer, but also (and maybe more importantly) it allows you to **test how your notebooks will behave for students** since they will mostly use your notebooks in noto.\n", "\n", "In addition, we provide you with **template files** for initializing your repository with all the necessary information (licence, etc.).\n", "\n", "This is done in a few short steps:\n", "* [Setting up your credentials](#2.a.-Setting-up-your-credentials)\n", "* [Cloning your repository on noto](#2.b.-Cloning-your-repository-on-noto)\n", "* [Adding template files to your repository (optional)](#2.c.-Adding-template-files-to-your-repository-(optional))\n", "* [Doing your first commit and push with git](#2.d.-Doing-your-first-commit-and-push-with-git)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 2.a. Setting up your credentials\n", "\n", "When sending changes to your git repository from noto (push), you will have to authenticate yourself on c4science. To avoid having to type in your user identifier and password on noto each time you want to commit changes you have made to your notebooks, the simplest option is to use an **authentication key**. \n", "The idea is that noto will generate such a key for you, and then you have to configure your account on c4science so that it recognizes this key and authentifies you without asking for a password. \n", "\n", "### Generate your authentication key.\n", "\n", "**Execute the following cell to get your authentication key from noto**." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# Utility function to display the authentication key in green\n", "function show_ssh_key {\n", " echo -en ${Green}\n", " cat /home/.ssh/id_rsa.pub\n", " echo -en ${NoColor}\n", "}\n", "\n", "# We test if a key already exists. If yes, then it will just display it. If no, then it will first create the key and then display it.\n", "if [ -r /home/.ssh/id_rsa.pub ]; then\n", " echo \"Your SSH public key file is: /home/.ssh/id_rsa.pub\"\n", " echo \"Here is the public key you need to export to your remote git server:\"\n", " show_ssh_key\n", "else\n", " echo \"It looks like you don't have an SSH key pair yet. Creating one for you:\"\n", " mkdir -p /home/.ssh\n", " ssh-keygen -q -b 2048 -t rsa -N '' -f /home/.ssh/id_rsa\n", " show_ssh_key\n", "fi" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "**Copy the part in green** in the output above: this is your authentication key." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Register your authentication key on c4science\n", "\n", "Now you need to go on http://c4science.ch and log in to register this authentication key. \n", "Once logged on, go to the `Settings` menu from the top right toolbar.\n", "\n", "\n", "\n", "In the list of settings on the left pane, choose `SSH Public Keys`.\n", "\n", "\n", "\n", "To add a new authentication key, click on the dropdown menu `SSH Key Actions` on the right side of the window and then choose `Upload Public Key`.\n", "\n", "\n", "\n", "In the upload form, provide a `Name` for your key (for instance \"noto-key\") and then **paste your authentication key (green text in the output above)** and click on `Upload Public Key`.\n", "\n", "\n", "\n", "You should now see a new key (e.g. named \"noto-key\") in your list of public keys. \n", "This means that you are now authentified automatically on your git repository each time you are on noto." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Setting up your name and email\n", "\n", "The last thing to do is to set up your **full name** and **email address** so that anytime you make changes on your repository from noto, those changes get tagged with your name and email address. \n", "\n", "First, execute the following cell to see how things are currently configured." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# Display the name and email address as they are now set up\n", "git config --global user.name\n", "git config --global user.email" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If the above cell **displays no output** (this means that your name and email address are not yet set up) or if you are not happy with the current settings, change the values in the cell below**, then execute it**. It will display your name and email as they will now appear when you commit changes on your git repository from noto." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# Set the name and email address on git /!\\ CHANGE THE VALUES in red BEFORE EXECUTING\n", "git config --global user.name \"CHANGE Your Name Here\"\n", "git config --global user.email \"CHANGE your.email@address.here\"\n", "\n", "# Display the name and email address as they are now set up\n", "git config --global user.name\n", "git config --global user.email" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 2.b. Cloning your repository on noto\n", "\n", "Now that your credentials are set up, you are ready to **clone your git repository in your personal workspace on noto**.\n", "\n", "### Get the cloning URL from c4science\n", "\n", "First you need to **get the cloning URL** of your git repository on c4science. \n", "For this, go back to the welcome page of c4science (e.g. by clicking on the following link: [http://c4science.ch](http://c4science.ch)), then go to the `Applications > Repositories` menu on the left pane.\n", "\n", "Find your repository in the list and click on it. \n", "In the page displaying the current content of your repository (which is empty for now), click on the `Clone` button.\n", "\n", "\n", "\n", "In the form which appears, **copy the second URL** (the one starting with `ssh://...`).\n", "\n", "" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Clone the repository in noto\n", "\n", "**In noto** (i.e. in this window) you can now clone your repository. \n", "Make sure to **place yourself in the folder where you want your repository cloned**, by using the navigation in your workspace explorer (left pane of this window).\n", "\n", "Once you are at the right place, click on the `Git Clone` icon (diamond shape with a small `+` on the side). \n", "\n", "\n", "\n", "**Paste the cloning URL** from c4science in the form and click on `Clone`.\n", "\n", "\n", "\n", "After a few seconds, you should see a folder with the same name as your repository appear in your workspace. \n", "**You are now ready to work with your repository on Noto!**" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 2.c. Adding template files to your repository (optional)\n", "\n", "We provide you with **the following template files:**\n", "* `.gitignore`: to avoid saving temporary files into your git repository ([more information here](#gitignore))\n", "* `README.md`: description of your git repository for other users, search engines, etc. ([more information here](#readme))\n", "* `LICENSE.md`: description of the licence under which you make your content available to others ([more information here](#license))\n", "* and a first notebook, as an example\n", "\n", "You can find a more detailed description of the role and content of each of these files [below](#gitignore).\n", "\n", "To install these template files into your repository:\n", "1. **Download** the following zip file on your computer (if the link doesn't work, you can find this zip file inside the \"docs\" folder in the left pane: simply right-click on it to dowload it)\n", "2. **Upload** the zip file into your repository: simply drag-and-drop the zip file over your JupyterLab workspace into the corresponding folder\n", "3. **Unzip** the file: right-click on it and select \"Extract Archive\" in the contextual menu, as shown in the screen capture below\n", "\n", "\n", "\n", "4. **Delete** the zip file since you don't need it anymore\n", "5. **Edit** the different template files so that they correspond to your needs" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 2.d. Doing your first commit and push with git\n", "\n", "You are now ready to **make your first commit and push with `git`**. \n", "\n", "We recommend that you do this **using the command line** to avoid a known bug in the `git` graphical interface of JupyterLab. After this first interaction with your git server, you will be able to use the graphical interface of JupyterLab without any issue. \n", "\n", "Here is how to proceed:\n", "\n", "1. First, open your repository in a git terminal, as shown on the screen capture below:\n", "\n", "\n", "\n", "2. Then type the following two commands **one after the other** in the terminal:\n", "\n", "``` bash\n", "git commit -am \"Initialization of the repository\"\n", "git push\n", "```\n", "\n", - "These commands are meant to first commit all the changes you have made to your repository, then push the changes to your git server. \n", - "The execution of the last command should result in a message similar to the following:\n", - "\n", - "```\n", - "Counting objects: 4, done.\n", - "Delta compression using up to 16 threads.\n", - "Compressing objects: 100% (4/4), done.\n", - "Writing objects: 100% (4/4), 417 bytes | 139.00 KiB/s, done.\n", - "Total 4 (delta 2), reused 0 (delta 0)\n", - "To ssh://c4science.ch/diffusion/10288/notouserdoc.git\n", - " fd05541..0560bc3 master -> master\n", - "```" + "These commands are meant to first commit all the changes you have made to your repository, then push the changes to your git server. \n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "\n", - "That's it! **Your git repository is now ready to be used from Noto**!
\n", - "If you know how to use `git` from the command line then you are all set. You can jump to the last part of the tutorial on how to share your notebooks with students on Noto.
\n", - "Otherwise, you can learn about the `git` graphical interface included in JupyterLab in the following page of the tutorial.\n", + "That's it! **Your git repository is now ready to be used from Noto**!\n", + "\n", + "You can use `git` from the command line as illustrated just above, but note that there is also a graphical interface accessible by the menu on the left of your personal workspace as illustrated below (or you can use the `git` menu at the top and select \"Git Interface\"). \n", + "\n", + "\n", + "\n", + "You can now jump to the last part of the tutorial on how to share your notebooks with students on Noto.\n", "\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", - " <<< 1. Create a repository on c4science\n", + " <<< 1. Create a repository on c4science\n", "    |   \n", " 2. Access your repository from noto\n", "    |   \n", - " 3. Add your files to the repository >>>\n", + " 3. Share the repository with students on noto >>>\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "\n", "# Appendix: details on the provided template files" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "

Role of the .gitignore file

\n", " \n", "Jupyter and Python produce temporary files all the time, for instance to save the temporary state of a notebook (see [this page for a more detailed explanation](https://www.dataquest.io/blog/jupyter-notebook-tutorial/#saveandcheckpoint)). \n", "These files are very useful for yourself, in your own environment, but they are useless for other users and saving them in your git repository will take space for nothing.\n", "\n", "Therefore it is best to configure git so that these **temporary files are ignored** when you commit changes to your git repository. This is done by adding a hidden file called `.gitignore` to your repository and describing in this file which rules to use to exclude temporary files. Therefore, the `.gitignore` file is meant to be a list of files that git should not track. It resides at the root directory of your repository.\n", "\n", "The `.gitignore` file we provide you with has the following content:\n", "\n", "```\n", "**/.ipynb_checkpoints\n", "**/__pycache__\n", "```\n", "\n", "The first line excludes the temporary files created by Jupyter. \n", "The second line excludes compiled Python files." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "

Role of the README.md file

\n", "\n", "The advantage of having a git repository is that people will be able to find your notebooks online through a simple web search. However, visualizing notebooks online is not easy and so it is best to **provide the public (and search engines) with readable information about what your notebooks are about**. This is the role of the `README.md` file, which name is standardized so that anyone including search engines can understand that it contains the description of the repository contents.\n", "\n", "A `README.md` file is a simple text file in which you can use the `Markdown` syntax to format text, just as in notebook text cells. You can edit this file in noto simply by double clicking on it, or you can use your favorite text editor (e.g. Notepad++, iMacs, etc.). \n", "\n", "The content of the file itself is not standardized so you can basically put anything that you want in it. The template file that we provide you with, which you can see [by clicking here](docs/README.md), contains the following sections: \n", "\n", "* project short description with names of contributors\n", "* copyright and license information (with link to the `LICENSE.md` file described below)\n", "* table of contents\n", "\n", "Once added to your repository, the `README.md` file will be displayed on the public page of your repository on c4science, as illustrated below.\n", "\n", "\n", "\n", "You may also want to add other sections to your`README.md` file, such as:\n", "* credits and acknowledgements, with links to resources you have used\n", "* software dependencies (including specific versions of important libraries)\n", "* installation instructions" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "

Role of the LICENSE.md file

\n", "\n", "The `LICENSE.md` file is maybe the most important of the template files we provide with the initialization of your repository. Its role is to **state under which conditions you are sharing your notebooks** and more generally the content of your git repository.\n", "\n", "Since notebooks contain both text (and potentially other media) and code, you should indicate how each type of content is distributed. \n", "We advise to use **open licenses** for both:\n", "* For text and other web media, we suggest to use the [*Creative Commons License CC-BY 4.0*](https://creativecommons.org/licenses/by/4.0/deed.en): \n", - "* For code, we suggest to use the [*3-Clause BSD license*](https://en.wikipedia.org/wiki/BSD_licenses#3-clause_license_(%22BSD_License_2.0%22,_%22Revised_BSD_License%22,_%22New_BSD_License%22,_or_%22Modified_BSD_License%22)) \n", + "* For code, we suggest to use the [*3-Clause BSD license*](https://en.wikipedia.org/wiki/BSD_licenses#3-clause_license_(%22BSD_License_2.0%22,_%22Revised_BSD_License%22,_%22New_BSD_License%22,_or_%22Modified_BSD_License%22))\n", "\n", "The licence template file that we provide you with, which you can see [by clicking here](docs/LICENSE.md), contains both licenses. \n", "Of course, there are many other types of licenses that you can use and you can modify the LICENSE.md file as you wish." ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] } ], "metadata": { "kernelspec": { "display_name": "Bash", "language": "bash", "name": "bash" }, "language_info": { "codemirror_mode": "shell", "file_extension": ".sh", "mimetype": "text/x-sh", "name": "bash" }, "toc-showmarkdowntxt": false }, "nbformat": 4, "nbformat_minor": 4 } diff --git a/HowTos/ShareNotebooks/3-ShareNotebooks-ShareURL.ipynb b/HowTos/ShareNotebooks/3-ShareNotebooks-ShareURL.ipynb index 0aae8ca..e979954 100644 --- a/HowTos/ShareNotebooks/3-ShareNotebooks-ShareURL.ipynb +++ b/HowTos/ShareNotebooks/3-ShareNotebooks-ShareURL.ipynb @@ -1,181 +1,180 @@ { "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "

How to share notebooks with students?

\n", - "

Table of contents

\n", + "

Table of contents

\n", "
    \n", - "
  1. Create a git repository on c4science
    2. \n", - "
  2. Access your repository from noto
    3. \n", - "
  3. Add your files to the repository
    4. \n", - "
  4. Share the repository with students on noto
    5. \n", + "
  5. Create a git repository on c4science
    6. \n", + "
  6. Access your repository from noto
    7. \n", + "
  7. Share the repository with students on noto
    8. \n", "
\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# 4. Share the repository with students on noto\n", "\n", "You are now ready to share notebooks from your repository with students.
\n", "In the following, you will learn how to **generate a simple URL link** that you can share with students so that they are able to **view and execute your notebooks on Noto**. \n", "\n", "
\n", "\n", "
\n", " \n", "The method we describe in this tutorial **works with anyone being able to log on Noto**, i.e. all EPFL members and all members of universities with [Switch-AAI authentication](https://www.switch.ch/aai/participants/homeorgs/) (e.g. UNIL, ETHZ, UniGE, HEP-VD, etc.).
\n", "If you want to share your notebooks with people **outside of these organizations**, you should look for alternative ways of sharing such as with [MyBinder](https://mybinder.org/) for instance. \n", " \n", "
\n", "\n", "
\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 4.a. Check access rights on your git repository\n", "\n", "Before going any further, you should check that your git repository has **public reading access**.
\n", - "If you have followed the indications from [step 1 of this tutorial](1-SharingNotebooks-CreateGitRepo.ipynb) on how to create your repository on c4science this should already be the case. \n", + "If you have followed the indications from [step 1 of this tutorial](1-ShareNotebooks-CreateGitRepo.ipynb) on how to create your repository on c4science this should already be the case. \n", "Otherwise, we advise you to set the access rights accordingly." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 4.b. Creating a shareable link\n", + "## 4.b. Create a shareable link\n", "\n", "The method we describe in this tutorial uses a tool called `nbgitpuller` which generates shareable URL links. When clicked, a `nbgitpuller` link will automatically do the following for your students:\n", "* **Launch Noto** and open their personal workspace\n", "* **Clone your repository** (or pull it if they have already clicked on the link previously) in their personal workspace\n", "* **Open a notebook** of your choice\n", "\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. In the following we provide an example allowing to create a link to this notebook. You have to **adapt the parameters for *your* repository!**\n", "\n", "1. JupyterHub URL: https://noto.epfl.ch\n", "1. Git Repository URL: https://c4science.ch/source/noto-poc-notebooks (<= without the '.git' extension !)\n", "1. Branch: (none) (<= leave blank or set this up as needed)\n", "1. File to open: TeachingHowTos/SharingNotebooksWithStudents.ipynb (<= this is the path to your notebook inside your repository)\n", "1. Application to Open: JupyterLab" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from IPython.display import IFrame\n", "IFrame('https://jupyterhub.github.io/nbgitpuller/link?hub=https://noto.epfl.ch', 1000, 800)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from nbgitpuller_link import Link\n", "\n", "linker = Link(\n", " jupyterhub_url=\"https://noto.epfl.ch\",\n", " repository_url=\"https://c4science.ch/source/noto-poc-notebooks\",\n", " branch=\"master\",\n", - " launch_path=\"HowTos/SharingYourNotebooks/0-SharingNotebooks-TableOfContents.ipynb\",\n", + " launch_path=\"HowTos/SharingYourNotebooks/3-ShareNotebooks-ShareURL.ipynb\",\n", " )\n", "\n", "print(\"The nbgitpuller link is:\\n\\x1b[32m{}\\x1b[0m\".format(linker.link))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The result, displayed *at the top of the page*, is a link similar to:\n", "`https://noto.epfl.ch/hub/user-redirect/git-pull?repo=https%3A%2F%2Fc4science.ch%2Fsource%2Fnoto-poc-notebooks&urlpath=lab%2Ftree%2Fnoto-poc-notebooks%2FTeachingHowTos%2FSharingNotebooksWithStudents.ipynb`" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "**Choosing the `depth` of cloning (optional)**\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, just by adding `&depth=1` at the end of the URL:\n", "\n", "`https://noto.epfl.ch/hub/user-redirect/git-pull?repo=https%3A%2F%2Fc4science.ch%2Fsource%2Fnoto-poc-notebooks&urlpath=lab%2Ftree%2Fnoto-poc-notebooks%2FTeachingHowTos%2FSharingNotebooksWithStudents.ipynb&depth=1`\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 4.c. Testing the link\n", "\n", "**Before sharing the link with your students it is important that you test it!**
\n", "By pasting the link in your web browser, you should get sent to the desired notebook.\n", "\n", "Note that if you already have an opened Noto session in your browser, jupyterlab will create a new session automatically.\n", "\n", "**WATCH OUT:** After testing the link you will have a second copy of your repository in your Noto workspace, and this copy will be read-only. So you might want to delete this new copy right away to avoid problems." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 4.d. Shortening the link (optional)\n", "\n", "Once you are happy and ready to share your link, you can make it shorter and also prettier by using a URL shortening service such as [go.epfl.ch](https://go.epfl.ch). \n", "\n", "For instance, [`go.epfl.ch/noto-share`](https://go.epfl.ch/noto-share) is a pretty link to this notebook based on the URL we have generated in the previous section.\n", "\n", "Using `go.epfl.ch`, you can create there short and nice looking links that you will be able to distribute by email, your Moodle page, etc. \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": [ "
\n", - " <<< 3. Add your files to the repository\n", + " <<< 2. Access your repository from noto\n", "    |   \n", - " 4. Share the repository with students on noto\n", + " 3. Share the repository with students on noto\n", "
" ] } ], "metadata": { "kernelspec": { "display_name": "nbgitpullerenv", "language": "python", "name": "nbgitpullerenv" }, "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.9" } }, "nbformat": 4, "nbformat_minor": 4 }