diff --git a/HowTos/UsingGit/UsingGit.ipynb b/HowTos/UsingGit/UsingGit.ipynb index 760e27e..63cd230 100644 --- a/HowTos/UsingGit/UsingGit.ipynb +++ b/HowTos/UsingGit/UsingGit.ipynb @@ -1,125 +1,125 @@ { "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# How to use `git` for your notebooks?" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This notebook describes the workflow you can adopt to work efficently on your notebooks with your colleagues, and how you can share notebooks through simple shareable links with anyone.\n", "\n", "`git` it is a version control system, designed to help team work on a set of shared files. There are two main uses of git:\n", "1. Each member of the notebook development team can work on the files and send his/her changes to the files to a `git` server.\n", "2. The `git` server can also be configured to allow a public read-only access to the files, allowing anyone to get a copy of the files.\n", "\n", "For point 2. (sharing your git repository to your audience) read [this notebook](../../TeachingHowTos/ShareNotebooksWithStudents.ipynb)!" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Getting ready to use `git`\n", "This notebook does _not_ go into details on how to use `git`.
\n", "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", "# What git server should you use?\n", "\n", "We recommand using a `git` server to store your work on your notebooks and to share them with colleagues and students.\n", "\n", "![git server](Images/sharing_with_git.png)\n", "\n", "*figure: git server at the center of your workflow.*\n", "\n", "\n", "There are many places around the web providing `git` services:\n", "\n", "* EPFL's [`c4science`](https://gitlab.epfl.ch/) - using your GASPAR account\n", "* EPFL's [`gitlab`](https://gitlab.epfl.ch/) - using your GASPAR account\n", "* [`github`](https://github.com/) - you need a `github` account\n", "\n", "While ![noto](../../Images/noto_inline_transparent.png) works perfectly with any of these `git` servers, we would like to stress out the fact that you should care about **where** in the the world your data is stored. By using EPFL's services you ensure your data stays in Switzerland and that your work will not be impacted by possible changes in the law on data protection.\n", "\n", "# Setting up your environment for working with a git server\n", "\n", "## For public repositories\n", "\n", "Usually, once your `git` tool is installed on your personal computer (just like it is in ![noto](../../Images/noto_inline_transparent.png)), you are ready to go and you can clone right away any `git` public repository.\n", "Most public `git` repositories are read-only, meaning that you can not contribute back by sending the changes you made. To contribute (push your changes to the `git` server), you need to authenticate and ,of course, have write access on the `git` repository! (see next section)\n", "\n", "## Authenticating on a remote git server\n", "\n", "There are two ways to authenticate on a remote server: using a **username** and a **password** or to user **SSH keys**. While both methods will work from the command line (`git` command will ask your username and password), it is much more convenient to setup SSH keys: the `git` command will make use of your SSH keys and not ask for your password everytime and the `git` interface from Jupyterlab will be able to interact with the server.\n", "We recommend you take some time to set up SSH keys authentication - it not a long process and that will certainly speed up your \n", "\n", "Here are the required steps for having SSH keys authentication to work:\n", "\n", "* Make sure the remote URL of your git folder starts with `ssh://...`. When you clone and existing repository, use the `ssh://...` URL (not the `https://...` version).\n", "* Make sure your SSH keys on ![noto](../../Images/noto_inline_transparent.png) are ready (see the \"using git\" notebook in your Documentation directory)\n", "* Make sure you imported your public key over to your account on the remote server. On most `git` services, in your user's settings page, there is a place to add new SSH keys.\n", "\n", "This should be enough to have SSH key authentication working.\n", "Should you need to troubleshoot, the `jupyterlab-git` extension (then part that provide the JupyterLab integration with `git`) is unfortunately not really helpfull.\n", "So, always give it a go in your Terminal for a more verbose feedback.\n", "\n", "## Making `git` work easier\n", "\n", "There are a few things to consider when using `git` for Jupyter notebooks:\n", "\n", "1. It is much more convinient to only commit *clean* notebooks: you should remove your outputs before your commit. Once that is done, it is much easier to see the differences from one version to another. Also, it gives the opportunity to your readers to run the notebook themselves. **Reproducibility** is an important aspect of the work you are sharing: it is more important to ensure that the notebooks work perfectly and that anyone can reproduce the output than just pushing your own outputs to the `git` server.\n", "\n", "2. Jupyter and Python produce temporary files that you do not want to be part of your repository: make sure that the root of your `git` repository contains a `.gitignore' file with the following content:\n", "\n", "```\n", "**/.ipynb_checkpoints\n", "**/__pycache__\n", "```\n", "\n", "3. Avoid putting large binary files, especially content that could be hosted somewhere else. e.g. if you need a video from youtube, import it as [link](../EmbedExternalResources/EmbedExternalResources.ipynb#Videos).\n", "\n", "# Sharing notebooks through shareable links using git\n", "\n", "On noto, you can use a mechanism called `nbgitpuller` (it *clones* or *pulls* your `git` repository into the user's workspace and opens a notebook). This allows you to share your notebooks with anyone by simply sending a link. Any person clicking this link gets to a specific notebook from your `git` repository, loaded on noto.\n", "\n", "For teachers, this is a very convenient way to share notebooks, for instance by publishing a link to one of your notebooks on your course's Moodle page. Your students click and they get to the notebook directly.\n", "\n", - "[More information on how to use it **in this notebook**.](../../TeachingHowTos/SharingNotebooksWithStudents.ipynb)\n" + "[More information on how to use it **in this notebook**.](../../TeachingHowTos/ShareNotebooksWithStudents.ipynb)\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "\n", "**End of the notebook**" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.6.8" } }, "nbformat": 4, "nbformat_minor": 4 } diff --git a/TeachingHowTos/EmbedQuizQuestions.ipynb b/TeachingHowTos/EmbedQuizQuestions.ipynb index ace7ed4..33a52a5 100644 --- a/TeachingHowTos/EmbedQuizQuestions.ipynb +++ b/TeachingHowTos/EmbedQuizQuestions.ipynb @@ -1,203 +1,232 @@ { "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# How to add auto-corrected quiz questions to my notebooks?\n", "\n", "\n", "
\n", "\"Moodle\n", "\"Moodle\n", "
\n", "\n", "Interactive quiz questions are a great way to engage students with the content of the notebook and to help them check their understanding. \n", "In this notebook, we present how to **create quiz questions in moodle** (using the H5P plugin) and **embed the questions into your notebooks**. \n", "\n", "The figure on the right shows an example of what it can look like, before and after a student submits an answer.\n", "\n", "To see an example of a notebook including quiz questions, have a look at our [\"Suspended Objects\" example](../TeachingExamples/SuspendedObjects-exercise.ipynb) or at the [demo](#DemoSection) at the end of this notebook. \n", "\n", "
 
\n", "\n", "\n", "## Why use moodle?\n", "\n", "

There are other ways to integrate quiz questions into notebooks but the solution we suggest here has a very important characteristic: the data collected on students' responses is stored on the EPFL moodle server.
\n", "This is extremely important in order to be consistent with the data protection and professional confidentiality provisions of Swiss law.

\n", "\n", "In addition, using moodle to create quiz questions has **a number of advantages**:\n", "* The moodle H5P plugin for creating quiz questions offers a [wide range of question types](https://h5p.org/content-types-and-applications) with multiple options to customize them ;\n", "* You don't need to write code to correct the quiz questions, the moodle H5P plugin has multiple options that allow you to give feedback automatically to students when they answer the quiz ;\n", "* In your moodle page, you will be able to see how people answer your quiz question, which can give you useful feedback ;\n", "* The quiz questions that you create in moodle can be reused for different purposes (e.g. learning activities in moodle) and they can also be exported / imported.\n", "\n", "However, this solution (as any other) has some limitations.\n", "\n", "## Limitations \n", "\n", "You need to **have a moodle course page** for creating the quiz questions and you need to have the \"teacher\" (or \"manager\") role on this page to be able to edit it. \n", "We suggest you use the moodle page of one of your courses. In case this is not possible or not adapted for your project, don't hesitate to [contact us](mailto:noto-support@groupes.epfl.ch) to discuss other options.\n", "\n", "One important limitation of this is that **the way in which you set up registrations on your moodle course** will impact **who can see your quiz questions in your notebooks**. \n", "Please check below who will have access to your quiz questions before anything else. \n", "\n", " \n", "\n", "## Step 0: check who will have access to your quiz questions \n", "\n", "In your moodle course, go to the \"Participants\" page, check the \"Enrolment methods\" which are activated on your course.\n", "\n", "Here is who will have access to your quiz questions depending on the enrolment methods activated (these enrolment methods can be combined):\n", "1. **\"External database\"**: students who are registered on your course on IS-Academia have access to your quiz questions. \n", "This is the option recommanded so that your students can use your quiz questions.\n", "1. **\"Manual enrolment\"**: you have to add manually the persons who will have access to your quiz questions (they need to have a GASPAR account).\n", "1. **\"Self enrolment\"**: anyone with a GASPAR account can register to your course and have access to your quiz questions. \n", "This is the option recommanded so that any EPFL students and member of EPFL staff can use your quiz questions.\n", "1. **\"Guest access\"**: anyone from the general public can see your moodle page and have access to your quiz questions without being logged on. \n", "This is the option recommanded so that the general public can use your quiz questions. However, one important drawback of this method is that you will no longer be able to see how people answer your quiz (and it also means the whole content of your moodle page is public).\n", "\n", "Please note that for methods 1, 2 and 3, people have to be **logged on moodle** when they use your notebooks so that they see your quiz questions. It is recommended to add a short sentence indicating that if they don't see the quiz then they need to log on moodle.\n", "\n", "Make sure to activate the appropriate enrolment methods depending on the audience who will use your notebooks. \n", "When someone does not have access as per the enrolment methods above, here is what they see in place of the quiz question in the notebook:\n", "\n", "\"No\n", "\n", "\n", " \n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Step 1: create a quiz question in moodle\n", "\n", "\n", "You need to *turn editing on* your moodle page before proceeding to the next steps.\n", "\n", "

Add a hidden section to your moodle page

\n", "\n", "We suggest that you create an additional section (\"topic\") in your moodle course page, which will serve as a container for your quiz questions. \n", "To add a section, then go at the bottom of the moodle page and click on \"Add topics\".\n", "\n", "We also suggest that you hide this section from your moodle page so that the quiz question are visible only in the notebooks - of course, if you want your students to see the questions in your moodle page then skip this step. \n", "At the top of the section, select \"Edit\" then \"Hide topic\". A blue tage should appear just below the title of the section saying `Hidden from students`.\n", "\n", "\n", "

Create a question

\n", "\n", "To create a new quiz question, use the \"Add an activity\" dropdown menu and then choose \"Interactive content\" as shown on the figure below. \n", "Attention: do not select the \"quiz\" option in the dropdown menu (this type of quiz cannot be embedded in a notebook).\n", "\n", "\"Interactive\n", "\n", "Select the type of question that you want in the list and click on it.\n", "\n", "\"Content\n", "\n", "Fill out the form to create your question, then choose \"Save and return to course\".\n", "\n", "

Make the question available

\n", "\n", "If your question is placed in a hidden section as we have suggested, then you have to indicate to moodle that you want to make the quiz question available outside of moodle (i.e. in your notebooks). On the right side of the activity, select the \"Edit\" menu and then click on \"Make available\", as shown on the image below. \n", "NB: this step is not necessary if the question is in a visible section of the moodle page (by default it is then available).\n", "\n", "\"Make\n", "\n", "Once this is done, a blue tag saying `Available but not shown on course page` should appear right below your quiz question.\n", "\n", " " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Step 2: embed the question into a notebook\n", "\n", "

Get the URL of your question

\n", "\n", "From your moodle page, click on your new question. This will open your question and show you how it will look like for students. \n", "Click on the \"<> Embed\" link at the bottom of the question, as shown on the figure below. Copy the code which appears in the \"Embed\" popup.\n", "\n", "\"Embed\"\n", "\n", "Paste the code into your favorite text editor and find the URL of the question, which should appear between quotes after ` ') \n", + "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Demo \n", "\n", "To be able to see the demo quiz question, you need to be logged on moodle and registered as participant on our moodle course (see the [Limitations section](#LimitationsSection)). \n", "Please open a new tab or window, **log on [moodle](https://moodle.epfl.ch/enrol/index.php?id=15917)** and **register yourself on the [Noto Community moodle page](https://moodle.epfl.ch/enrol/index.php?id=15917)**. \n", "\n", "Then execute the cell below to activate the interactive quiz. \n", "\n", "" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 1, "metadata": {}, - "outputs": [], + "outputs": [ + { + "data": { + "text/html": [ + "\n", + " \n", + " " + ], + "text/plain": [ + "" + ] + }, + "execution_count": 1, + "metadata": {}, + "output_type": "execute_result" + } + ], "source": [ "from IPython.display import IFrame\n", "IFrame('https://moodle.epfl.ch/mod/hvp/embed.php?id=1028285', 800, 600)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If you see the message `Vous n'avez pas accès à ce contenu. Essayez de vous connecter.`, check that you are logged on [moodle](https://moodle.epfl.ch/) using your GASPAR account and that you are registered as participant on the [Noto Community moodle page](https://moodle.epfl.ch/enrol/index.php?id=15917)." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.6.8" + "version": "3.6.9" } }, "nbformat": 4, "nbformat_minor": 4 } diff --git a/TeachingHowTos/GetFeedback.ipynb b/TeachingHowTos/GetFeedback.ipynb index b485682..5884223 100644 --- a/TeachingHowTos/GetFeedback.ipynb +++ b/TeachingHowTos/GetFeedback.ipynb @@ -1,101 +1,101 @@ { "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# How to get feedback from students on your notebooks?\n", "\n", "Getting feedback from students on the notebooks you use in your teaching is very important to be able to improve them in a meaningful way. \n", "We offer two ways in which you can get feedback from students on your notebooks:\n", "1. Through a **[short generic online survey](#generic)** integrated into your notebooks\n", "2. Through a more **[detailed survey](#specific)** which can be **customized to your needs** and administered online or on paper in your class\n", "\n", "## Short generic survey  \n", "\n", "We provide a generic survey that you can embed into your notebooks to **collect anonymous feedback** from those who use your notebooks. \n", "The survey is designed to be short and easy to fill out, with three questions (both in English and French) focusing on helpfulness, usability and a free text field for comments. You can see the survey form below. \n", "The survey will automatically collect data for you. We then process the data and provide you with a summary of the feedback regularly. \n", "\n", "How to use it?\n", "\n", "**Step 1:** Add a cell to your notebook and copy the following piece of Python code in it (below is the code to use in R):\n", "\n", " ```python\n", "from IPython.display import IFrame\n", "IFrame('https://www.surveymonkey.com/r/NOTOSURVEY?notebook_set=COURSENAME¬ebook_id=NOTEBOOKNAME', 600, 800)\n", "```\n", "\n", "**Step 2:** In the code, replace the two following elements (attention: DO NOT USE SPACES, use dash or underscore to replace spaces):\n", "* `COURSENAME`: replace by name of the project or course, e.g. `MecaDRIL` or `PHYS-101`\n", "* `NOTEBOOKNAME`: replace by the name or code of the notebook in the course, e.g. `01-Logan` \n", "\n", "\n", "Example of complete URL: \n", "`https://www.surveymonkey.com/r/NOTOSURVEY?notebook_set=MecaDRIL¬ebook_id=01-Logan`\n", "\n", "**Optional:** It can be useful to add one line of text above the code cell with the survey to indicate to your students that you would appreciate their feedback on your notebook. \n", "You could use something like: *Did you like this Notebook? Why don't you give us some feedback using the completely anonymous form below (just execute the cell to see it)? Thank you!*\n", "\n", "**Demo:**\n", "\n", "Execute the cell below to see the survey:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from IPython.display import IFrame\n", "IFrame('https://www.surveymonkey.com/r/NOTOSURVEY?notebook_set=noto-poc-notebooks¬ebook_id=survey-monkey-demo', 600, 900)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If you use R, here is the equivalent code:\n", "\n", "```R\n", "library(IRdisplay)\n", "IRdisplay::display_html(' ') \n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Detailed customized survey  \n", "\n", "If you would like to have **more detailed feedback** or if these questions do not match your context, then we can **design a survey** for you. \n", "You can see [in this file an example of a questionnaire](Docs/NotebookSurvey.pdf) with customized questions, which can be administered either on paper in your class or online. We can help you with designing the questions, administering the questionnaire as well as analyzing the data.\n", "\n", "Just **drop us an email at [noto-support@groupes.epfl.ch](mailto:noto-support@groupes.epfl.ch)** if you would like to use one of those questionnaires." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.6.8" + "version": "3.6.9" } }, "nbformat": 4, "nbformat_minor": 4 } diff --git a/TeachingHowTos/ShareNotebooksWithStudents.ipynb b/TeachingHowTos/ShareNotebooksWithStudents.ipynb index 65111a2..b141d32 100644 --- a/TeachingHowTos/ShareNotebooksWithStudents.ipynb +++ b/TeachingHowTos/ShareNotebooksWithStudents.ipynb @@ -1,88 +1,88 @@ { "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Sharing notebooks with your students\n", "\n", "Notebooks are simple text files, so they can easily be shared by usual means e.g. **uploaded on Moodle**, sent by email, etc. like you would do with any other type of document (pdf, doc, etc.). \n", "To execute a notebook, students can then simply **upload it to  ![noto](../Images/noto_inline_transparent.png)** by **drag-and-dropping the file onto their workspace** (of course, they can also execute a notebook in their own Jupyter environment if they have installed one on their laptop). \n", "But these methods have a few drawbacks:\n", "* Students cannot easily see the content of a notebook unless they execute it\n", "* If the notebook reads data from other files, then you also have to share these other files with the notebook\n", "\n", "In the following, we present a much more powerful way of **sharing your notebooks using simple shareable links** using a mechanism called `nbgitpuller`.
\n", "A **requirement** for using this method is to host the notebooks you want to share in a `git` repository. \n", "In exchange, this method will allow you to **generate shareable links** for any of the notebooks from this repository, that you can then **publish on your Moodle page**. Students clicking on it will get instant access to the notebook and will be able to execute it directly on  ![noto](../Images/noto_inline_transparent.png).\n", "\n", "## Putting your notebooks in a `git` repository\n", "\n", "See [this notebook for more information](../HowTos/SharingYourNotebooks/SharingYourNotebooks.ipynb).\n", "\n", "## Who can get access to notebooks this way?\n", "\n", "To be able to generate `nbgitpuller` links, you must allow **public reading access** to the `git` repository hosting your notebooks. \n", "\n", "The `nbgitpuller` links allow you to share your notebooks using  ![noto](../Images/noto_inline_transparent.png). This means that this method of sharing notebooks works with anyone being able to log on  ![noto](../Images/noto_inline_transparent.png), i.e. all EPFL members and all members of [universities with Switch-AAI authentication](https://www.switch.ch/aai/participants/homeorgs/). \n", "\n", "\n", "## Preparing and testing the `nbgitpuller` link\n", "\n", "In order to build the `nbgitpuller` link, you need to go to: [https://jupyterhub.github.io/nbgitpuller](https://jupyterhub.github.io/nbgitpuller/link?hub=https://noto.epfl.ch). Then you need to fill out the form. 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\n", "\n", "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`\n", "\n", "## Testing the link\n", "By pasting the link in your web browser, you should get sent to the desired notebook.\n", "**Note that if you already have an opened Noto session in your browser, jupyterlab will create a new session automatically.**\n", "\n", "## Choosing the `depth` of cloning\n", "\n", "By default, the entire history of the git repository is pulled in the user's workspace. This might be slow if your git repository is large or if a large number of students are going to pull at the same time. You can set this to 1 to pull only the latest commit on initial pull, like so:\n", "\n", "`https://noto.epfl.ch/hub/user-redirect/git-pull?repo=https%3A%2F%2Fc4science.ch%2Fsource%2Fnoto-poc-notebooks&urlpath=lab%2Ftree%2Fnoto-poc-notebooks%2FTeachingHowTos%2FSharingNotebooksWithStudents.ipynb&depth=1`\n", "\n", "(just by adding `&depth=1`)\n", "\n", "\n", "## Sharing the link\n", "\n", "Once you are happy and ready to share your link, it is time to make it pretty!
\n", "For that, you can use a URL shortening service such as [go.epfl.ch](https://go.epfl.ch). 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", "\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!" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.6.8" + "version": "3.6.9" } }, "nbformat": 4, "nbformat_minor": 4 }