Skip to content

Change to Jupyter Book #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pancakereport merged 3 commits into from
Jan 15, 2026
Merged

Change to Jupyter Book #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
47454c5
init changes for jb
pancakereport Jan 9, 2026
f99b0a5
small changes for rendering
pancakereport Jan 10, 2026
bb9ea7d
a11y badge
pancakereport Jan 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 35 additions & 38 deletions .github/workflows/a11y.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,66 +2,63 @@ name: Accessibility Checks

on:
push:
branches:
- main
pull_request:
workflow_dispatch:

env:
PRODUCTION_URL: "https://ds100.org/debugging-guide/"
SITE_SUBDIR: "debugging-guide"

jobs:
axe-audit:
axe-check:
runs-on: ubuntu-latest

steps:
- name: Checkout repository
- name: Checkout code
uses: actions/checkout@v4

# Setup Node.js and install Axe and http-server
- name: Set up Node.js
# 1. Setup Python & Build the Book
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
cache: 'pip'

- name: Install Python dependencies
run: pip install -r requirements.txt

- name: Build Jupyter Book
run: jupyter-book build --html

# 2. Setup Node environment for Axe
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Axe and Server

- name: Install Axe CLI and HTTP Server
run: npm install -g @axe-core/cli http-server

# Start Local Server
- name: Start Local Server
run: |
# Mimic the production path structure exactly with
# the local server
mkdir -p public/${{ env.SITE_SUBDIR }}
cp -r docs/* public/${{ env.SITE_SUBDIR }}/

# Serve the 'public' folder on port 3000
npx http-server ./public -p 3000 > /dev/null 2>&1 &

sleep 5
- name: Get Matching Chrome version
run: npx browser-driver-manager install chrome

# Run Axe Scan
- name: Run Accessibility Scan
id: axe-scan
# 3. Serve, Discover URLs, and Run Axe
- name: Run Axe Checks
run: |
# Swap the Production URL for Localhost + Subdirectory
LOCAL_URL="http://localhost:3000/${{ env.SITE_SUBDIR }}/"
# A. Start a local server in the background
npx http-server ./_build/html -p 8080 -s &
sleep 5

URLS=$(cat docs/sitemap.xml | \
sed -n 's/.*<loc>\(.*\)<\/loc>.*/\1/p' | \
sed "s|${{ env.PRODUCTION_URL }}|$LOCAL_URL|" | \
tr '\n' ' ')

echo "Scanning the following pages:"
echo "$URLS"

# Run Axe
# B. Generate the URL list from the actual build artifacts
cd _build/html
URLS=$(find . -name "*.html" -not -path "*/build/*" | sed 's|^\./||' | sed 's|^|http://localhost:8080/|' | tr '\n' ' ')

# C. Run Axe CLI on the discovered URLs
axe $URLS \
--tags wcag2a,wcag2aa,wcag21a,wcag21aa \
--save axe-report.json \
--exit

# Upload Report even if previous step fails
- name: Upload Accessibility Report
if: always()
uses: actions/upload-artifact@v4
with:
name: axe-report
path: axe-report.json
path: _build/html/axe-report.json
48 changes: 48 additions & 0 deletions .github/workflows/deploy.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# This file was created automatically with `jupyter-book init --gh-pages` 🪄 💚
# Ensure your GitHub Pages settings for this repository are set to deploy with **GitHub Actions**.

name: Jupyter Book (via myst) GitHub Pages Deploy
on:
push:
# Runs on pushes targeting the default branch
branches: [main]
env:
# `BASE_URL` determines, relative to the root of the domain, the URL that your site is served from.
# E.g., if your site lives at `https://mydomain.org/myproject`, set `BASE_URL=/myproject`.
# If, instead, your site lives at the root of the domain, at `https://mydomain.org`, set `BASE_URL=''`.
BASE_URL: /${{ github.event.repository.name }}

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: 'pages'
cancel-in-progress: false
jobs:
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Pages
uses: actions/configure-pages@v3
- uses: actions/setup-node@v4
with:
node-version: 18.x
- name: Install Jupyter Book (via myst)
run: npm install -g jupyter-book
- name: Build HTML Assets
run: jupyter-book build --html
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: './_build/html'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
9 changes: 7 additions & 2 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
/.quarto/

# Notebook Checkpoints
.ipynb_checkpoints/
**/.ipynb_checkpoints/

# macOS files
.DS_Store
**/.DS_Store
__MACOSX/

# Site build
Expand All @@ -16,3 +16,8 @@ _site/*
__pycache__/

**/*.quarto_ipynb

# MyST build outputs
_build

venv/
169 changes: 64 additions & 105 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,132 +1,91 @@
# Debugging Guide

