diff --git a/HowTos/SharingYourNotebooks/2-SharingNotebooks-ConnectGitNoto.ipynb b/HowTos/SharingYourNotebooks/2-SharingNotebooks-ConnectGitNoto.ipynb index 665749f..c9d1245 100644 --- a/HowTos/SharingYourNotebooks/2-SharingNotebooks-ConnectGitNoto.ipynb +++ b/HowTos/SharingYourNotebooks/2-SharingNotebooks-ConnectGitNoto.ipynb @@ -1,351 +1,351 @@ { "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": 2, + "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", "\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", "\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: " ] } ], "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/LICENSE.md b/HowTos/SharingYourNotebooks/docs/LICENSE.md new file mode 100644 index 0000000..d7ecab4 --- /dev/null +++ b/HowTos/SharingYourNotebooks/docs/LICENSE.md @@ -0,0 +1,39 @@ +# Copyright and License + +Copyright (c) 2019-2020 Center for Digital Education (CEDE), EPFL + +## Content Material + +All content material is made available under the Creative Commons Attribution license CC-BY 4.0. + +You are free: +* to Share---to copy, distribute and transmit the work +* to Remix---to adapt the work + +Under the following conditions: +* Attribution---You must attribute the work using "Copyright (c) CEDE, EPFL" (but not in any way that suggests that we endorse you or your use of the work). Where practical, you must also include a hyperlink to https://c4science.ch/source/noto-poc-notebooks/. + +With the understanding that: +* Waiver---Any of the above conditions can be waived if you get permission from the copyright holder. +* Other Rights---In no way are any of the following rights affected by the license: + * Your fair dealing or fair use rights; + * The author's moral rights; + * Rights other persons may have either in the work itself or in how the work is used, such as publicity or privacy rights. +* Notice---For any reuse or distribution, you must make clear to others the license terms of this work. The best way to do this is with a link to http://creativecommons.org/licenses/by/4.0/. + +For the full legal text of this license, please see: http://creativecommons.org/licenses/by/4.0/legalcode + + +## Software + +Except where otherwise noted, all software is made available under the OSI-approved BSD-3-Clause license (https://opensource.org/licenses/BSD-3-Clause): + +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. \ No newline at end of file diff --git a/HowTos/SharingYourNotebooks/docs/README.md b/HowTos/SharingYourNotebooks/docs/README.md new file mode 100644 index 0000000..c4a2b09 --- /dev/null +++ b/HowTos/SharingYourNotebooks/docs/README.md @@ -0,0 +1,30 @@ +# 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