diff --git a/HowTos/ShareNotebooks/2-ShareNotebooks-ConnectGitNoto.ipynb b/HowTos/ShareNotebooks/2-ShareNotebooks-ConnectGitNoto.ipynb index 9141e7a..1dac080 100644 --- a/HowTos/ShareNotebooks/2-ShareNotebooks-ConnectGitNoto.ipynb +++ b/HowTos/ShareNotebooks/2-ShareNotebooks-ConnectGitNoto.ipynb @@ -1,376 +1,376 @@ { "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. Access your repository from noto
    3. \n", "
  3. Share the repository with students on noto
    4. \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", + "* `.gitignore`: configuration file 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", + "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" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "\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", "    |   \n", " 2. Access your repository from noto\n", "    |   \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", "\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 }