[![pages-build-deployment](https://github.com/DS-100/debugging-guide/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/DS-100/debugging-guide/actions/workflows/pages/pages-build-deployment) [![Accessibility Checks](https://github.com/DS-100/debugging-guide/actions/workflows/a11y.yml/badge.svg)](https://github.com/DS-100/debugging-guide/actions/workflows/a11y.yml)
[![Accessibility Checks](https://github.com/DS-100/debugging-guide/actions/workflows/a11y.yml/badge.svg)](https://github.com/DS-100/debugging-guide/actions/workflows/a11y.yml)

Website link: https://ds100.org/debugging-guide/
This was built with [Jupyter Book (MyST flavor)](https://jupyterbook.org/en/stable/intro.html).

## Accessibility Checks
## Structure

Accessibility checks run whenever you push changes to the repository. View results in the Actions tab. You can also download reports generated by individual action runs.
Only two things need to be edited.
- `myst.yml`: Configuration information about the textbook. Modify this file for things like:
- changing the logo or favicon;
- adding or removing launch buttons;
- changing information about the book.
- table of contents (section, chapter numbering and order)
- `content/`: Content of the textbook. All the notebooks with section and chapter content go here. Modify these files to change the content of the sections.

If you'd like to run checks locally, first ensure you have quarto and Node.js installed. Then run `quarto preview --render all` which will preview the site at http://localhost:xxxx and generate `docs/sitemap.xml`. If the sitemap already exists, you can skip the `--render all` flag. Note the port number. From a second terminal, run the following with the correct port number:
```
axe $(cat docs/sitemap.xml | grep -o "<loc>[^<]*" | sed 's/<loc>//' | sed 's|https://ds100.org/debugging-guide|http://localhost:xxxx|') \
--tags wcag2a,wcag2aa,wcag21a,wcag21aa \
--exit
```

## Repo Setup

### Quarto Set-Up
## Maintaining the Textbook
This section details how to maintain the textbook.

Begin by [installing Quarto](https://quarto.org/docs/get-started/).
### One-time Setup
Follow these steps the first time you set up a computer to modify and maintain the textbook.
1. Create a local copy of this repo by running `git clone https://github.com/DS-100/debugging-guide.git` from the command line in whichever folder you want to contain the textbook.
2. Next, you need to install all the required packages. Either of the commands `pip install -r requirements.txt` or `conda install --file requirements.txt` should work. If you have a Windows device, it's preferable to run this in an Anaconda Prompt terminal. This should install the packages used to build the textbook and execute the notebooks. If you use pip to install the packages, I recommend using a python virtual environment:

Texts can be authored in Quarto using VSCode, JupyterLab, or classic Jupyter Notebook. We suggest using [VSCode](https://quarto.org/docs/get-started/hello/vscode.html)

### Cloning the Repo
After you've installed quarto, go into your terminal on your *local* device and type
```bash
python3 -m venv venv # create virtual environment
source venv/bin/activate # activate the virtual environment
pip install -r requirements.txt # as above
```
If you use a virutal environment, make sure to activate it before updating the textbook by first running `source venv/bin/activate` at the top level of this repo. You can deactivate the environment with `deactivate`. If you choose to use a virtual environment not named venv, ensure that you add this to the `.gitignore` so it is NOT tracked by git.

`git clone https://github.com/DS-100/debugging-guide.git`
### Updating the Textbook
These steps detail the process you should go through every time you update the textbook. Remember to activate your virtual environment first if you are using one.
1. **Pull:** `cd` into `debugging-guide/`, your local copy of the repository and `git pull origin main` to collect any updates which may have been pushed to the remote copy by other collaborators.
2. **Update:** Make any changes you wish to make. This should (likely) only consist of changes to `_myst.yml` and the files in `content/`.
- If you added new sections or chapters, update the `toc` in `myst.yml` to ensure your changes are included.
3. **Build and Check:** `cd` into the top level directory of this repository and run `jupyter book start` to build the book and serve it on localhost. View what the textbook looks like with any changes you've made. Make sure nothing is broken and the changes are as you want them.
6. **Push:** Stage any changes you made (i.e. using `git add [file]`, `git add -u`, `git add .`, etc.), commit your changes with `git commit -m "[description]"` (please include a useful description of any changes you made), and push to the repository with `git push origin main`. Deployment will happen automatically via GitHub Actions.

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.
### Deployment
The textbook is hosted on GitHub Pages and deployed automatically everytime you push to the main branch via [this workflow](https://github.com/DS-100/debugging-guide/actions/workflows/deploy.yml).

### 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](https://github.com/DS-100/course-notes). We recommend using Conda ([download here](https://www.anaconda.com/download)) to keep track of your environment.
## Helpful Things
The [Jupyter Book](https://jupyterbook.org/stable/) website has lots of information about Jupyter Book. This textbook uses Jupyter Book v2 built on [MyST](https://mystmd.org/).

Run the following in your terminal within the main directory:
If changes you've made aren't showing up the HTML after building, sometimes deleting `_build` and then building again helps. You can also run `jupyter book clean`.

```
conda create --name data100quarto
conda activate data100quarto
pip3 install -r requirements.txt # will take a while
ipython kernel install --user
```
Some cells are hidden with tags like `remove-input` or `remove-cell`.

If you get an `error: externally-managed-environment` on the third line, run `pip3 install -r requirements.txt --break-system-packages`. You may also run into issues if you're running on Apple silicon. I fixed this by running `conda install -c conda-forge scikit-learn==1.2.2 scikit-image==0.25.2` before `pip3 install -r requirements.txt`.
### Images

Remember to always activate the right environment before running anything with `conda activate data100quarto`.
All images must have alt text. [More on images and figures in MyST.](https://mystmd.org/guide/figures)

### Links
Links to the internet should be done as they are usually done in Markdown. However, to cross-link to other pages of the textbook, there is an internal linking system that should be used instead (since it is robust to file structure changes). This system is described [here](https://mystmd.org/guide/cross-references#targeting-headers).

## Repo Organization
This website uses Quarto to render pages. The main index can be found in `_quarto.yml`, and subpages are organized under the `contents` section. Each subpage has it's own folder and `.md` (markdown) file. Note that unlike the [Course Notes repo](https://github.com/DS-100/course-notes), 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:

For example, Section 12.4 Exercise 3 of the [Stat 88 Textbook](https://github.com/stat88/textbook) contains a link to Section 12.2.
1. The flag `(ch12.2)=` was added *before* the primary header of the notebook.
```
---
title: INSERT_TOPIC_TITLE
format:
html:
toc-location: right
code-fold: 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
---
(ch12.2)=
## The Distribution of the Estimated Slope ##
```

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.

![](assets/images/readme/md_preview.png)

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

#### 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" alt="ALT TEXT HERE"></img></a></center>```

For example, `<center><img src = "images/updated_basic.png" width = "700" alt="description of image"></img></a></center>`.

In some instances, the images may be completely described in the text of the page. In these cases, you may leave the alt text blank i.e. `alt=""`, **but alt text must still be included to meet our legal obligations.**

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

Not all files in this repository need to be rendered. For example, images used in this README are not used in the website and as such do not need to be included in the rendered website. To ensure these files are not rendered, they are placed in the folder `assets/images/_readme/` which is not rendered because the folder begins with an underscore `_`. Read more about this [here](https://quarto.org/docs/websites/index.html#render-targets).

## Pushing to Github
Once you're satisfied and have *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.

2. The link referencing Section 12.2 is created like so:
```
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
**3.**
Refer to the regression of active pulse rate on resting pulse rate in [Section 12.2](ch12.2). Here are the estimated values again, along with some additional data.
```

2. **Github Desktop** ([download](https://desktop.github.com/)). 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. ![](assets/images/readme/git_files.png)
* Write an informative comment on the bottom left hand corner and click "commit to main" once finished ![](assets/images/readme/git_comment.png)
* Push your changes using the button on the top right.
### Hidden Cells

Once your changes are pushed, you can see the progress of your build in the ["Actions" tab](https://github.com/DS-100/debugging-guide/actions). The Actions tab monitors all workflows. Currently there are two workflows: "pages-build-deployment" which builds and deploys the website, and "Accessibility Checks." If both checks complete successfully, you will see a green checkmark next to each workflow's most recent run on the Actions page as well as a green checkmark on the main repo page for the associated commit. Yellow/orange indicates that checks are still running, meaning that the website may not be deployed yet. Red means that at least one check was unable to complete successfully. You should always investigate if you see a red mark; It's possible that the website deployed successfully but the accessibility checks failed, or vice versa.
[Use tags to hide cells and/or their output](https://mystmd.org/guide/interactive-notebooks#notebooks-cell-visibility)

The website should take less than 5 minutes to deploy, and you will see the changes reflected in the [website](https://ds100.org/debugging-guide/).
I wasn't able to figure out a quick dropdown to hide the cell before it is clicked, so this is what I ended up with. In a markdown cell, I first put the code that I want to hide in a dropdown [directive](https://mystmd.org/guide/directives):

````{dropdown} Click to see the code
:open: false
```python
import pandas as pd
import numpy as np
import urllib.request
import os.path
import zipfile
```
````

## Other Quarto Resources

[Quick Start Guide](https://quarto.org/docs/get-started/)

[Comprehensive Guide](https://quarto.org/docs/guide/)
Then I put the code I want to execute (and see its output on the website) in a code cell with the `remove-input` tag added. You can add tags via VSCode or like so:

[Markdown in Quarto](https://quarto.org/docs/authoring/markdown-basics.html)
```{code-cell} python
:tags: [remove-input]
print("This will show output with no input!")
```
Loading
Loading