From 46d4481ef9bca4304bffc4689196bea30a426825 Mon Sep 17 00:00:00 2001 From: Zoltan Date: Mon, 11 Dec 2023 14:06:04 -0500 Subject: [PATCH 1/2] edit colab buttons for w1d1 tut4 --- tutorials/W1D1_Instructions/W1D1_Tutorial4.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/W1D1_Instructions/W1D1_Tutorial4.ipynb b/tutorials/W1D1_Instructions/W1D1_Tutorial4.ipynb index 7bd9b618..e86df345 100644 --- a/tutorials/W1D1_Instructions/W1D1_Tutorial4.ipynb +++ b/tutorials/W1D1_Instructions/W1D1_Tutorial4.ipynb @@ -8,7 +8,7 @@ "id": "view-in-github" }, "source": [ - "\"Open   \"Open" + "\"Open   \"Open" ] }, { From 44f4db2ffd3d96beb915ec51f9979f4510a99d52 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Mon, 11 Dec 2023 19:09:58 +0000 Subject: [PATCH 2/2] Process tutorial notebooks --- tutorials/README.md | 1 + tutorials/W1D1_Instructions/README.md | 2 + .../W1D1_Instructions/W1D1_Tutorial4.ipynb | 2 +- .../instructor/W1D1_Tutorial4.ipynb | 324 ++++++++++++++---- .../student/W1D1_Tutorial4.ipynb | 324 ++++++++++++++---- 5 files changed, 530 insertions(+), 123 deletions(-) diff --git a/tutorials/README.md b/tutorials/README.md index 02bbab2c..92234547 100644 --- a/tutorials/README.md +++ b/tutorials/README.md @@ -18,6 +18,7 @@ Slides: [Intro](https://mfr.ca-1.osf.io/render?url=https://osf.io/rbx2a/?direct% | Tutorial 1 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial1.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial1.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial1.ipynb?flush_cache=true) | | Tutorial 2 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial2.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial2.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial2.ipynb?flush_cache=true) | | Tutorial 3 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial3.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial3.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial3.ipynb?flush_cache=true) | +| Tutorial 4 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial4.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial4.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial4.ipynb?flush_cache=true) | | Outro | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/W1D1_Outro.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/W1D1_Outro.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/W1D1_Outro.ipynb?flush_cache=true) | diff --git a/tutorials/W1D1_Instructions/README.md b/tutorials/W1D1_Instructions/README.md index cce02bfb..37ffecc3 100644 --- a/tutorials/W1D1_Instructions/README.md +++ b/tutorials/W1D1_Instructions/README.md @@ -8,6 +8,7 @@ | Tutorial 1 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial1.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial1.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial1.ipynb?flush_cache=true) | | Tutorial 2 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial2.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial2.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial2.ipynb?flush_cache=true) | | Tutorial 3 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial3.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial3.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial3.ipynb?flush_cache=true) | +| Tutorial 4 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial4.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial4.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial4.ipynb?flush_cache=true) | | Outro | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/W1D1_Outro.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/W1D1_Outro.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/W1D1_Outro.ipynb?flush_cache=true) | @@ -19,5 +20,6 @@ | Tutorial 1 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial1.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial1.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial1.ipynb?flush_cache=true) | | Tutorial 2 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial2.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial2.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial2.ipynb?flush_cache=true) | | Tutorial 3 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial3.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial3.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial3.ipynb?flush_cache=true) | +| Tutorial 4 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial4.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial4.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/student/W1D1_Tutorial4.ipynb?flush_cache=true) | | Outro | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/W1D1_Outro.ipynb) | [![Open In kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://raw.githubusercontent.com/neuromatch/course-content-template/main/tutorials/W1D1_Instructions/W1D1_Outro.ipynb) | [![View the notebook](https://img.shields.io/badge/render-nbviewer-orange.svg)](https://nbviewer.jupyter.org/github/neuromatch/course-content-template/blob/main/tutorials/W1D1_Instructions/W1D1_Outro.ipynb?flush_cache=true) | diff --git a/tutorials/W1D1_Instructions/W1D1_Tutorial4.ipynb b/tutorials/W1D1_Instructions/W1D1_Tutorial4.ipynb index e86df345..deed8715 100644 --- a/tutorials/W1D1_Instructions/W1D1_Tutorial4.ipynb +++ b/tutorials/W1D1_Instructions/W1D1_Tutorial4.ipynb @@ -350,7 +350,7 @@ "colab": { "collapsed_sections": [], "include_colab_link": true, - "name": "W1D1_Tutorial2", + "name": "W1D1_Tutorial4", "provenance": [], "toc_visible": true }, diff --git a/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial4.ipynb b/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial4.ipynb index cca06dda..c9a08af3 100644 --- a/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial4.ipynb +++ b/tutorials/W1D1_Instructions/instructor/W1D1_Tutorial4.ipynb @@ -8,7 +8,7 @@ "id": "view-in-github" }, "source": [ - "\"Open   \"Open" + "\"Open   \"Open" ] }, { @@ -17,15 +17,21 @@ "execution": {} }, "source": [ - "# Tutorial 4: Model Discussions\n", - "**Week 1, Day 1: Model Types**\n", + "# Tutorial 4: Notebook Sections\n", "\n", - "**By Neuromatch Academy**\n", + "**Week 1, Day 1: Instructions**\n", "\n", - "__Content creators:__ Matt Laporte, Byron Galbraith, Konrad Kording\n", + "**By Neuromatch**\n", "\n", - "__Post-production team:__ Gagana B, Spiros Chavlis\n", - "\n" + "__Content creators:__ Konstantine Tsafatinos\n", + "\n", + "__Content reviewers:__ Konstantine Tsafatinos\n", + "\n", + "__Production editors:__ Konstantine Tsafatinos\n", + "\n", + "
\n", + "\n", + "Acknowledgments: [Ella Batty, Spiros Chavlis and neuromatch]\n" ] }, { @@ -35,29 +41,48 @@ }, "source": [ "___\n", - "# Tutorial Objectives\n", "\n", - "*Estimated timing of tutorial: 45 minutes*\n", + "## Tutorial Objectives\n", + "\n", + "*Estimated timing of tutorial: [15 mins]*\n", + "\n", + "In this tutorial, you will learn about the different sections and folder heirarchies in the course notebook, and how to use them.\n", + "\n", "\n", - "In this tutorial, you will reflect on what/how/why models in a group discussion and discuss your preferences and thoughts on modeling." + "You will: \n", + "\n", + "- learn how to add Art for the landing page of a tutorial day\n", + "- learn how to create Wrap Ups for a given module (category)\n", + "- learn how to add Bonus Tutorials\n", + "- learn how to add/update the course schedule\n", + "\n", + "It is recommended that you read through all of tutorials 1 through 3 as this tutorial builds upon that knowledge." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "---\n", + "## Setup (maybe remove?)\n", + "\n" ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": { - "cellView": "form", "execution": {} }, - "outputs": [], "source": [ + "In this section, we have:\n", "\n", - "# @title Tutorial slides\n", - "# @markdown These are the slides for the videos in all tutorials today\n", - "from IPython.display import IFrame\n", - "link_id = \"6dxwe\"\n", - "print(f\"If you want to download the slides: https://osf.io/download/{link_id}/\")\n", - "IFrame(src=f\"https://mfr.ca-1.osf.io/render?url=https://osf.io/{link_id}/?direct%26mode=render%26action=download%26mode=render\", width=854, height=480)" + "1. **Github Actions**: Enable github actions to allow for triggered workflows.\n", + "2. **Branches and PRs**: Create local branches, push to github, and create a pull request.\n", + "3. **Folder Structure and Naming Convention**: Guidelines to follow so that the processing and build steps work correctly.\n", + "4. **Materials.yml**: Add days and tutorials to the materials.yml file.\n", + "5. **Workflows**: Trigger the workflows." ] }, { @@ -67,36 +92,174 @@ }, "source": [ "---\n", - "# Setup" + "\n", + "## Section 1: How to enable github action\n", + " " + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "Steps:" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "- click on the settings tab in your newly created repo\n", + "- click on the actions dropdown -> general\n", + "- click on *allow all action and reusable workflows*\n", + "- click save\n", + "\n", + "

github actions gif

\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "---\n", + "\n", + "# Section 2: How to create a PR\n", + "\n", + "When creating content you want to add to the course book, you will need to have python and git installed. Afterwards, you will need to create a local python environment with all requirements for your code installed; including jyputer. Before starting to add content, you will need to create a new branch. Instructions [here](https://www.w3schools.com/git/git_branch.asp). \n", + "\n", + "Once you have created your working branch, you can then start to work on your notebook. Before saving your notebook and committing the changes to your branch, restart the kernel and clear all cells. Then you can save it, [add](https://www.w3schools.com/git/git_staging_environment.asp?remote=github) the changes, [commit](https://www.w3schools.com/git/git_commit.asp?remote=github) them, and [push](https://www.w3schools.com/git/git_push_to_remote.asp?remote=github) to github.\n", + "\n", + "**NOTE**: It is vital that you restart the kernel and clear all outputs. The processing scripts will throw an error if you do not, and the workflow will **not** complete successfully.\n", + "\n", + "**Be Careful**: Remeber to pull the lastest changes from github before you commit your work! This is important, a successful workflow execution will create new commits, and if you do not pull the those changes before your commit your local ones, there will be a commit history conflict; i.e you will not be able to push your changes.\n", + "\n", + "\n", + "How to restart kernel and clear all outputs:\n", + "\n", + "

restart kernel gif

\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "## Section 2.1: Creating a PR\n", + "\n", + "Once you have pushed the work on your new branch, you can create a PR onto the main branch. **NOTE**: This will trigger the processing workflow for the course content.\n", + "\n", + "Create a pull request:\n", + "\n", + "

pull request gif

\n", + "\n", + "\n", + "Process Notebook workflow:\n", + "\n", + "

process notebook gif

\n", + "\n", + "The process notebook workflow will automatically get triggered once a pull request is made to the main branch. It will create the student, instructor and solutions directories, verify the exercises, and prepare the content for the publish workflow. You do **not** need to create or touch the aforementioned folders. All your work should be done on the jupyter notebooks. Remember to restart the kernel and clear your output, if you do not, the process notebooks workflow will throw an error." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "# Section 3: Folder Structure and Naming Conventions\n", + "\n", + "In order for the workflows and scripts to work correctly, and for your book to properly build, you will need to **strictly** follow our folder heirarchy and naming conventions. This is what the scripts are expecting, and you will not be able to successfully build your course book if you deviate from the conventions. \n", + "\n", + "- book/ (do not touch, this get automatically created/population in the publish workflow)\n", + "- projects/ (TODO: explain this in more depth)\n", + "- tutorials/\n", + " - W#D#\\_DayName/ -> (ie. W1D1\\_InstructionsTemplate; This is strict! You must have the W#D#\\_ prefix followed by the name of the content for that day. The name **cannot** include special characters (i.e \\-, \\_) and must follow the format shown.\n", + " - static/\n", + " - README.md -> (This needs to match exactly!)\n", + " - W#D#\\_DaySummary.ipynb -> (The name needs to match exactly!)\n", + " - W#D#\\_Intro.ipynb -> (The name needs to match exactly!)\n", + " - W#D#\\_Outro.ipynb -> (The name needs to match exactly!)\n", + " - W#D#\\_Tutorial#.ipynb -> (The name needs to match exactly! You can have multiple tutorials for a day as long as you number them sequentially and add the number to the materials.yml file.)\n", + " - further_reading.md -> (The name needs to match exactly!)\n", + " - static/\n", + " - materials.yml\n", + "\n", + "See a working example below:\n", + "

folder structure image

\n", + "\n", + "To reiterate, you do not need to worry about the student, instructor, or solutions directories. Those are automatically taken care of." ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": { - "cellView": "form", "execution": {} }, - "outputs": [], "source": [ - "# @title Install and import feedback gadget\n", + "## Section 3.1: Cell Tags (markings at the top of the cell)\n", + "\n", + "The workflows and processing scripts actively make use of predefined tags to determine how to process the cell. There are tags for video embeddeing, slide embedding, titles, exercises and solutions, etc. It is very important these instructions are followed **exactly**! Any deviations will break the pipeline. More details about the tags and how to use them can be found in W1D2_Tutorial1.ipynb of the template notebook.\n", + "\n", + "**NOTE**: Please read the details found in the template very carefully. Specifically the section on exercises and solutions. You need to be precise. We have a script to verify exercises that will fail if you deviate from the instructions. For example, the comments in the cells for the exercises and solutions grouping need to be **EXACT**. See below:\n", + "\n", + "Exercise:\n", "\n", - "!pip3 install vibecheck datatops --quiet\n", + "def func(ex):\n", "\n", - "from vibecheck import DatatopsContentReviewContainer\n", - "def content_review(notebook_section: str):\n", - " return DatatopsContentReviewContainer(\n", - " \"\", # No text prompt\n", - " notebook_section,\n", - " {\n", - " \"url\": \"https://pmyvdlilci.execute-api.us-east-1.amazonaws.com/klab\",\n", - " \"name\": \"neuromatch_cn\",\n", - " \"user_key\": \"y1x3mpx5\",\n", - " },\n", - " ).render()\n", + "  # comments describing the exercises\n", "\n", + "  x = ...\n", + " \n", + "  return x\n", "\n", - "feedback_prefix = \"W1D1_T4\"" + "\n", + "Solution:\n", + "\n", + "def func(ex):\n", + "\n", + "  # comment describing the exercises\n", + "\n", + "  x = ...\n", + " \n", + "  return x\n", + "\n", + "\n", + "This will fail because \"comments\" is singular in the comments of the solution cell. These checks are in place to ensure the exercise and corresponding solution cells are appropriately matched and coupled. This comment rule applies to **all** comments in the exercise/solution cells.\n", + "\n", + "The above is not an exhaustive list of the cell tags, it is simply a highlight of something that can go wrong that is easy to miss. Please find the details of all tags [here](https://neuromatch.github.io/course-content-template/tutorials/W1D2_Template/student/W1D2_Tutorial1.html). " + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "## Section 3.2: Add Images\n", + "\n", + "Your images should live in the static directories. They can be grouped into the a static directory per day, or can be inside the general static directory for all tutorials. The important thing here is that you correctly link to the proper URL. You can directly add the following html into your markdown cells in order to add images.\n", + "\n", + "\n", + "\\

\\image description\\

\n", + "\n", + "\n", + "Ex:\n", + "\n", + "\\

\\folder structure image\\

\n", + "\n", + "We recommend using .png or .gif file extensions.\n", + "\n", + "**NOTE**: This will not show up in your local development environment until the images are added to the main branch on github. As you can see from the above URL, it is pointing to the main branch of a github repository. If you would like to test it locally, you can use this:\n", + "\n", + "\\

\\image desctiption\\

\n", + "\n", + "Remember to change the source back to the github url before pushing your changes!" ] }, { @@ -106,8 +269,39 @@ }, "source": [ "---\n", - "# Section 1: Model discussions\n", - "\n" + "\n", + "# Section 4: Add Content to the materials.yml File\n", + "\n", + "The materials.yml file is used in our scripts to help verify links, populate the books, and create our table of contents. Be sure to **precisely** follow the structure outlined in the file. If you look at the materials.yml file for this template notebook, you will see the structure laid out in order for this book to properly build. There are comments in the file to further explain all the fields you will need to use. Here is an overview of the structure:\n", + "\n", + "- day: W1D1\n", + " - category: Course Content Template Instructions \n", + " - intro: https://www.youtube.com/watch?v=KxldhMR5PxA\n", + " - intro_bilibili: https://www.bilibili.com/video/BV1HT4y1E7U4/\n", + " - name: Instructions \n", + " - outro: https://www.youtube.com/watch?v=KZQXfQL1SH4\n", + " - outro_bilibili: https://www.bilibili.com/video/BV1vv411i7SG/\n", + " - playlist: https://www.youtube.com/playlist?list=PLkBQOLLbi18ObAiSOZ42YBwOQIKNvspeI\n", + "\n", + " - qa: #insert as many as Q&A video links as needed\n", + " - Insert Q&A video link 1 here \n", + "\n", + " - slides: #insert as many as slides links and titles as needed\n", + " - link: https://mfr.ca-1.osf.io/render?url=https://osf.io/rbx2a/?direct%26mode=render%26action=download%26mode=render\n", + " - title: Intro\n", + " - link: https://mfr.ca-1.osf.io/render?url=https://osf.io/6dxwe/?direct%26mode=render%26action=download%26mode=render\n", + " - title: Tutorials\n", + " - link: https://mfr.ca-1.osf.io/render?url=https://osf.io/jdumz/?direct%26mode=render%26action=download%26mode=render\n", + " - title: DaySummary\n", + " - link: https://mfr.ca-1.osf.io/render?url=https://osf.io/9hkg2/?direct%26mode=render%26action=download%26mode=render\n", + " - title: Outro\n", + " - link: https://mfr.ca-1.osf.io/render?url=https://osf.io/2esh5/?direct%26mode=render%26action=download%26mode=render\n", + " - title: Reading\n", + " - link: https://mfr.ca-1.osf.io/render?url=https://osf.io/5vj73/?direct%26mode=render%26action=download%26mode=render\n", + " - title: TA\n", + " - tutorials: 1\n", + " \n", + "Remember to create one grouping of the above content per day and be sure to set the number of tutorials." ] }, { @@ -116,32 +310,39 @@ "execution": {} }, "source": [ - "## Think! 1: Model discussions\n", + "# Section 5: Workflows\n", + "TODO: look into other workflows, ask spiros and ella\n", + "\n", + "There are two main workflows used to build the notebooks:\n", + "- notebook-pr (automatically triggered when a PR is made onto the main repo)\n", + "- publish-book (this needs to be manually triggered by navigating to the github actions tab. See Below)\n", + "Each workflow involves building python environments and running python scripts on github's servers, and then automatically creating the appropriate commits and pushes on github. The scripts handle notbeook processing, verification and html generation. After the publish-book workflow is complete, it pushes the generated html files into the gh-pages branch (it creates one if it does not exist). This branch is not to be touched and is automatically taken care of for us. All we need to do is change our pages settings under github settings to use the gh-pages branch instead of main. See Below.\n", "\n", - "Please spend the next **45 minutes** or so discussing the following questions.\n", + "Trigger publish-book:\n", + "

publish book gif

\n", "\n", - "- What is your favorite model ever\n", - " - Every student contributes one. Can not reuse the same\n", - "- Which models when?\n", - " - For which questions do you prefer what models?\n", - " - How models?\n", - " - Why models?\n", - "- Which model kinds do you like best?\n", - " - Why?\n", - " - Would you be missing something if the other models did not exist?" + "Point github pages to the gh-pages branch:\n", + "

github pages gif

\n" ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": { - "cellView": "form", "execution": {} }, - "outputs": [], "source": [ - "# @title Submit your feedback\n", - "content_review(f\"{feedback_prefix}_Model_discussions_Discussion\")" + "---\n", + "# Summary\n", + "\n", + "Congrats! You now know:\n", + "\n", + "1. how and where to create new content\n", + "2. how to follow our naming convention\n", + "3. how to prepare the notebooks for our pipeline\n", + "4. how to create branches and pull requests\n", + "5. the basics of our workflows using github actions\n", + "\n", + "Happy content creating!" ] } ], @@ -159,7 +360,8 @@ "name": "python3" }, "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", + "language": "python", "name": "python3" }, "language_info": { @@ -172,9 +374,9 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.9.17" + "version": "3.9.18" } }, "nbformat": 4, - "nbformat_minor": 0 + "nbformat_minor": 4 } diff --git a/tutorials/W1D1_Instructions/student/W1D1_Tutorial4.ipynb b/tutorials/W1D1_Instructions/student/W1D1_Tutorial4.ipynb index e0561a3f..f8e334b8 100644 --- a/tutorials/W1D1_Instructions/student/W1D1_Tutorial4.ipynb +++ b/tutorials/W1D1_Instructions/student/W1D1_Tutorial4.ipynb @@ -8,7 +8,7 @@ "id": "view-in-github" }, "source": [ - "\"Open   \"Open" + "\"Open   \"Open" ] }, { @@ -17,15 +17,21 @@ "execution": {} }, "source": [ - "# Tutorial 4: Model Discussions\n", - "**Week 1, Day 1: Model Types**\n", + "# Tutorial 4: Notebook Sections\n", "\n", - "**By Neuromatch Academy**\n", + "**Week 1, Day 1: Instructions**\n", "\n", - "__Content creators:__ Matt Laporte, Byron Galbraith, Konrad Kording\n", + "**By Neuromatch**\n", "\n", - "__Post-production team:__ Gagana B, Spiros Chavlis\n", - "\n" + "__Content creators:__ Konstantine Tsafatinos\n", + "\n", + "__Content reviewers:__ Konstantine Tsafatinos\n", + "\n", + "__Production editors:__ Konstantine Tsafatinos\n", + "\n", + "
\n", + "\n", + "Acknowledgments: [Ella Batty, Spiros Chavlis and neuromatch]\n" ] }, { @@ -35,29 +41,48 @@ }, "source": [ "___\n", - "# Tutorial Objectives\n", "\n", - "*Estimated timing of tutorial: 45 minutes*\n", + "## Tutorial Objectives\n", + "\n", + "*Estimated timing of tutorial: [15 mins]*\n", + "\n", + "In this tutorial, you will learn about the different sections and folder heirarchies in the course notebook, and how to use them.\n", + "\n", "\n", - "In this tutorial, you will reflect on what/how/why models in a group discussion and discuss your preferences and thoughts on modeling." + "You will: \n", + "\n", + "- learn how to add Art for the landing page of a tutorial day\n", + "- learn how to create Wrap Ups for a given module (category)\n", + "- learn how to add Bonus Tutorials\n", + "- learn how to add/update the course schedule\n", + "\n", + "It is recommended that you read through all of tutorials 1 through 3 as this tutorial builds upon that knowledge." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "---\n", + "## Setup (maybe remove?)\n", + "\n" ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": { - "cellView": "form", "execution": {} }, - "outputs": [], "source": [ + "In this section, we have:\n", "\n", - "# @title Tutorial slides\n", - "# @markdown These are the slides for the videos in all tutorials today\n", - "from IPython.display import IFrame\n", - "link_id = \"6dxwe\"\n", - "print(f\"If you want to download the slides: https://osf.io/download/{link_id}/\")\n", - "IFrame(src=f\"https://mfr.ca-1.osf.io/render?url=https://osf.io/{link_id}/?direct%26mode=render%26action=download%26mode=render\", width=854, height=480)" + "1. **Github Actions**: Enable github actions to allow for triggered workflows.\n", + "2. **Branches and PRs**: Create local branches, push to github, and create a pull request.\n", + "3. **Folder Structure and Naming Convention**: Guidelines to follow so that the processing and build steps work correctly.\n", + "4. **Materials.yml**: Add days and tutorials to the materials.yml file.\n", + "5. **Workflows**: Trigger the workflows." ] }, { @@ -67,36 +92,174 @@ }, "source": [ "---\n", - "# Setup" + "\n", + "## Section 1: How to enable github action\n", + " " + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "Steps:" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "- click on the settings tab in your newly created repo\n", + "- click on the actions dropdown -> general\n", + "- click on *allow all action and reusable workflows*\n", + "- click save\n", + "\n", + "

github actions gif

\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "---\n", + "\n", + "# Section 2: How to create a PR\n", + "\n", + "When creating content you want to add to the course book, you will need to have python and git installed. Afterwards, you will need to create a local python environment with all requirements for your code installed; including jyputer. Before starting to add content, you will need to create a new branch. Instructions [here](https://www.w3schools.com/git/git_branch.asp). \n", + "\n", + "Once you have created your working branch, you can then start to work on your notebook. Before saving your notebook and committing the changes to your branch, restart the kernel and clear all cells. Then you can save it, [add](https://www.w3schools.com/git/git_staging_environment.asp?remote=github) the changes, [commit](https://www.w3schools.com/git/git_commit.asp?remote=github) them, and [push](https://www.w3schools.com/git/git_push_to_remote.asp?remote=github) to github.\n", + "\n", + "**NOTE**: It is vital that you restart the kernel and clear all outputs. The processing scripts will throw an error if you do not, and the workflow will **not** complete successfully.\n", + "\n", + "**Be Careful**: Remeber to pull the lastest changes from github before you commit your work! This is important, a successful workflow execution will create new commits, and if you do not pull the those changes before your commit your local ones, there will be a commit history conflict; i.e you will not be able to push your changes.\n", + "\n", + "\n", + "How to restart kernel and clear all outputs:\n", + "\n", + "

restart kernel gif

\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "## Section 2.1: Creating a PR\n", + "\n", + "Once you have pushed the work on your new branch, you can create a PR onto the main branch. **NOTE**: This will trigger the processing workflow for the course content.\n", + "\n", + "Create a pull request:\n", + "\n", + "

pull request gif

\n", + "\n", + "\n", + "Process Notebook workflow:\n", + "\n", + "

process notebook gif

\n", + "\n", + "The process notebook workflow will automatically get triggered once a pull request is made to the main branch. It will create the student, instructor and solutions directories, verify the exercises, and prepare the content for the publish workflow. You do **not** need to create or touch the aforementioned folders. All your work should be done on the jupyter notebooks. Remember to restart the kernel and clear your output, if you do not, the process notebooks workflow will throw an error." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "# Section 3: Folder Structure and Naming Conventions\n", + "\n", + "In order for the workflows and scripts to work correctly, and for your book to properly build, you will need to **strictly** follow our folder heirarchy and naming conventions. This is what the scripts are expecting, and you will not be able to successfully build your course book if you deviate from the conventions. \n", + "\n", + "- book/ (do not touch, this get automatically created/population in the publish workflow)\n", + "- projects/ (TODO: explain this in more depth)\n", + "- tutorials/\n", + " - W#D#\\_DayName/ -> (ie. W1D1\\_InstructionsTemplate; This is strict! You must have the W#D#\\_ prefix followed by the name of the content for that day. The name **cannot** include special characters (i.e \\-, \\_) and must follow the format shown.\n", + " - static/\n", + " - README.md -> (This needs to match exactly!)\n", + " - W#D#\\_DaySummary.ipynb -> (The name needs to match exactly!)\n", + " - W#D#\\_Intro.ipynb -> (The name needs to match exactly!)\n", + " - W#D#\\_Outro.ipynb -> (The name needs to match exactly!)\n", + " - W#D#\\_Tutorial#.ipynb -> (The name needs to match exactly! You can have multiple tutorials for a day as long as you number them sequentially and add the number to the materials.yml file.)\n", + " - further_reading.md -> (The name needs to match exactly!)\n", + " - static/\n", + " - materials.yml\n", + "\n", + "See a working example below:\n", + "

folder structure image

\n", + "\n", + "To reiterate, you do not need to worry about the student, instructor, or solutions directories. Those are automatically taken care of." ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": { - "cellView": "form", "execution": {} }, - "outputs": [], "source": [ - "# @title Install and import feedback gadget\n", + "## Section 3.1: Cell Tags (markings at the top of the cell)\n", + "\n", + "The workflows and processing scripts actively make use of predefined tags to determine how to process the cell. There are tags for video embeddeing, slide embedding, titles, exercises and solutions, etc. It is very important these instructions are followed **exactly**! Any deviations will break the pipeline. More details about the tags and how to use them can be found in W1D2_Tutorial1.ipynb of the template notebook.\n", + "\n", + "**NOTE**: Please read the details found in the template very carefully. Specifically the section on exercises and solutions. You need to be precise. We have a script to verify exercises that will fail if you deviate from the instructions. For example, the comments in the cells for the exercises and solutions grouping need to be **EXACT**. See below:\n", + "\n", + "Exercise:\n", "\n", - "!pip3 install vibecheck datatops --quiet\n", + "def func(ex):\n", "\n", - "from vibecheck import DatatopsContentReviewContainer\n", - "def content_review(notebook_section: str):\n", - " return DatatopsContentReviewContainer(\n", - " \"\", # No text prompt\n", - " notebook_section,\n", - " {\n", - " \"url\": \"https://pmyvdlilci.execute-api.us-east-1.amazonaws.com/klab\",\n", - " \"name\": \"neuromatch_cn\",\n", - " \"user_key\": \"y1x3mpx5\",\n", - " },\n", - " ).render()\n", + "  # comments describing the exercises\n", "\n", + "  x = ...\n", + " \n", + "  return x\n", "\n", - "feedback_prefix = \"W1D1_T4\"" + "\n", + "Solution:\n", + "\n", + "def func(ex):\n", + "\n", + "  # comment describing the exercises\n", + "\n", + "  x = ...\n", + " \n", + "  return x\n", + "\n", + "\n", + "This will fail because \"comments\" is singular in the comments of the solution cell. These checks are in place to ensure the exercise and corresponding solution cells are appropriately matched and coupled. This comment rule applies to **all** comments in the exercise/solution cells.\n", + "\n", + "The above is not an exhaustive list of the cell tags, it is simply a highlight of something that can go wrong that is easy to miss. Please find the details of all tags [here](https://neuromatch.github.io/course-content-template/tutorials/W1D2_Template/student/W1D2_Tutorial1.html). " + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": {} + }, + "source": [ + "## Section 3.2: Add Images\n", + "\n", + "Your images should live in the static directories. They can be grouped into the a static directory per day, or can be inside the general static directory for all tutorials. The important thing here is that you correctly link to the proper URL. You can directly add the following html into your markdown cells in order to add images.\n", + "\n", + "\n", + "\\

\\image description\\

\n", + "\n", + "\n", + "Ex:\n", + "\n", + "\\

\\folder structure image\\

\n", + "\n", + "We recommend using .png or .gif file extensions.\n", + "\n", + "**NOTE**: This will not show up in your local development environment until the images are added to the main branch on github. As you can see from the above URL, it is pointing to the main branch of a github repository. If you would like to test it locally, you can use this:\n", + "\n", + "\\

\\image desctiption\\

\n", + "\n", + "Remember to change the source back to the github url before pushing your changes!" ] }, { @@ -106,8 +269,39 @@ }, "source": [ "---\n", - "# Section 1: Model discussions\n", - "\n" + "\n", + "# Section 4: Add Content to the materials.yml File\n", + "\n", + "The materials.yml file is used in our scripts to help verify links, populate the books, and create our table of contents. Be sure to **precisely** follow the structure outlined in the file. If you look at the materials.yml file for this template notebook, you will see the structure laid out in order for this book to properly build. There are comments in the file to further explain all the fields you will need to use. Here is an overview of the structure:\n", + "\n", + "- day: W1D1\n", + " - category: Course Content Template Instructions \n", + " - intro: https://www.youtube.com/watch?v=KxldhMR5PxA\n", + " - intro_bilibili: https://www.bilibili.com/video/BV1HT4y1E7U4/\n", + " - name: Instructions \n", + " - outro: https://www.youtube.com/watch?v=KZQXfQL1SH4\n", + " - outro_bilibili: https://www.bilibili.com/video/BV1vv411i7SG/\n", + " - playlist: https://www.youtube.com/playlist?list=PLkBQOLLbi18ObAiSOZ42YBwOQIKNvspeI\n", + "\n", + " - qa: #insert as many as Q&A video links as needed\n", + " - Insert Q&A video link 1 here \n", + "\n", + " - slides: #insert as many as slides links and titles as needed\n", + " - link: https://mfr.ca-1.osf.io/render?url=https://osf.io/rbx2a/?direct%26mode=render%26action=download%26mode=render\n", + " - title: Intro\n", + " - link: https://mfr.ca-1.osf.io/render?url=https://osf.io/6dxwe/?direct%26mode=render%26action=download%26mode=render\n", + " - title: Tutorials\n", + " - link: https://mfr.ca-1.osf.io/render?url=https://osf.io/jdumz/?direct%26mode=render%26action=download%26mode=render\n", + " - title: DaySummary\n", + " - link: https://mfr.ca-1.osf.io/render?url=https://osf.io/9hkg2/?direct%26mode=render%26action=download%26mode=render\n", + " - title: Outro\n", + " - link: https://mfr.ca-1.osf.io/render?url=https://osf.io/2esh5/?direct%26mode=render%26action=download%26mode=render\n", + " - title: Reading\n", + " - link: https://mfr.ca-1.osf.io/render?url=https://osf.io/5vj73/?direct%26mode=render%26action=download%26mode=render\n", + " - title: TA\n", + " - tutorials: 1\n", + " \n", + "Remember to create one grouping of the above content per day and be sure to set the number of tutorials." ] }, { @@ -116,32 +310,39 @@ "execution": {} }, "source": [ - "## Think! 1: Model discussions\n", + "# Section 5: Workflows\n", + "TODO: look into other workflows, ask spiros and ella\n", + "\n", + "There are two main workflows used to build the notebooks:\n", + "- notebook-pr (automatically triggered when a PR is made onto the main repo)\n", + "- publish-book (this needs to be manually triggered by navigating to the github actions tab. See Below)\n", + "Each workflow involves building python environments and running python scripts on github's servers, and then automatically creating the appropriate commits and pushes on github. The scripts handle notbeook processing, verification and html generation. After the publish-book workflow is complete, it pushes the generated html files into the gh-pages branch (it creates one if it does not exist). This branch is not to be touched and is automatically taken care of for us. All we need to do is change our pages settings under github settings to use the gh-pages branch instead of main. See Below.\n", "\n", - "Please spend the next **45 minutes** or so discussing the following questions.\n", + "Trigger publish-book:\n", + "

publish book gif

\n", "\n", - "- What is your favorite model ever\n", - " - Every student contributes one. Can not reuse the same\n", - "- Which models when?\n", - " - For which questions do you prefer what models?\n", - " - How models?\n", - " - Why models?\n", - "- Which model kinds do you like best?\n", - " - Why?\n", - " - Would you be missing something if the other models did not exist?" + "Point github pages to the gh-pages branch:\n", + "

github pages gif

\n" ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": { - "cellView": "form", "execution": {} }, - "outputs": [], "source": [ - "# @title Submit your feedback\n", - "content_review(f\"{feedback_prefix}_Model_discussions_Discussion\")" + "---\n", + "# Summary\n", + "\n", + "Congrats! You now know:\n", + "\n", + "1. how and where to create new content\n", + "2. how to follow our naming convention\n", + "3. how to prepare the notebooks for our pipeline\n", + "4. how to create branches and pull requests\n", + "5. the basics of our workflows using github actions\n", + "\n", + "Happy content creating!" ] } ], @@ -159,7 +360,8 @@ "name": "python3" }, "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", + "language": "python", "name": "python3" }, "language_info": { @@ -172,9 +374,9 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.9.17" + "version": "3.9.18" } }, "nbformat": 4, - "nbformat_minor": 0 + "nbformat_minor": 4 }