Skip to content

Commit

Permalink
Merge pull request #81 from ds-modules/cg_update
Browse files Browse the repository at this point in the history 
Onboarding doc updates
  • Loading branch information
@balajialg
balajialg authored Aug 9, 2024
2 parents a9437fe + d883289 commit b36c1f7
Show file tree
Hide file tree
Showing 2 changed files with 89 additions and 42 deletions.
50 changes: 39 additions & 11 deletions faq/onboarding.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,48 @@
# Get yourself onboarded to DataHub

```
**I am instructor planning to teach using Datahub. What should I know prior to the start of the semester?**

Dear Instructor, Datahub team is available to support you through this process. Sharing few onboarding tips that would make it easy for you to get familiar with Datahub and interact with the support team.

- **Github Issues:** The best way to request help with the Datahub is handled through filing an issue on the github page for the datahub deployment: https://github.com/berkeley-dsep-infra/datahub/issues
- **Slack Channel:** For urgent troubleshooting, you or your course staff can also use uctech.slack.com (anyone with a berkeley.edu account can get in) and join the #ucb-datahubs channel to touch base with the infra team.
- **Documentation:** You can also refer to the FAQ section of this support documentation where we regularly update solutions to some of the reported issues.
- **Packages:** Check whether all the needed Python/R packages along with their required versions are installed in the instructional hubs you use for teaching. If certain packages are not present, please use the following [template](https://github.com/berkeley-dsep-infra/datahub/issues/new?assignees=felder%2Cbalajialg&labels=package-request&template=package_request.yml&title=Request+python+package+X+for+class+Y) to make a request to the support team.
- **Elevated Privileges:** Do you want your instructional staff to troubleshoot student servers when they have issues. You can get elevated privileges which allows for viewing and accessing student servers in DataHub. If you need to access student servers, You can use this [template](https://github.com/berkeley-dsep-infra/datahub/issues/new?assignees=balajialg&labels=support&template=admin_request.yml) to make the request for the requested hub.
- **Big Assignments / High Usage times:** You can share the important date(s)/time(s) for workshops/exams/assignments etc. in your course the compute requirement is greater than regular usage during this semester. You can provide us with the required information using this [template](https://github.com/berkeley-dsep-infra/datahub/issues/new?assignees=felder%2Cbalajialg&labels=support&template=resourcescheduler.yml&title=Increase+compute+resources+for+Course+XXX+between+specific+date%28s%29%2Ftime%28s%29).
- **Newsletter:** Are you interested to learn about some of the latest infrastructure changes, case studies of faculty doing interesting work, and scheduled workshops related to Datahub and other tools part of Berkeley Data Science Teaching Stack? If yes, Check our [newsletter](https://ucberkeleydatahub.substack.com/p/january-edition-of-berkeley-datahub) and subscribe to it if you think the information shared is useful! Some new things to know about are,
- **Datahub Link Generator Plugin:** There is a [plugin in the Google Chrome store](https://chromewebstore.google.com/detail/datahub-link-generator/ijbgangngghdanhcnaliiobbiffocahf?hl=en) which helps with generating distributable links from Github.
##### General Updates

**Proactive Support Requests:** Please submit support requests for software changes and resource allocations before instruction begins. This helps us to ensure that your requests can be accommodated and will not disrupt other course environments. Ideal time frames to make requests are either **before the start or during the first two weeks of the semester**. We recommend this timeline to ensure that we make minimal changes to the hub infrastructure when the courses are ongoing.

**Assignment Deadlines:** Please try to schedule assignments during regular working hours so that infrastructure staff can troubleshoot hubs if something goes wrong.

**Test Assignments in Advance:** Please try to test assignments and notebooks on the hub before giving them to students. This will allow time for the infra team to fix any issues you discover.

**Export to PDF Using WebPDF:** We recommend using the “Save and Export Notebook as -> WebPDF” option to convert Jupyter notebooks to PDF. We have resolved the image rendering issues previously encountered with this method and are hoping for a smoother conversion process. For more details on PDF conversion, please refer to the [documentation](https://ds-modules.github.io/curriculum-guide/workflow/download_notebook_as_pdf.html).

**Using Language Models in Assignments:** If you plan to incorporate language models into your assignments then please schedule a consultation with the infra team before releasing the assignments to students. For more details, please refer to the [documentation](https://ds-modules.github.io/curriculum-guide/technology/using-ai-llm.html).

**Datahub Link Generator:** A Berkeley specific fork of nbgitpuller browser extension called [“Datahub Link Generator”](https://chromewebstore.google.com/detail/datahub-link-generator/ijbgangngghdanhcnaliiobbiffocahf?hl=en) has been developed with few additional features. Please uninstall the old extension and reinstall the [latest version](https://chromewebstore.google.com/detail/datahub-link-generator/ijbgangngghdanhcnaliiobbiffocahf?hl=en) in Chrome so that you can get the recent updates and support. We encourage you to review this [documentation](https://ds-modules.github.io/curriculum-guide/workflow/distributing-notebooks.html#datahub-link-generator-chrome-extension) which provides detailed steps to generate assignment links through the new extension.

**Backup Students' Data:** We recommend that you inform students to back up their data (notebooks and datasets) on their local devices before the end of the semester. We have prepared [download instructions](https://ds-modules.github.io/curriculum-guide/workflow/download-archive.html) on how students can retrieve all of their archived files. We receive a lot of student requests to retrieve their files after the completion of the semester. Any upfront communication from your end about backing up their files will hopefully ease the workload for us.

**Otter Grader Upgrade:** If you are interested in moving to the latest versions of otter-grader then please reach out to [email protected] and [email protected].

##### DataHub - Support Overview

**GitHub Issues:** The best way for instructional staff to request help with the DataHub is through filing an issue using the [GitHub templates](https://github.com/berkeley-dsep-infra/datahub/issues/new/choose).

**Slack Channel:** If you have anything you'd like to discuss with w/the infra team, please join the Slack channel. Access [uctech.slack.com](http://uctech.slack.com/) (anyone with a berkeley.edu account can get in) and join the #ucb-datahubs channel to interact with the infra team.

**Datahub Service Lead:** In addition, you can reach out to Balaji Alwar <[email protected]> directly if there are time-sensitive issues.

##### Datahub - Common Requests
**Packages:** Please test your assignments for hub compatibility before the start of the semester. Check whether all the needed Python/R packages and their required versions are installed. If not, please use the [package request template](https://github.com/berkeley-dsep-infra/datahub/issues/new?assignees=felder%2Cbalajialg&labels=package-request&template=package_request.yml&title=Request+python+package+X+for+class+Y) to raise a request to the infra team. The Infra team requires at least 2 business days for a turnaround on support requests such as this.

**Elevated Privilege Access:** You can use this [GitHub template](https://github.com/berkeley-dsep-infra/datahub/issues/new?assignees=balajialg&labels=support&template=admin_request.yml) to request [elevated privileges](https://ds-modules.github.io/curriculum-guide/faq/admin.html?highlight=admin) for course staff to troubleshoot student servers in the requested hub.

**Big Assignments / High Use times:** You can share the important date(s)/time(s) for workshops/exams/assignments etc. when you expect the resource requirement to be greater than usual. We will review your request and get back to you directly about the feasibility of increasing resources. You can provide us with all the relevant information using the [calendar event scheduling template](https://github.com/berkeley-dsep-infra/datahub/issues/new?assignees=felder%2Cbalajialg&labels=support&template=resourcescheduler.yml&title=Increase+compute+resources+for+Course+XXX+between+specific+date%28s%29%2Ftime%28s%29).

##### Other Updates

**a11y Documentation:** For further insights into improving the accessibility of the Jupyter Notebook/Lab experience for students, please review this [documentation](https://ds-modules.github.io/curriculum-guide/workflow/accessibility.html?highlight=accessibility) that provides a few tips for improving the accessibility of the notebooks.

**JupyterLab a11y Checker:** Please check out the [JupyterLab a11y-checker extension](https://pypi.org/project/jupyterlab-a11y-checker/) that performs multiple accessibility checks on Jupyter notebook/Lab cells containing images and headings. It does the following, a) Verifies the presence of alt-text for images, ensuring that visually impaired users can understand their content, b) Calculates the colour contrast ratio to ensure readability for low-vision users and c) Evaluates the heading structure to align with WCAG standards, ensuring that headers (h1, h2, etc.) are appropriately structured for optimal accessibility.

Finally, provide us with any [feedback](https://github.com/berkeley-dsep-infra/datahub/issues/new) that will help us improve our hub operations. We want to ensure that you have a smooth experience teaching this semester.
Finally, provide us with any feedback that will help us improve our hub operations. We want to ensure that you have a smooth experience teaching this semester.

**How can I learn more about Datahub to onboard myself?**

Expand Down
81 changes: 50 additions & 31 deletions technology/quarto.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Use Quarto to produce scientific and technical documentation
# Using Quarto in DataHub

Quarto 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.

Expand All @@ -8,35 +8,70 @@ Quarto is an open-source publishing system that is particularly valuable for ins
:name: Convert R markdown assignments/labs with quarto to produce pdfs
```

