Merge pull request #19 from ryanlovett/misc-fixes

Misc fixes

_toc.yml

@@ -58,8 +58,7 @@ parts:
     title: Download Jupyter Notebook as PDF
   - file: workflow/download-archive.md
     title: Download DataHub home directory contents as archive
-  - file: workflow/performance_issue.md
-    title: Best Practices to Avoid Performance Issues
+  - file: workflow/performance-issue.md
   - file: workflow/calculate-compute-cost.ipynb
     title: Cost of Compute Intensive Scenarios
   - file: workflow/securely-push-github

faq/share.md

@@ -1,21 +1,18 @@
-# Sharing information about the Hub
+---
+title: Evangelizing DataHub
+---
 
-```{note}
-Interested to be our evangelist? See below!
+## Spread the Word
 
-```
+We are always interested in getting case studies of how different teaching teams used their hub and tweaked it according to their needs. So reach out to [Eric Van Dusen](mailto:[email protected]) or [Balaji Alwar](mailto:[email protected]) if you are interested in sharing your experience using hub over the past semesters!
 
-**How do I spread the word about the hub?**
+## Learn More
 
-We are always interested in getting case studies of how different teaching teams used their hub and tweaked it according to their needs. So reach out to [Eric Van Dusen](mailto:[email protected])/[Balaji Alwar](mailto:[email protected]) if you are interested in sharing your experience using hub over the past semesters!
-
-**What are the collaterals that I can use to share the information about this initiative?**
-
-- Anyone interested to know more about Data initiatives at Berkeley, can take a look at Computing, Data Science and Society's (CDSS) [website](https://data.berkeley.edu/external).
+- Anyone interested to know more about Data initiatives at Berkeley, can take a look at Computing, Data Science and Society's (CDSS) [educational partners](https://cdss.berkeley.edu/dsus/data-science-resources/educationalpartners).
 
 - [Data science modules](https://ds-modules.github.io/) are short explorations into data science that give students the opportunity to work hands-on with a data set relevant to their course and receive some instruction on the principles of data analysis, statistics, and computing. Here is the [link](https://github.com/ds-modules) to DS-Modules repository which has information on the many courses using it at Berkeley. Reach out to Eric Van Dusen (ericvd@berkeley) if you want help to make notebooks.
 
-- Otter Grader is a light-weight, modular open-source autograder developed by the Data Science Education Program at UC Berkeley. If you are interested to learn more about this autograding software then see [Otter Grader's documentation](https://otter-grader.readthedocs.io/en/latest/).
+- [Otter Grader]((https://otter-grader.readthedocs.io/en/latest) is a light-weight, modular open-source autograder developed by the Data Science Education Program at UC Berkeley.
 
 - If you are interested to learn more about the conversations by the Jupyter Hub community, then check [Jupyter's discourse site](https://discourse.jupyter.org/).
 

technology/nbgitpuller.md

@@ -0,0 +1,21 @@
+---
+title: nbgitpuller
+---
+
+nbgitpuller links simplify the assignment distribution process. Rather than downloading files from an external source and then uploading to their personal JupyterHub accounts, users can obtain all files for a given assignment with just one click. When a user clicks on an nbgitpuller link for a particular assignment, all files for the assignment will show up in the user's personal JupyterHub account.
+
+## Restrictions
+
+To use an nbgitpuller link, files must be stored in a public GitHub repo. Currently, nbgitpuller links are only supported for certain repositories. You can either store content in one of the allowed repositories or contact us on Piazza to add your repository to the list of approved ones. In the future, we will provide automatic nbgitpuller link support for all repositories.
+
+## Components
+
+Here is an nbgitpuller link with the various components highlighted in different colors. The grey portions of the link are needed for formatting and will remain the same for each links. The colored portions will be different for each link. If you are new to GitHub you may want to familiarize yourself with the basics \(repositories, branches, etc.\) to better understand each component.
+
+![](/assets/interact-link.png)
+
+## nbgitpuller Link Generator
+
+nbgitpuller links can be manually created in the format shown above, or can be automatically generated using [this](https://jupyterhub.github.io/nbgitpuller/link.html) tool. The nbgitpuller link generator tool allows users to specify a JupyterHub URL and GitHub url as inputs. The tool will generate an nbgitpuller link for the specified GitHub content and JupyterHub.
+
+For example, to pull [this](https://github.com/data-8/mcb-88-connector/tree/gh-pages/exercises/lab5) folder into a JupyterHub account on datahub.berkeley.edu, select "datahub.berkeley.edu" as the desired hub, paste the GitHub url "[https://github.com/data-8/mcb-88-connector/tree/gh-pages/exercises/lab5](https://github.com/data-8/mcb-88-connector/tree/gh-pages/exercises/lab5)" into the generator, and hit the convert button. The output should be "[https://datahub.berkeley.edu/user-redirect/interact?account=data-8&repo=mcb-88-connector&branch=gh-pages&path=exercises/lab5](https://datahub.berkeley.edu/user-redirect/interact?account=data-8&repo=mcb-88-connector&branch=gh-pages&path=exercises/lab5)". This link will copy the desired folder into JupyterHub.

technology/using-ai-llm.md

@@ -1,55 +1,53 @@
-# Using generative AI in Jupyter
+---
+title: Using Generative AI
+---
 
 ## Introduction
 
 Jupyter AI integrates generative AI into Jupyter, allowing users to interact with AI models directly within their notebooks. This guide explains how to use Jupyter AI in your teaching and research.
 
 ## Disclaimer
 
-**Note**: The DataHub infrastructure team does not currently support the deployment of Large Language Models (LLMs) for courses using DataHub. Limited compute resources and the lack of TPUs/GPUs make it challenging to deploy language models, and doing so could lead to a significant increase in cloud costs. For these reasons, deploying language models on DataHub is considered on a case-by-case basis.
+The DataHub infrastructure team does not currently support the deployment of Large Language Models (LLMs) for courses using DataHub. Limited compute resources and the lack of TPUs/GPUs make it challenging to deploy language models, and doing so could lead to a significant increase in cloud costs. For these reasons, deploying language models on DataHub is considered on a case-by-case basis.
 
 In one course, a smaller language model known as DistilBERT was deployed by bumping CPU resources. Here is an [example notebook](https://data100.datahub.berkeley.edu/hub/user-redirect/git-pull?repo=https%3A%2F%2Fgithub.com%2FDS-100%2Fsp24-student&urlpath=lab%2Ftree%2Fsp24-student%2F%2Fhw%2Fhw03%2Fhw03.ipynb&branch=main) using distiBERT. If you're considering using language models or any AI model in your teaching workflow, we strongly recommend scheduling a consultation with the DataHub team at the start of the semester or a few weeks prior to the assignment release. This proactive approach helps determine the feasibility and necessary optimizations to ensure smooth operations.
 
 ## Key Features
 
 Let's look at some interested usecases of Jupyter-AI,
 
-- **Magic Commands**: Use `%%ai` in notebooks to interact with AI models.
-- **Chat Interface**: Chat with AI models within JupyterLab.
-- **Model Support**: Works with various AI providers like OpenAI, Hugging Face, etc.
-- **Local Models**: Supports running local AI models for privacy.
+- Magic Commands: Use `%%ai` in notebooks to interact with AI models.
+- Chat Interface: Chat with AI models within JupyterLab.
+- Model Support: Works with various AI providers like OpenAI, Hugging Face, etc.
+- Local Models: Supports running local AI models for privacy.
 
 ## Getting Started
 
 ### Setting Up API Keys
 
-1. **Obtain API Keys**:
-   - Get API keys from your chosen AI model provider (e.g., OpenAI, Hugging Face).
+1. Obtain API Keys. Get API keys from your chosen AI model provider (e.g., OpenAI, Hugging Face).
 
-2. **Set Up API Keys in Your Notebook**:
-   - Add your API key to the environment variables in your Jupyter notebook:
-     ```python
-     %env PROVIDER_API_KEY=YOUR_API_KEY_HERE
-     ```
+2. Set Up API Keys in Your Notebook. Add your API key to the environment variables in your Jupyter notebook:
+   ```python
+   %env PROVIDER_API_KEY=YOUR_API_KEY_HERE
+   ```
 
 ### Using Magic Commands
 
-1. **Load the AI Magic Command**:
-   - In your notebook, run:
-     ```python
-     %load_ext jupyter_ai
-     ```
+1. Load the AI Magic Command. In your notebook, run:
+   ```python
+   %load_ext jupyter_ai
+   ```
 
-2. **Use the AI Magic Command**:
-   - To generate text or perform other AI tasks, use the following command:
-     ```python
-     %%ai
-     Your prompt to the AI model here.
-     ```
+2. Use the AI Magic Command. To generate text or perform other AI tasks, use the following command:
+   ```python
+   %%ai
+   Your prompt to the AI model here.
+   ```
 
 ### Using the Chat Interface
 
-- **Access the Chat UI**:
+- Access the Chat UI:
   - Open the chat interface in JupyterLab to interact with the AI conversationally.
 
 ## Examples
@@ -58,4 +56,4 @@ Explore example notebooks provided in the Jupyter AI repository to see how to us
 
 ## Getting Help
 
-For detailed instructions, troubleshooting, and further information, refer to the [official Jupyter AI documentation](https://jupyter-ai.readthedocs.io).
+For detailed instructions, troubleshooting, and further information, refer to the [official Jupyter AI documentation](https://jupyter-ai.readthedocs.io).

workflow/bestpractices.md

@@ -1,8 +1,12 @@
-# Instructional Design Best Practices for Creating Jupyter Notebooks
+---
+title: Authoring Best Practices
+---
 
 Designing an effective strategy for developing and utilizing Jupyter Notebooks as part of your teaching methodology can be a challenging task. Here are some best practices to consider when creating your notebooks:
 
-**Identify Learning Outcomes:** Clearly define the learning outcomes you want to achieve using Jupyter Notebooks for your course or module. Consider the following questions:
+## Identify Learning Outcomes
+
+Clearly define the learning outcomes you want to achieve using Jupyter Notebooks for your course or module. Consider the following questions:
 
 - Are the students expected to learn a specific programming language?
 - Are the students expected to learn a new technology or installation process?
@@ -11,18 +15,22 @@ Designing an effective strategy for developing and utilizing Jupyter Notebooks a
 - Will students publish their notebooks as PDFs, HTML websites, dashboards, Jupyter Books, etc.?
 - What kind of datasets are required to achieve the desired learning outcomes?
 
-**Choose an Ideal Pedagogical Strategy:** Select a suitable pedagogical approach to deliver your notebook content. Below are some examples of pedagogical strategies you can adapt for your course:
+## Choose an Ideal Pedagogical Strategy
+
+Select a suitable pedagogical approach to deliver your notebook content. Below are some examples of pedagogical strategies you can adapt for your course:
 
 - Direct Instruction: Teacher-led demonstrations and explanations.
 - Inquiry-Based Learning: Encourages students to ask questions and explore.
 - Collaborative Learning: Students work together to solve problems and complete tasks.
 - Flipped Classroom: Students review content outside of class and engage in activities during class time.
 
-**Identify Technology Requirements:** Based on your answers to the questions above, determine the necessary technology and resources, such as software, hardware, and datasets, to support the learning outcomes.
+## Identify Technology Requirements
+
+Based on your answers to the questions above, determine the necessary technology and resources, such as software, hardware, and datasets, to support the learning outcomes.
 
 By carefully considering these factors, you can create a structured and effective approach to integrating Jupyter Notebooks into your teaching.
 
-### Pedagogical strategies for notebook creation
+## Pedagogical strategies for notebook creation
 | Pedagogical Approach Name | Course Name |  Notebook Example | Pedagogical Approach Description
 | ---- | ----------- | ------ | ------- |
 | Cell Execution | Data 101 (Data Engineering) | [Lecture 2 Notebook](https://fa23.data101.org/resources/assets/lectures/lec02/lec02.html) | Students use this notebook to learn  how to connect to a Postgres database hosted in a cloud server. The pedagogical approach followed is to do "Shift-Enter" to execute all the cells and in the process understand to work with Postgres database. Students read data from the database, run complex queries against the data to perform analysis |
@@ -31,13 +39,13 @@ By carefully considering these factors, you can create a structured and effectiv
 | Explore APIs | EPS 88 (PyEarth) | [Week 2 Assignment](https://github.com/ds-modules/EPS88-24031-FA23/blob/main/week02_datahubfiles/W02_assignment_Earthquakes.ipynb) | In this notebook, students query a remote server hosted by US Geological Survey Org to get data about areas in the globe where an earth quake has happened and whose magnitude is greater than 5.0. They create a map highlighting  those places |
 Hello World | Econ 130 (Economics for Public Policy) | [Intro Jupyter notebook](https://github.com/ds-modules/ECON-130-FA23/blob/main/IntroToR/Intro%20to%20R.ipynb) | Many courses have this intro notebook where student perform basic operations in Python/R to understand the syntax of the programming language. Instructors spend a week helping students get accustomed to the chosen programming language | 
 
-### Tips for Notebook Creation
+## Tips for Notebook Creation
 
 - Have a text to code ratio of 3:1
 - Explain the ouput of the cell in the text annotation above each cell
 - Have an intro Jupyter notebook which focuses on exposing students to syntactical elements of the programming language
 
-### References
+## References
 - [Teaching and Learning with Jupyter](https://jupyter4edu.github.io/jupyter-edu-book/index.html)
 - [Best practices for writing and sharing computational analysis in Jupyter notebooks](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6657818/)