From 9173de45e9867f20eebef6487fe6a7e8db07f530 Mon Sep 17 00:00:00 2001 From: Ryan Lovett Date: Mon, 7 Oct 2024 23:47:06 -0700 Subject: [PATCH] Fix a lot of markdown syntax. --- connector/general/what-is-a-connector.md | 17 +++++--- faq/admin.md | 18 +++++---- technology/jupyter/python-errors.md | 12 +++--- .../jupyter/troubleshoot-nbgitpuller.md | 40 ++++++++++++------- .../options-launch-rkernel.md | 10 ++--- technology/quarto.md | 38 +++++++++--------- technology/troubleshooting_tips_students.md | 30 +++++++------- workflow/creating-notebooks.md | 16 ++++---- workflow/download_notebook_as_pdf.md | 38 +++++++----------- workflow/pushing-to-github.md | 29 +++++++------- workflow/use-realtimecollaboration.md | 28 ++++++------- 11 files changed, 147 insertions(+), 129 deletions(-) diff --git a/connector/general/what-is-a-connector.md b/connector/general/what-is-a-connector.md index 86512bb..6d25efb 100644 --- a/connector/general/what-is-a-connector.md +++ b/connector/general/what-is-a-connector.md @@ -1,10 +1,15 @@ -# What is a Connector Course? +--- +title: What is a Connector Course? +--- Connector courses allow students to apply theoretical concepts from Data 8 to a particular area of interest. Below are some details that characterize the average 2-unit connector course. This is just to give you a general idea of what connectors are like. Some connectors may not fully match this description. -![](/assets/connectors.jpg)![](/assets/hello.jpg) +```{image} ../../assets/connectors.jpg +:alt: Grid of connector logos and titles -### Prerequisites +``` + +## Prerequisites Data 8 is a pre-requisite or co-requisite for connector courses. Students should have already completed Data 8 or be taking it concurrently. @@ -12,18 +17,18 @@ Although this expectation is stated in the official course description, instruct Of course, instructors have the discretion to consider a student's enrollment on a case-by-case basis. If you are thinking about waiving the Data 8 pre-/co-requisite for a particular student, you will want to consider their other preparation, what Data 8 material they will be missing, and the overall effect it may have on the class. -### Units +## Units Connector courses have generally been two units in the past. There have not been any three unit connectors yet but this is a possibility if your connector is higher in workload. -### General Course Structure +## General Course Structure * One two-hour class meeting per week, which includes both a lab and lecture portion. Instructors decide how they want to split up two hours between lab and lecture. Some instructors choose to spend the first hour on lecture and the second on lab. Others prefer a more fluid structure and switch back and forth between lecture and lab questions throughout the two hours. * Weekly in-class lab assignment * Additional projects/homeworks/exams depending on the instructor's preference * Weekly office hours -### Workload +## Workload For students, one unit of work corresponds to three hours of work. The six hours of work for a 2-unit connector can be broken down in the following way: diff --git a/faq/admin.md b/faq/admin.md index d786e25..f0bc66e 100644 --- a/faq/admin.md +++ b/faq/admin.md @@ -1,16 +1,18 @@ -# Accessing Elevated Privileges in a Hub +--- +title: Accessing Elevated Privileges in a Hub +--- ```{note} Curious about elevated privileges in DataHub? If yes, read below! ``` -**What does elevated privilege in an hub mean?** +## What are elevated privileges? -Elevated privilege provides the necessary features required to troubleshoot students notebook interface in the hub. If you are an admin user, you can do the following, +Elevated privilege enable course staff to troubleshoot students notebook interface in the hub. If you have such privileges, you can: -1. You can start and stop the students' server in your dedicated hub -2. You can access the student server to debug issues in their notebook +1. Start and stop students' servers +2. Access students' servers to debug issues ```{warning} Elevated privileges are hub-wide. If you have a GSI teaching your course using a particular hub but is acting as a student in another course which uses the same hub, then this can result in a conflict of interest. Please report such scenarios to the infrastructure team so that we can take the necessary corrective action. @@ -26,7 +28,7 @@ Check this image to know your privileges for the admin option, Here is how the admin dashboard looks like! ``` -**How do I get elevated privileges?** +## Obtaining Elevated Privileges We generally recommend the teaching team alone to have elevated privileges in the hubs they use for the instructional purposes. If you satisfy the above criteria, please create a request using this [template](https://github.com/berkeley-dsep-infra/datahub/issues/new?assignees=&labels=support&template=admin_request.yml).The infrastructure team will assist in the process of assigning elevated privileges to the instructors. @@ -47,9 +49,9 @@ To assign elevated privileges to a set of people other than all course staff, fo If you need any help during this process of creating bcourses groups, please reach out to bcourseshelp@berkeley.edu. Please keep in mind that the bcourses page for the course should be published so that users requiring elevated privileges actually have the required access. ``` -**How do I navigate to the admin portal?** +## Admin Interface -Please follow the steps below to navigate admin interface, +Follow the steps below to navigate admin interface: - Login to your hub instance - Click the admin option from the top bar diff --git a/technology/jupyter/python-errors.md b/technology/jupyter/python-errors.md index 9582613..723cac2 100644 --- a/technology/jupyter/python-errors.md +++ b/technology/jupyter/python-errors.md @@ -1,8 +1,10 @@ -## Troubleshooting Code Cell Errors +--- +title: Troubleshooting Code Cell Errors +--- This category describes errors that occur when running code cells. This list is not exhaustive, but it details some of themost frequent errors that new Notebook users encounter. -#### NameError +## NameError By far the most common errors that new students encounter are NameErrors. An example screenshot is below: ![](../../assets/name-error.png) NameErrors occur when a code cell refers to a name that has not yet been defined. This usually happens when: @@ -16,14 +18,14 @@ Solutions: * double-check spelling, capitalization, punctuation, and spaces in variable names * make sure that if you're referring to a string, you enclose it in quotation marks -#### ValueError +## ValueError Common when dealing with table data, ValueErrors arise when misspelled column labels are used. An example screenshot is below: ![](../../assets/column-name-error.png) Solution: * The most likely solution is to review the column headers and ensure that the correct value is selected for. Python is case-sensitive, so it's important to check the spelling and capitalization of your strings/variable names. -#### TypeError +## TypeError When using a function, e.g for table manipulation, it is possible to use the incorrect kind of value. In the example below, the column relabeling function is misused, causing errors in two different ways. In this error, the function was given too many values: @@ -36,7 +38,7 @@ Solutions: * If you see an error relating to the *number* of arguments, check that you are using the correct number. If you aren't sure, refer to prior uses of the function for reference, or ask a friend. * If you see an error relating to the type, ensure that the values you use in the function call are appropriate. For example, in the case above, renaming the column requires a string, not a boolean. -#### Cells never stop running +## Cells never stop running Sometimes, cells can get "stuck" running: ![](../../assets/kernel-busy.png) diff --git a/technology/jupyter/troubleshoot-nbgitpuller.md b/technology/jupyter/troubleshoot-nbgitpuller.md index 9200709..a83296d 100644 --- a/technology/jupyter/troubleshoot-nbgitpuller.md +++ b/technology/jupyter/troubleshoot-nbgitpuller.md @@ -1,4 +1,6 @@ -# Troubleshooting nbgitpuller +--- +title: Troubleshooting nbgitpuller +--- You may run into different types of errors when you are using the JupyterHub or Jupyter notebooks. The majority of errors come from a few common causes and can be solved using the following methods. @@ -6,27 +8,35 @@ You may run into different types of errors when you are using the JupyterHub or nbgitpuller link errors are usually due to one of three issues: -#### 1. The nbgitpuller link was clicked in an incompatible browser (Microsoft Edge) +### Incompatible Browser + Unfortunately, the nbgitpuller software does not support the Microsoft Edge browser. If you click an nbgitpuller link in Edge, you will likely be taken to your datahub.berkeley.edu dashboard, but you won't see your desired files there. -Solution: open nbgitpuller links in Chrome, Firefox, or Safari +Open nbgitpuller links in Chrome, Firefox, or Safari. + +### Link Generated Incorrectly -#### 2. The nbgitpuller link was generated incorrectly If the nbgitpuller link was not generated correctly, you'll see a red loading bar with an error message that says "Error: Command '['git', 'fetch']' returned non-zero exit status 128." An example screenshot is below: -![](../../assets/broken-nbgitpuller-link.png) +```{image} ../../assets/broken-nbgitpuller-link.png +:alt: Example error output from nbgitpuller + +``` Solution: re-generate the nbgitpuller link. Make sure that you've filled in the correct Jupyter hub URL, Github URL, branch, and file. Some tips: * URLS should NOT end with forward slashes. "https://github.com/ds-modules" is okay; "https://github.com/ds-modules/" will break * The Git repository url should go to the base repo that contains the materials you want. For example, if you want to link to the "lab01.ipynb" in the fall19 repository of the data-8 organization, the Git URL should be "https://github.com/data-8/fall19", not "https://github.com/data-8/fall19/blob/master/lab01" * The File to Open needs to include the full path of the file from the base repository. For example, if the "lab01" file is in a folder called "labs", the File to Open needs to be "labs/lab01" -#### 3. The nbgitpuller link has been used before, and some of the content was changed in both DataHub and Github -If you make changes to an assignment on Github after students have started working on it, students that click the nbgitpuller link again may see a red loading bar and a message about a *merge conflict*. This occurs if the instructor and the student both change the same parts of the notebook: nbgitpuller doesn't know how to integrate the instructor's changes without overwriting student work, so it refuses to proceed. You can read [more about nbgitpuller's automatic merging behavior here](https://jupyterhub.github.io/nbgitpuller/topic/automatic-merging.html). +### Modified Content -###### Solutions: +If you make changes to an assignment on GitHub after students have started working on it, students that click the nbgitpuller link again may see a red loading bar and a message about a *merge conflict*. This occurs if the instructor and the student both change the same parts of the notebook: nbgitpuller doesn't know how to integrate the instructor's changes without overwriting student work, so it refuses to proceed. You can read [more about nbgitpuller's automatic merging behavior](https://jupyterhub.github.io/nbgitpuller/topic/automatic-merging.html). -Method 1: The easiest and most conservative solution is to rename the file or folder that contains the incompatible changes, then click the nbgitpuller link again. If the file or folder is renamed to anything else (e.g. "SOC-5-old"), nbgitpuller will clone a fresh copy of the problematic files to the student's Jupyterhub. They can then copy over any work from the old version of the file. +### Solutions + +#### Rename Files + +The easiest and most conservative solution is to rename the file or folder that contains the incompatible changes, then click the nbgitpuller link again. If the file or folder is renamed to anything else (e.g. "SOC-5-old"), nbgitpuller will clone a fresh copy of the problematic files to the student's Jupyterhub. They can then copy over any work from the old version of the file. When you face an error like below, do the following steps ```{figure} ../../images/mergeconflict.png @@ -48,7 +58,9 @@ Here is the steps required to rename the folder! - Click on the nbgitpuller link again - Use the newly cloned repository created after nbgitpuller link was clicked -Method 2: If you have command line experience then you can use "git stash" command in terminal to temporarily remove the incompatible changes. +#### git stash + +If you have command line experience then you can use "git stash" command in terminal to temporarily remove the incompatible changes. - If you are using https://datahub.berkeley.edu then navigate to your file manager which acts as your home page. If you are using other hubs then you can access your file manager by navigating to "Hub URL/user/`Your-Username`/tree" which will take you to the home directory. For eg: If my user name is Julia and I want to access my home directory in R hub then the URL to access my home directory will be https://r.datahub.berkeley.edu/user/julia/tree. - On the upper right of the page, click the dropdown menu that says “New” and select “Terminal”. @@ -58,7 +70,7 @@ Method 2: If you have command line experience then you can use "git stash" comma :align: center :name: Launch Terminal -Here is how you launch terminal +Launch a terminal ``` - Navigate to the folder where a) your files are stored and b) you have merge conflict issues @@ -67,10 +79,10 @@ Here is how you launch terminal ```{figure} ../../assets/gitstash_output.png :width: 500px :align: center -:name: Launch Terminal +:name: git stash output -Here is the output from gitstash command +Output from git stash command ``` - Access the nbgitpuller link again. You will be able to load the notebooks directly. -The best advice, however, is to avoid making changes to assignments once they've been released to students if at all possible. \ No newline at end of file +The best advice, however, is to avoid making changes to assignments once they've been released to students if at all possible. diff --git a/technology/pedagogy-and-technology/options-launch-rkernel.md b/technology/pedagogy-and-technology/options-launch-rkernel.md index ed41d4a..65d56c2 100644 --- a/technology/pedagogy-and-technology/options-launch-rkernel.md +++ b/technology/pedagogy-and-technology/options-launch-rkernel.md @@ -13,7 +13,7 @@ Step 1: Install Anaconda distribution (JupyterLab application gets installed thr Step 2: Search for "Anaconda Powershell Prompt" and Open it. Run the following code to install R Kernel in Jupyter Lab, -```{code} +```bash conda install -c r r-essentials ``` @@ -30,7 +30,7 @@ The following is a screenshot of running this command in Anaconda Powershell Pro Step 3: Run the following command in "Anaconda Powershell Prompt" to install tidyverse packages -```{code} +```bash conda install -c r r-tidyverse ``` @@ -49,7 +49,7 @@ The following is a screenshot of running the command to install tidyverse packag Step 4: Run the following command to launch Jupyter Lab -```{code} +```bash jupyter lab ``` @@ -75,13 +75,13 @@ Step 1: Launch R Kernel in Google Colab by accessing this [link](https://colab.t Step 2: Check whether the tidyverse packages (or any other package you need) is already installed in Colab by using the following code, -```{code} +```R print(installed.packages()) ``` Step 3: If not installed, Install tidyverse package using the following command -```{code} +```R devtools::install_github("tidyverse/tidyverse") ``` diff --git a/technology/quarto.md b/technology/quarto.md index a5afc24..c93e802 100644 --- a/technology/quarto.md +++ b/technology/quarto.md @@ -1,4 +1,6 @@ -# Using Quarto in DataHub +--- +title: Quarto +--- [Quarto](https://quarto.org) is an open-source publishing system that is particularly valuable for instructors who want to create dynamic, interactive course materials. Whether you're developing lecture notes, assignments, or entire textbooks, Quarto provides a powerful, flexible platform that integrates code, data, and narrative, making it ideal for educational settings. It supports a variety of programming languages, including R, Python, Julia, and Observable JavaScript, enabling instructors to design course content that actively engages students through hands-on coding exercises and real-time data analysis. @@ -8,40 +10,40 @@ :name: Convert R markdown assignments/labs with quarto to produce pdfs ``` -### Opportunities to Integrate Quarto in Your Workflow +## Why Use Quarto? -##### 1. Creating Interactive Lecture Notes +### Create Interactive Lecture Notes **Use Case:** Developing lecture notes that integrate code, data, and narrative. **How Quarto Helps:** Quarto allows you to write notes in Markdown (.qmd files) with embedded code snippets. These snippets can generate live outputs like tables, plots, and calculations directly within the notes. -##### 2. Building Course Websites +### Build Course Websites **Use Case:** Hosting all course materials online in a single, accessible location. **How Quarto Helps:** Use Quarto to render your Markdown files into a static site, which can be deployed on platforms like Netlify. This site can include lecture notes, assignments, schedules, and more. Eg: Stat 20 instructor Andrew Bray uses Quarto to generate stat20.org. Quarto is used to create and manage course materials, which are then rendered into a static website. This website is deployed on Netlify, a popular platform for hosting and deploying static sites. Netlify’s Continuous Integration/Continuous Deployment (CI/CD) pipeline automates the process of building and deploying your site whenever you update your Quarto files. This ensures that any changes you make to your course materials are automatically reflected on the live website without additional manual steps. -##### 3. Designing Assignments and Projects +### Design Assignments and Projects **Use Case:** Creating assignments where students interact with code and data directly. **How Quarto Helps:** Quarto enables you to build assignments in .qmd files that include executable code. Students can run and modify this code to complete their tasks, making the assignments more interactive and practical. -##### 4. Automating Grading with Gradescope +### Automate Grading with Gradescope **Use Case:** Efficiently grading assignments that involve coding and data analysis. **How Quarto Helps:** Integrate Quarto into the Gradescope autograder to automatically run and check the code in student submissions. The autograder can simulate environments like DataHub, ensuring consistency in grading. -##### 5. Authoring Books and Manuals +### Author Books and Manuals **Use Case:** Writing textbooks, lab manuals, or comprehensive guides. **How Quarto Helps:** Quarto supports long-form content creation, allowing you to compile multiple .qmd files into a cohesive book. You can include live code examples and data analysis, making your book interactive. -### Pathways to use Quarto in DataHub +## Use Quarto on DataHub Quarto integrates with popular Integrated Development Environments (IDEs) such as RStudio, VSCode and JupyterLab. You can visit [this website](https://quarto.org/docs/get-started/) to learn more about the detailss. @@ -51,37 +53,37 @@ Quarto integrates with popular Integrated Development Environments (IDEs) such a **VSCode:** If VSCode and [VSCode Quarto extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) are enabled in your hub, you can [use them](https://quarto.org/docs/get-started/hello/vscode.html) to render and preview quarto documents with syntax highlighting. You can also use command line tools to convert to varied documents. -### Workflow for Beginner Instructors +## Workflow for Beginner Instructors Imagine you’re preparing a lecture on data visualization. You start by writing your notes in a simple Markdown file (.qmd), adding a few basic code examples that generate charts. You then use Quarto to render these notes as a PDF handout and an HTML page for your course website. -### Steps to Convert Documents to HTML/PDF via Quarto +## Steps to Convert Documents to HTML/PDF via Quarto -##### Convert Jupyter notebook and Quarto Markdown file to HTML +### Convert Jupyter notebook and Quarto Markdown file to HTML -```{code} +```bash quarto render my-notebook.ipynb --to html ``` The above command converts your Jupyter Notebook (.ipynb) into an HTML file. -```{code} +```bash quarto render my-document.qmd --to html ``` The above command converts your Quarto Markdown file (.qmd) into an HTML file. -##### Convert Jupyter notebook and Quarto Markdown to PDF +### Convert Jupyter notebook and Quarto Markdown to PDF **Option 1:** -```{code} +```bash quarto render my-homework.ipynb --to pdf ``` The above command converts your Jupyter Notebook (.ipynb) into a PDF file. **Option 2:** -```{code} +```bash quarto render my-homework.ipynb --to typst ``` @@ -91,9 +93,9 @@ The above command converts your Jupyter Notebook (.ipynb) into a PDF file with a Typst is a modern typesetting system designed to provide a user-friendly alternative to traditional typesetting tools like LaTeX. It is intended for authors, researchers, and anyone who needs to produce documents with precise formatting and layout control, but without the steep learning curve often associated with traditional typesetting systems. For more details, check out [typst webpage](https://typst.app/) ``` -##### Convert qmd file to PDF +### Convert qmd file to PDF -```{code} +```bash quarto render my-document.qmd --to pdf ``` diff --git a/technology/troubleshooting_tips_students.md b/technology/troubleshooting_tips_students.md index 0863987..2de700c 100644 --- a/technology/troubleshooting_tips_students.md +++ b/technology/troubleshooting_tips_students.md @@ -1,38 +1,40 @@ -# Tips to Use DataHub +--- +title: Tips to Use DataHub +--- ## About the UC Berkeley DataHub: DataHub is UC Berkeley’s implementation of Jupyterhub and is a free service made available to UC Berkeley students to provide a small amount of computing and storage on a virtual machine running in the cloud. This guide provides an overview of the tasks you will need to complete before the semester begins, during the semester, and at the end of the semester. This high-level information will help you navigate your coursework effectively using the UC Berkeley DataHub. -#### Before the Semester Begins +### Before the Semester Begins -##### 1. Browser and Internet Check +#### 1. Browser and Internet Check **Browser Compatibility:** Ensure you are using a compatible web browser (Chrome, Firefox, Safari) that is updated to the latest version. **Internet Connection:** Verify you have a stable internet connection to access DataHub smoothly. -##### 2. Account Setup and Access +#### 2. Account Setup and Access **Activate CalNet ID:** Ensure your CalNet ID is activated and functioning properly. **Access DataHub:** Go to datahub.berkeley.edu and log in with your CalNet ID to verify you can access the platform. (and allow bcourses to authenticate when you get the message “DataHub is requesting access to your account”.) -##### 3. Familiarize Yourself with DataHub +#### 3. Familiarize Yourself with DataHub **Overview:** Review student resources to understand the varied features of DataHub. **Interface Tour:** Explore the DataHub interface, including the JupyterLab and RStudio environments. -#### During the Semester +### During the Semester -##### 1. Accessing Course Materials +#### 1. Accessing Course Materials **Course Hub:** Use nbgitpuller links shared by your course instructors to launch notebooks in DataHub **Notebooks and Scripts:** Open and work on Jupyter Notebooks, R scripts, or other files as provided by your instructor. **To manage files in JupyterHub:** To upload a file, click the "Upload" button in the JupyterHub interface and select the file from your local machine.To download a file, right-click on the file in the JupyterHub interface and select the "Download" option. -##### 2. Completing Assignments +#### 2. Completing Assignments **Regular Use:** Regularly log in to DataHub to complete assignments, run analyses, and work on projects. **Save Work:** Save your progress frequently. It's good practice to manually save your work as well. @@ -43,7 +45,7 @@ DataHub is UC Berkeley’s implementation of Jupyterhub and is a free service ma **Do Your Work in Sub Directories:** Create a sub directory for each assignment and do your work there. Avoid working on assignments from the root directory as they may lead to data issues if done wrongly. -##### 3. Collaboration and Sharing +#### 3. Collaboration and Sharing ```{note} DataHub doesn’t have collaboration tools at this time as we are continuously testing the latest updates. @@ -51,7 +53,7 @@ DataHub doesn’t have collaboration tools at this time as we are continuously t **Instructor Feedback:** Share your work with instructors or TAs for feedback by downloading and submitting your notebooks as required. -##### 4. Troubleshooting +#### 4. Troubleshooting **Restart Kernel/Server:** Try restarting your kernel as a classic troubleshooting step to see if the error goes away. If the problem persists, restart your server. **Kill Process:** Having too many things open on DataHub can cause issues. Sharing two different approaches to check running processes and kill them, @@ -81,14 +83,14 @@ Yes, you can access DataHub from anywhere with an internet connection. What should I do if I encounter a technical issue? First, try restarting your kernel. If the issue persists, contact your course TA, and if they can’t resolve it they will reach out to DataHub staff. -#### End of the Semester -##### 1. Backup Your Work +### End of the Semester +#### 1. Backup Your Work **Backup coursework:** Back up your notebooks and data to either your personal device or an external storage service like Google Drive, Dropbox. **User Home Directory Archiving:** Files unused for 90 days will be archived and stored in a low cost storage. You will need to open a request with the DataHub team to retrieve your unused files. -##### 2. Clean Up Your Workspace +#### 2. Clean Up Your Workspace **Clean Up:** Clean up your DataHub workspace by deleting unnecessary files and folders. -**Feedback:** Provide feedback on your experience with the DataHub team to help improve the service for future students. \ No newline at end of file +**Feedback:** Provide feedback on your experience with the DataHub team to help improve the service for future students. diff --git a/workflow/creating-notebooks.md b/workflow/creating-notebooks.md index 4475899..1ff6542 100644 --- a/workflow/creating-notebooks.md +++ b/workflow/creating-notebooks.md @@ -1,12 +1,14 @@ -# Creating Assignments +--- +title: Creating Assignments +--- Most courses in CDSS use Jupyter notebooks for assignments. Jupyter notebooks are a tool used for in-browser computing that allow you to include code, text, and visualizations on the same page. Once created, these notebooks can be distributed to students and then downloaded in various formats for submission. See an [example of a Data 8 notebook](http://datahub.berkeley.edu/user-redirect/interact?repo=data8assets&path=materials/sp17/lab/lab01). The link might take some time to download all of the files. -### Working with Jupyter Notebooks +## Working with Jupyter Notebooks Below is an short introduction on how to use Jupyter notebooks on `datahub.berkeley.edu`. Assignment development can be done on `datahub.berkeley.edu` or locally, if you already have a local Jupyter setup. The below steps assume you are working on DataHub, but most of the steps can be done on a local setup as well. If you decide to work locally, we recommend you test your notebooks on `datahub.berkeley.edu` well in advance. The development environment on DataHub is probably different from your local environment, so it is possible that code may break. -##### Create a Blank Notebook +### Create a Blank Notebook This section describes how to create a notebook on the JupyterHub infrastructure. Go to [datahub.berkeley.edu](https://datahub.berkeley.edu). Click on the green `Start My Server` button. You will not need to do this if you are working locally. @@ -18,7 +20,7 @@ Click on the `New` dropdown on the right side of the page. Select the option for You will see a blank notebook to which you can now add text and code. The notebook consists of sections called cells. There are different types of cells that can be used. Code is part of the "code" cell type and text is part of the "markdown" cell types. -##### Add a New Cell +### Add a New Cell You can add a new cell using eiher the `+` button on the left side or the `Insert` button on the toolbar. @@ -36,7 +38,7 @@ You will notice that there is no code output in the previous image. In addition, ![](https://cloud.githubusercontent.com/assets/8205702/23251108/dcada876-f960-11e6-9629-ac8a1bdbe116.png) -##### Run Code +### Run Code You can run code by either typing Shift-Enter from the cell or clicking the play button in the toolbar \(triangle with a line\). @@ -46,13 +48,13 @@ Code that has been run in one cell is accessible by another cell. If any change ![](https://cloud.githubusercontent.com/assets/8205702/23251192/394dfd9c-f961-11e6-8bef-d1aa93c18dec.png) -##### Download Notebooks +### Download Notebooks Click on `File` in the toolbar, then `Download as`, then select `Notebook (.ipynb)` . This will download the notebook to your computer in the standard Jupyter notebook format. You can also download notebooks in alternate formats, seen below. ![](https://cloud.githubusercontent.com/assets/8205702/23284842/8995ced4-f9e2-11e6-809e-2b46bd7833da.png) -### Additional Resources +## Additional Resources * [Markdown basics notebook](http://datahub.berkeley.edu/user-redirect/interact?repo=connector-instructors&path=examples/external_notebooks/markdown_basics.ipynb) - Double clicking on each cell allows you to see how a variety different content is formatted in Jupyter Notebooks. diff --git a/workflow/download_notebook_as_pdf.md b/workflow/download_notebook_as_pdf.md index 360cfd1..d37119b 100644 --- a/workflow/download_notebook_as_pdf.md +++ b/workflow/download_notebook_as_pdf.md @@ -22,52 +22,44 @@ File -> Save and Export Notebook As -> HTML :name: Download Jupyter Notebook as HTML ``` -````{note} +```{note} When it comes to embedding images in Jupyter notebooks so that it is available as part of PDF, there are various methods to include images. Below are the five options to embed an image of an early Mathematica interface. +``` -#### HTML Image Tag +#### HTML Image -```{code} +```html Early Mathematica Interface ``` This method uses standard HTML to embed an image. It is straightforward and allows for extensive customization through HTML attributes like style and class. -#### Markdown Image Syntax +#### Markdown Image -```{code} +```markdown ![mathematica](mathematica.png) ``` Markdown provides a simple syntax for embedding images. This method is concise and ideal for use in Markdown cells in Jupyter notebooks. -#### HTML in Markdown Cell +#### Markdown Image with Attachment -```{code} -Berkeley Logo +```markdown +![mathematica.png](attachment:5265a161-c705-42fc-a3ed-ec1fde427030.png) ``` -Embedding an image using HTML within a Markdown cell offers the flexibility of HTML while allowing the cell to remain in Markdown mode. This is useful for more complex styling and alignment requirements. +This method is used to embed an image as an attachment within a Jupyter notebook. It references the image by its attachment identifier, which is useful for images embedded directly within the notebook file. + +```{warning} +All image links referred as part of the Jupyter Notebook should use *https://* and not *http://*. Serving http content within https pages are referred to as [mixed content requests](https://www.cloudflare.com/learning/ssl/what-is-mixed-content). Modern browsers consider these requests to be a security risk and will refuse to load them when using default security settings. +``` #### IPython Display Module -```{code} +```python from IPython.display import display, Image display(Image(filename="mathematica.png", width=250))\ ``` The IPython.display module provides functions to display images directly in Jupyter notebooks. -#### Markdown Image with Attachment - -```{code} -![mathematica.png](attachment:5265a161-c705-42fc-a3ed-ec1fde427030.png) -``` - -This method is used to embed an image as an attachment within a Jupyter notebook. It references the image by its attachment identifier, which is useful for images embedded directly within the notebook file. - -```` - -```{warning} -All image links referred as part of the Jupyter Notebook should be adhering to https and not http. Serving http content within https pages are referred to as [mixed content requests](https://www.cloudflare.com/learning/ssl/what-is-mixed-content). Modern browsers consider these requests to be a security risk and will refuse to load them when using default security settings. -```` diff --git a/workflow/pushing-to-github.md b/workflow/pushing-to-github.md index 4e0daab..c383b86 100644 --- a/workflow/pushing-to-github.md +++ b/workflow/pushing-to-github.md @@ -1,14 +1,16 @@ -# Uploading Files to GitHub +--- +title: Uploading Files to GitHub +--- -### What are Git and GitHub? +## What are Git and GitHub? Git is a version control software that tracks changes in files and allows multiple users to work on the same files in parallel smoothly. Git is often used in conjunction with GitHub, a website that hosts code and files. A repository \(aka repo\) on GitHub holds the files for a specific project. GitHub’s web interface also displays the information that Git tracks, such as which users are working on a file and what changes have been made to the file. -### Why should I store materials on GitHub? +## Why should I store materials on GitHub? Storing materials on the GitHub allows you to use interact links for assignment distribution. It's also allows you to use the version control features that Git provides. Most connector courses have a public and private repo for their courses in the data-8 GitHub organization, which acts a centralized location for the material across semesters. -### Using the Web Interface +## Using the Web Interface You can perform many actions such as uploads and downloads directly through GitHub's web interface directly, without having to use the command line interface. Here are some directions on how to upload assignments to GitHub. If you did your development on JupyterHub, download the notebook onto your computer. Then, go to your connector's GitHub repository and click `Upload Files` on the right side. @@ -24,9 +26,9 @@ You will then see an option to select the branch for your changes. The default f Once you've gone through the above steps, you can save your changes. A set of changes in Git is called a commit. -## ![](https://cloud.githubusercontent.com/assets/8205702/23319717/9f1fb81e-fa8c-11e6-86ae-074f2c11e9f5.png) +![](https://cloud.githubusercontent.com/assets/8205702/23319717/9f1fb81e-fa8c-11e6-86ae-074f2c11e9f5.png) -### Using the Command Line +## Using the Command Line GitHub can also be used via the command line. We will not go into the details of how to use Git in this guide as there are many online resources on this topic. One resource for using Git over the command line is linked at the bottom of this page. @@ -38,21 +40,18 @@ You will then see a terminal page in the browser. ![](https://cloud.githubusercontent.com/assets/8205702/23321085/a981a654-fa92-11e6-98e2-f64bf92600bc.png) -### Additional Resources +## Additional Resources -##### **Web Interface** +### Web Interface * [Managing Files](https://help.github.com/categories/managing-files-in-a-repository) - contains information under the "Managing Files on GitHub" section on how to perform many basic file operations using the GitHub web interface. * [Hello World Exercise](https://guides.github.com/activities/hello-world) is a short exercise that walks you through additional GitHub features such as branches and pull requests. -##### Command Line - -* [Atlassian Tutorials](https://www.atlassian.com/git/tutorials\) - tutorials for different levels of Git Users. - -##### Desktop GUI - -* [Desktop GUI site](https://desktop.github.com/\) - information on using a GitHub desktop GUI. +### Command Line +* [Atlassian Tutorials](https://www.atlassian.com/git/tutorials) - tutorials for different levels of Git Users. +### Desktop GUI +* [Desktop GUI site](https://desktop.github.com/) - information on using a GitHub desktop GUI. diff --git a/workflow/use-realtimecollaboration.md b/workflow/use-realtimecollaboration.md index c67ecc9..b175a00 100644 --- a/workflow/use-realtimecollaboration.md +++ b/workflow/use-realtimecollaboration.md @@ -1,4 +1,6 @@ -# Enabling Real Time Collaboration feature in DataHub +--- +title: Enabling Real Time Collaboration feature in DataHub +--- [Real-Time Collaboration in Jupyter](https://github.com/jupyterlab/rtc) is one of the most requested functionalities, which has also proven to be a complex use case to develop. A little bit of context about RTC, It was previously deployed as part of the Stat 159 hub during Spring 22. However, we found [severe data corruption issues](https://github.com/berkeley-dsep-infra/datahub/pull/3287) which led to disabling RTC. Many issues were fixed as part of the `jupyter_collaboration` package which is an extension that enables RTC in the latest Jupyter Lab 4 version. However, a subset of users in the Data 100 SU 23 course were affected with random error messages (snapshotted below) which went away after disabling the `jupyter_collaboration` package. @@ -10,33 +12,29 @@ Here is a random error message received by Data 100 users ``` -```{note} RTC feature is still in a testing stage. New bugs get uncovered and are also fixed immediately -``` -```{note} Please do keep in mind that if you as an instructor wants to distribute links to students enrolled in your course then you should consider generating and distributing links through [nbgitpuller](distributing-notebooks#the-steps) pathway. However, If you are considering usecase around students working collaboratively using Jupyter notebooks then consider RTC. -``` + We are looking for instructors who are interested to pilot RTC in their course setting. If you are interested in enabling RTC functionality then please do make a [github request](https://github.com/berkeley-dsep-infra/datahub/issues/new?assignees=balajialg&labels=type%3A+enhancement&projects=&template=featurerequest.md). Do keep in mind that you are deploying an early-stage bleeding edge version of RTC and are open to the possibility that hub stability and/or data integrity could get impacted by this decision. -```{note} -### Data considerations for adopting RTC! -- User notebooks [were corrupted](https://github.com/jupyterlab/jupyterlab/issues/14031) in RTC hosted hub. +## Data Considerations + +User notebooks [were corrupted](https://github.com/jupyterlab/jupyterlab/issues/14031) in RTC hosted hub. -### Security considerations for adopting RTC! +## Security Considerations - If a user shares a link with another user, They can modify all the files in the owner's home directory for the specific hub, including other assignments and homework. - When a user who owns the notebook stops the server, then the validity of the shared link expires - either explicitly from the control panel or after non-activity for 60 minutes. - There is no option for the notebook owner to revoke the link, but they can stop the server, which makes the shared link invalid. - Anyone can forward the generated link to the next person as there is no link-level user control. Users would have to be careful where they share links while that server is active since anyone on the internet could gain control. - An user who has access to the shared link needs to leave the current session to go and work on their files. -``` -### Steps to enable RTC +## Enable RTC You can start collaborating with others by following the below steps, -##### Step 1 +### Step 1 Open your IPython (ipynb) notebook files in Jupyter Lab interface. If you are unsure how to generate a nbgitpuller link to access your notebook in Jupyter Lab or Retro Lab interfaces, Please install this [plugin](https://addons.mozilla.org/en-US/firefox/addon/nbgitpuller-link-generator/?utm_source=addons.mozilla.org&utm_medium=referral&utm_content=search) in the Mozilla Firefox browser, which will walk you through the steps required to generate the link for the file easily. @@ -44,7 +42,7 @@ Open your IPython (ipynb) notebook files in Jupyter Lab interface. If you are un Please do keep in mind that Real-Time Collaboration(RTC) functionality is not enabled in classic notebook and retro lab interfaces! ``` -##### Step 2 +### Step 2 As a next step, Generate the shareable link to be shared with your collaborators. Follow the below steps to generate this link, - In the Menu bar, Click on the Share option (option next to Help). - Select "Share Jupyter Server Link" which opens a prompt a the centre of the screen that shows an option to copy the shareable link. @@ -58,7 +56,7 @@ As a next step, Generate the shareable link to be shared with your collaborators Here is how you can generate a shareable link ``` -##### Step 3 +### Step 3 Share this link with your collaborators. They will be able to access your notebooks immediately and make edits to the notebook in real-tim You can also see the cursors from other users with an anonymous username, a username that will disappear in a few seconds to make room for what is essential, the document’s content. @@ -70,5 +68,7 @@ You can also see the cursors from other users with an anonymous username, a user Real Time Collaboration (RTC) in action ``` +## Learn More + If you are interested to learn more about how real time collaboration works in Jupyter Lab, do refer to this [documentation](https://jupyterlab.readthedocs.io/en/stable/user/rtc.html) If you are interested to get under the hood of real time collaboration and understand the framework enabling the shared data type, do refer to this [documentation](https://github.com/yjs/yjs)