### Example Usecases
```{note}
For more information about Quarto, Read [here](https://quarto.org/)
```

### Opportunities to Integrate Quarto in Your Workflow

##### 1. Creating 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.

**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
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.

**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
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.

**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
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.

**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
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.

**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

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.

**RSudio:** In RStudio, you can create, edit, and render Quarto documents (.qmd files) directly.

```{note}
Read more about it [here](https://quarto.org/docs/get-started/hello/rstudio.html)
```

### General Workflow for Beginner Instructors
**Jupyter:** In JupyterLab, you cannot create/edit Quarto documents but can convert Jupyter notebooks to various formats using Quarto's command-line tools.

```{note}
Read more about it [here](https://quarto.org/docs/get-started/hello/jupyter.html)
```

**VSCode:** Check whether VSCode and [VSCode Quarto extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) is enabled in your hub. If yes, you can render and preview quarto documents and can have syntax highlighting in addition to command line tools to convert to varied documents.

```{note}
Read more about it [here](https://quarto.org/docs/get-started/hello/vscode.html)
```

### 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.

### Quarto Command-Line Conversion
### Steps to Convert Documents to HTML/PDF via Quarto

##### Convert Jupyter notebook and Quarto Markdown file to HTML

Expand All @@ -51,7 +86,6 @@ 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

**Option 1:**
Expand Down Expand Up @@ -79,19 +113,4 @@ Typst is a modern typesetting system designed to provide a user-friendly alterna
quarto render my-document.qmd --to pdf
```

The above command converts your Quarto Markdown (. qmd) into a PDF.


For more information about Quarto, Read [here](https://quarto.org/)

```{note}
Quarto can be used in integration with Jupyter Lab. Read more about it [here](https://quarto.org/docs/tools/jupyter-lab.html)
```

### Quarto integration with IDE

Quarto integrates seamlessly with several 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 how it integrates with IDEs.

**RSudio:** In RStudio, you can create, edit, and render Quarto documents (.qmd files) directly, leveraging its rich IDE features.
**Jupyter:** In JupyterLab, you can convert Jupyter notebooks to various formats using Quarto's command-line tools, enhancing interactive notebook workflows.
**VSCode:** Check whether VSCode and [VSCode Quarto extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) is enabled in the hub. If yes, you can render and preview quarto documents. You can have syntax highlighting and command line tools to convert to varied documents.
The above command converts your Quarto Markdown (. qmd) into a PDF.

0 comments on commit b36c1f7

Please sign in to comment.