Website link: https://ds100.org/debugging-guide/
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.
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
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. 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.
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 contents 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-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
---
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.
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.
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.
Once you're satisfied and have 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-guidefolder 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. 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.
The website should take less than 5 minutes to deploy, and you will see the changes reflected in the website.