diff --git a/HowTos/SharingYourNotebooks/0-SharingNotebooks-TableOfContents.ipynb b/HowTos/SharingYourNotebooks/0-SharingNotebooks-TableOfContents.ipynb index 1da4a1f..d20ae07 100644 --- a/HowTos/SharingYourNotebooks/0-SharingNotebooks-TableOfContents.ipynb +++ b/HowTos/SharingYourNotebooks/0-SharingNotebooks-TableOfContents.ipynb @@ -1,81 +1,81 @@ { "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "

How to share notebooks with students?

\n", "

Table of contents

\n", "
    \n", "
  1. Create a git repository on c4science
    2. \n", "
  2. Clone and intialize the repository on noto
    3. \n", "
  3. Add your files to the repository
    4. \n", "
  4. Share the repository with students on noto
    5. \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 working collaboratively on notebooks while ensuring no modification is ever lost (versionning).\n", - "\n", - "This tutorial will guide you through the following steps:\n", + "Noto supports notebook sharing through a tool called `git`, which is specifically designed for working collaboratively on notebooks while ensuring *no modification is ever lost* (versionning).\n", + "With `git`, you can **manage who can only see** or conversely **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", "
  1. Create a git repository on c4science
    2. \n", "
  2. Clone and intialize the repository on noto
    3. \n", "
  3. Add your files to the repository
    4. \n", "
  4. Share the repository with students on noto
    5. \n", "
\n", " \n", "And if you want to go further, we recommend that you check out this notebook which contains advanced information.\n", "\n", "
\n", "\n", "**TODO** : diagram\n", " \n", "
\n", "\n", "\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", " Table of contents\n", "    |   \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/SharingYourNotebooks/1-SharingNotebooks-CreateGitRepo.ipynb b/HowTos/SharingYourNotebooks/1-SharingNotebooks-CreateGitRepo.ipynb index 006d876..ad0b18f 100644 --- a/HowTos/SharingYourNotebooks/1-SharingNotebooks-CreateGitRepo.ipynb +++ b/HowTos/SharingYourNotebooks/1-SharingNotebooks-CreateGitRepo.ipynb @@ -1,170 +1,178 @@ { "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "

How to share notebooks with students?

\n", "

Table of contents

\n", "
    \n", "
  1. Create a git repository on c4science
    2. \n", "
  2. Clone and intialize the repository on noto
    3. \n", "
  3. Add your files to the repository
    4. \n", "
  4. Share the repository with students on noto
    5. \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** for sharing notebooks with students.\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). Of course, other repositories exists, such as [GitHub](https://github.com/) for instance.\n", + "We recommend that you use the EPFL git server [c4science](http://c4science.ch).
\n", + "Of course, there are many othe `git` servers available around the internet, such as [GitHub](https://github.com/) for instance, and the `git` client installed on Noto is compatible with all them. 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", "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", - "We recommend you to change the following settings: \n", - "1. For allowing **students to access your notebooks** withou being able to modify them (they will still be able to modify their own local copy but will not be allowed to modify yours), you should set the **`Visible To` parameter to `Public (No Login Required)`**. \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", - "1. If you want **other teachers and teaching assistants** to be able to contribute to your notebooks, first make sure that these persons have an account on [c4science](http://c4science.ch) and 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", + "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", "    |   \n", " 1. Create a git repository on c4science\n", "    |   \n", " 2. Clone and initialize your repository in 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/SharingYourNotebooks/2-SharingNotebooks-ConnectGitNoto.ipynb b/HowTos/SharingYourNotebooks/2-SharingNotebooks-ConnectGitNoto.ipynb index c9d1245..415cd4c 100644 --- a/HowTos/SharingYourNotebooks/2-SharingNotebooks-ConnectGitNoto.ipynb +++ b/HowTos/SharingYourNotebooks/2-SharingNotebooks-ConnectGitNoto.ipynb @@ -1,351 +1,353 @@ { "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "

How to share notebooks with students?

\n", "

Table of contents

\n", "
    \n", "
  1. Create a git repository on c4science
    2. \n", "
  2. Clone and intialize the repository on noto
    3. \n", "
  3. Add your files to the repository
    4. \n", "
  4. Share the repository with students on noto
    5. \n", "
\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# 2. Clone and initialize the repository on 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 three very 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", "* [Initializing your repository with template files](#2.c.-Initializing-your-repository-with-template-files)" ] }, { "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 initialize your repository!**" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 2.c. Initializing your repository with template files\n", "\n", "We provide you with a script that will **automatically create 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 will find a description of the role and content of each of these files below.\n", "\n", "**Execute the following cell to execute the script**. Then if you want to remove some of those file, you can of course still do it. " ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# TODO SCRIPT HERE" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "\n", "**TODO** : script + the script should commit and push the files to avoid the `Git Push failed with error:fatal: The current branch master has no upstream branch.`\n", "We also need to correct the URLs in both the README and the LICENSE files when we change the URL of the noto doc repo.\n", " \n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Once you have executed this script, you are ready to **add your own files** to your repository!" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", " <<< 1. Create a repository on c4science\n", "    |   \n", " 2. Clone and initialize the repository on noto\n", "    |   \n", " 3. Add your files to the repository >>>\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Appendix: details on the provided template files\n", "\n", "

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": [ "
\n", "\n", "**TODO why not:**\n", "```\n", ".ipynb_checkpoints\n", "*/.ipynb_checkpoints/*\n", "```\n", " \n", "
" ] }, { "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", + "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 contains the following sections: \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 time 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: \n", - "* For code, we suggest to use the BSD-3-Clause license: " + "* For code, we suggest to use the BSD-3-Clause license: \n", + "\n", + ", which you can see [by clicking here](docs/LICENSE.md)," ] } ], "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/SharingYourNotebooks/docs/README.md b/HowTos/SharingYourNotebooks/docs/README.md index c4a2b09..76f2317 100644 --- a/HowTos/SharingYourNotebooks/docs/README.md +++ b/HowTos/SharingYourNotebooks/docs/README.md @@ -1,30 +1,31 @@ # Project title Start the README file by stating the name of your project or the name of your repository. ## Project description We recommend that you provide a short description of your project, making sure to include relevant keywords for indexing. The goal of this repository is to provide you with _template files_ that help you initialize your repository and that you can modify to fit your own needs and your own project. Then it is important to state the names of the authors and contributors of the project. The contributors of this repository and the included template files are Cécile Hardebolle, Pierre-Olivier Vallès and Patrick Jermann, from the Center for Digital Education at EPFL. It is good practice to include the public URL of your repository. This repository is available at: https://c4science.ch/source/noto-poc-notebooks/ And finally, contact information can also be helpful. For any enquiries relating to this template or this repository, please contact: [noto-support@groupes.epfl.ch](mailto:noto-support@groupes.epfl.ch) ## Copyright and license Providing licensing information is very important. A brief summary should be included into your README and then you should also provide a more detailed LICENSE file. + All content in this repository is distributed publicly and openly under a Creative Commons Attribution license, [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/), and all code is under [BSD-3-Clause](LICENSE.md). ## Table of contents This repository contains: * a template `.gitignore` file * a template `README.md` file * a templace `LICENSE.md` file * an example notebook