Website link: https://ds100.org/debugging-guide/
Begin by installing Quarto.
Texts can be authored in Quarto using VSCode, JupyterLab, or classic Jupyter Notebook. We suggest using VSCode
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.
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
.
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.
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.
Always git pull
before making any new changes.
A pdf view of how this notebook renders in Quarto can be found here.
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>
.
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
.
Once you're satisfied and thoroughly tested your changes, you can push your edits onto Github. There are two ways to do this:
- 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
- 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.