Debugging Guide

Website link: https://ds100.org/debugging-guide/

Repo Setup

Quarto Set-Up

Begin by installing Quarto.

Texts can be authored in Quarto using VSCode, JupyterLab, or classic Jupyter Notebook. We suggest using VSCode

Cloning the Repo

After you've installed quarto, go into your terminal on your local device and type

git clone https://github.com/DS-100/debugging-guide.git

If you're unable to clone the repo, please contact the head/infra TAs to make sure you have read/write access to this repository.

Environment Setup

This section will ensure that you have all the necessary packages to render the website and is identical to the corresponding section in the course-notes repo. We recommend using Conda (download here) to keep track of your environment.

Run the following in your terminal within the main directory:

conda create --name data100quarto 
conda activate data100quarto
pip3 install -r requirements.txt # will take a while
ipython kernel install --user

If you get an error: externally-managed-environment on the third line, run pip3 install -r requirements.txt --break-system-packages

Remember to always activate the right environment before running anything with conda activate data100quarto.

Repo Organization

This website uses Quarto to render pages. The main index can be found in _quarto.yml, and subpages are organized under the chapters section. Each subpage has it's own folder and .md (markdown) file. Note that unlike the Course Notes repo, the debugging guide rarely runs any code, so we rely on .md files rather than .qmd to save us the trouble of converting from .qmd to .ipynb for editing, then back to .qmd to render the website. Instead we can make edits directly to the .md file.

Creating a new section

To start a new document, create an empty folder topic_name and create an empty markdown file topic_name.md. Start each document like so:

---
title: INSERT_TOPIC_TITLE
format:
  html:
    toc: true
    toc-depth: 5
    toc-location: right
    code-fold: false
    theme:
      - cosmo
      - cerulean
    callout-icon: false
jupyter:
  jupytext:
    text_representation:
      extension: .qmd
      format_name: quarto
      format_version: '1.0'
      jupytext_version: 1.16.1
  kernelspec:
    display_name: Python 3 (ipykernel)
    language: python
    name: python3
---

Now, the notebook is ready for writing content. In VSCode, you can activate a live preview of markdown files by clicking the button on the upper right-hand corner.

Note that clicking on the quarto Preview button does not generate a live preview but rather a static one. Hence, we click the button on its right.

Document Formatting

Always git pull before making any new changes.

A pdf view of how this notebook renders in Quarto can be found here.

Formatting Images

To give you the most control when inserting images, we use html with the following format to center images/figs and control their size:

<center><img src = "IMAGE_NAME" width = "IMAGE_WIDTH_IN_PIXELS"></img></a></center>

For example, <center><img src = "images/updated_basic.png" width = "700"></img></a></center>.

Generating Output + Rendering Website

After making edits to the .md files, ensure that the right documents are un-commented under _quarto.yml's chapter section. Then, make sure you're using the right environment, and run quarto render in the main folder to render the entire website.

To preview your changes, run quarto preview.

Pushing to Github

Once you're satisfied and thoroughly tested your changes, you can push your edits onto Github. There are two ways to do this:

1. Command Line. Navigate to the main debugging-guide folder if you haven't already and make sure you're in the right environment.

git add . # this makes sure git tracks any new files created
git commit -m <your message here> # please commit with an informative message
git push # push your changes to github

2. Github Desktop (download). This is the GUI version of the command line.

• Choose the files you want to commit on the left hand menu. By default, github will select all changes/new files.
• Write an informative comment on the bottom left hand corner and click "commit to main" once finished
• Push your changes using the button on the top right.

Once your changes are pushed, you can see the progress of your build in the "Actions" tab; green means the website built successfully, yellow/orange indicates that it's still building, and red means there was an error and the website was unable to build. The website should take less than 5 minutes to build, and you will see the changes reflected in the website.

Other Quarto Resources

Quick Start Guide

Comprehensive Guide

Markdown in Quarto