diff --git a/README.md b/README.md index 498f91e..608e84b 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,69 @@ # Debugging Guide -# Guide to Quarto Installation & Use +Website link: https://ds100.org/debugging-guide/ + ## Quarto Set-Up Begin by [installing Quarto](https://quarto.org/docs/get-started/). -Texts can be authored in Quarto using JupyterLab or classic Jupyter Notebook. To start a new document, open Jupyter and create a new notebook file. +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) + +## 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](https://github.com/DS-100/course-notes), the debugging guide rarely runs any code, so we rely on `.md` files rather than `.qmd`, saving 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 set up the document, create a new Raw NBConvert cell. This will be used to set document-level YAML options. The Data 100 lecture notes are generated using the following YAML settings: +## 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: "Name of the Lecture" -execute: - echo: true +title: INSERT_TOPIC_TITLE format: html: - code-fold: true - code-tools: true toc: true - toc-title: Name of the Lecture - page-layout: full - theme: [cosmo, cerulean] + toc-depth: 5 + toc-location: right + code-fold: false + theme: + - cosmo + - cerulean callout-icon: false -jupyter: python3 +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. Quarto supports all the functionality of a standard ipynb file – code cells, markdown, and LaTeX. To begin writing lecture notes, it's a good idea to first set out the main headings of the document. These typically correspond to the title slides of each lecture ([example](https://docs.google.com/presentation/d/1FZJhOS8S1lCqZCRxbyys9rCZT0QxdY4hcmvZDskEHFI/edit#slide=id.g1150ea2fb2b_0_220)) and are written with the Markdown second headng level (`##`). Quarto will auto-populate the table of contents as these headings are created. +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. -To view the Quarto file, open a terminal window (either [within Jupyter](https://docs.google.com/presentation/d/1FZJhOS8S1lCqZCRxbyys9rCZT0QxdY4hcmvZDskEHFI/edit#slide=id.g1150ea2fb2b_0_220) or through your machine's terminal) and navigate to the notebook's directory. Running the command `quarto preview notebook.ipynb` will render the document and open it in a new web browser tab. +![](md_preview.png) -With the preview activated, the rendered view will update every time a change is saved in the notebook. When editing the document, it's helpful to have side-by-side views of the notebook and preview so you can watch changes in real-time. +Note that clicking on the quarto `Preview` button does not generate a *live* preview but rather a static one. ## Document Formatting A pdf view of how this notebook renders in Quarto can be found [here](https://drive.google.com/file/d/17ga5wvfcmvAzQ1rbnCP4kEf5bckST3--/view?usp=sharing). -#### Formatting Code - -The `code-fold: true` option in the YAML set-up will automatically collapse all code cells in the rendered document. If a particular code cell should be uncollapsed by default (e.g. to explicitly show a `pandas` example), a cell-specific YAML option can be specified: - -``` -#| code-fold: false -print("this code is now visible") -``` - #### Formatting Images -Inserting images in a Quarto document is similar to the standard Markdown syntax. The difference is that Quarto will insert figure captions automatically. The syntax below will insert an image with an accompanying description. - -``` -#![The best class at Berkeley](data.png) -``` - -#### Formatting Learning Outcomes - -Each lecture note should start with a brief list of intended student learning outcomes. These are formatted as collapsable call-out cells, which can be created in a Markdown cell using the syntax below. - -``` -::: {.callout-note collapse="true"} -## Learning Outcomes -* Gain familiarity with Quarto -* Create your first Quarto document -* Write A+ Data 100 lecture notes -::: -``` +To give you the most control when inserting images, we use html with the following format to center images/figs and control their size: -## Generating Output -To generate the final notebook as an HTML, run the terminal command `quarto render notebook.ipynb`. The HTML will be outputted in the same directory as the notebook. +```
``` -# Data 100-specific items +## 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, run `quarto render` to render the entire website. Push your changes to Github, and you should see the changes reflected in the [website](https://ds100.org/debugging-guide/) after a few minutes. -General commands/notes: - * `jupyter lab # local jupyter setup` - * `ipynb` -> `qmd`: `quarto convert notebook.ipynb` or `quarto convert notebook.qmd` - * `quarto render`: renders HTML to `docs`. Note `qmd` has to exist for rendering - * Edit `_quarto.yml` to include note in sidebar/table of contents -* Quick local development: - * TODO: how to quickly render just one notes directory and not all notes? * Publish notes to GitHub pages: * `quarto render` everything * `git add`, `git commit`, `git push` * Can view website compilation on GitHub (look for yellow-to-green button next to commit number) -* Common errors: - * `Illegal instruction: 4 ...` close jupyter lab ## Other Quarto Resources diff --git a/_quarto.yml b/_quarto.yml index dc25483..78f651d 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -27,7 +27,7 @@ format: theme: cosmo toc: true toc-depth: 5 - toc-expand: 3 + toc-expand: 3 # depth to expand index callout-icon: false number-sections: false pdf: default diff --git a/autograder_gradescope/autograder_gradescope.md b/autograder_gradescope/autograder_gradescope.md index 3b75111..a5624d4 100644 --- a/autograder_gradescope/autograder_gradescope.md +++ b/autograder_gradescope/autograder_gradescope.md @@ -56,11 +56,6 @@ This can happen if you “overwrite” a variable that is used in a question. Fo ### Why does a notebook test fail now when it passed before, and I didn’t change my code? You probably ran your notebook out of order. [Re-run all previous cells](https://ds100.org/debugging-guide/jupyter101/jupyter101.html#running-cells) in order, which is how your code will be graded. -### I accidentally deleted something in a cell that was provided to me – how do I get it back? -Suppose you’re working on Lab 5. One solution is to go directly to DataHub and rename your lab05 folder to something else, like lab05-old. Then, click the Lab 5 link on the course website again, and it’ll bring you to a brand-new version of Lab 5. You can then copy your work from your old Lab 5 to this new one, which should have the original version of the assignment. - -Alternatively, you can access this [public repo](https://github.com/DS-100/sp24-student) and navigate to a blank copy of the assignment you were working on. In the case of Lab 5 for example, the notebook would be located at `lab/lab05/lab05.ipynb`. You can then check and copy over the contents of the deleted cell into a new cell in your existing notebook. - ## Gradescope When submitting to Gradescope, there are often unexpected errors that make students lose more points than expected. Thus, it is imperative that you **stay on the submission page until the autograder finishes running**, and the results are displayed. diff --git a/docs/Data-100-Debugging-Guide.pdf b/docs/Data-100-Debugging-Guide.pdf index 1d61732..c8e82df 100644 Binary files a/docs/Data-100-Debugging-Guide.pdf and b/docs/Data-100-Debugging-Guide.pdf differ diff --git a/docs/autograder_gradescope/autograder_gradescope.html b/docs/autograder_gradescope/autograder_gradescope.html index 0b0dc9e..eb19d74 100644 --- a/docs/autograder_gradescope/autograder_gradescope.html +++ b/docs/autograder_gradescope/autograder_gradescope.html @@ -149,7 +149,6 @@

Table of contents

  • I’m positive I have the right answer, but the test fails. Is there a mistake in the test?
  • Why does grader.export(run_tests=True) fail if all previous tests passed?
  • Why does a notebook test fail now when it passed before, and I didn’t change my code?
    • -
  • I accidentally deleted something in a cell that was provided to me – how do I get it back?
  • Gradescope @@ -218,6 +221,11 @@

    Why does running a particular cell cause my kernel to die?

    If one particular cell seems to cause your kernel to die, this is likely because the computer is trying to use more memory than it has available. For instance: your code is trying to create a gigantic array. To prevent the entire server from crashing, the kernel will “die”. This is an indication that there is a mistake in your code that you need to fix.

    +
    +

    I accidentally deleted something in a cell that was provided to me – how do I get it back?

    +

    Suppose you’re working on Lab 5. One solution is to go directly to DataHub and rename your lab05 folder to something else, like lab05-old. Then, click the Lab 5 link on the course website again, and it’ll bring you to a brand-new version of Lab 5. You can then copy your work from your old Lab 5 to this new one, which should have the original version of the assignment.

    +

    Alternatively, you can access this public repo and navigate to a blank copy of the assignment you were working on. In the case of Lab 5 for example, the notebook would be located at lab/lab05/lab05.ipynb. You can then check and copy over the contents of the deleted cell into a new cell in your existing notebook.

    +

    “Click here to download zip file” is not working

    diff --git a/docs/search.json b/docs/search.json index 85ee594..b763a06 100644 --- a/docs/search.json +++ b/docs/search.json @@ -4,7 +4,7 @@ "href": "index.html", "title": "Data 100 Debugging Guide", "section": "", - "text": "About\nThis text offers pointers for keyboard shortcuts or common mistakes that accompany the coursework in the Spring 2024 Edition of the UC Berkeley course Data 100: Principles and Techniques of Data Science.\nInspiration for this guide was taken from the UC San Diego course DSC 10: Principles of Data Science and their debugging guide.\nIf you spot any typos or would like to suggest any changes, please email us at data100.instructors@berkeley.edu" + "text": "About\nThis text offers pointers for keyboard shortcuts or common mistakes that accompany the coursework in the Spring 2024 Edition of the UC Berkeley course Data 100: Principles and Techniques of Data Science.\nInspiration for this guide was taken from the UC San Diego course DSC 10: Principles of Data Science and their debugging guide.\nIf you spot any typos or would like to suggest any changes, please fill out the Data 100 Content Feedback Form (Spring 2024). Note that this link will only work if you have an @berkeley.edu email address. If you’re not a student at Berkeley and would like to provide feedback, please email us at data100.instructors@berkeley.edu" }, { "objectID": "jupyter101/jupyter101.html#shortcuts-for-cells", @@ -67,7 +67,7 @@ "href": "jupyter_datahub/jupyter_datahub.html#why-does-running-a-particular-cell-cause-my-kernel-to-die", "title": "Jupyter / Datahub", "section": "Why does running a particular cell cause my kernel to die?", - "text": "Why does running a particular cell cause my kernel to die?\nIf one particular cell seems to cause your kernel to die, this is likely because the computer is trying to use more memory than it has available. For instance: your code is trying to create a gigantic array. To prevent the entire server from crashing, the kernel will “die”. This is an indication that there is a mistake in your code that you need to fix." + "text": "Why does running a particular cell cause my kernel to die?\nIf one particular cell seems to cause your kernel to die, this is likely because the computer is trying to use more memory than it has available. For instance: your code is trying to create a gigantic array. To prevent the entire server from crashing, the kernel will “die”. This is an indication that there is a mistake in your code that you need to fix.\n\nI accidentally deleted something in a cell that was provided to me – how do I get it back?\nSuppose you’re working on Lab 5. One solution is to go directly to DataHub and rename your lab05 folder to something else, like lab05-old. Then, click the Lab 5 link on the course website again, and it’ll bring you to a brand-new version of Lab 5. You can then copy your work from your old Lab 5 to this new one, which should have the original version of the assignment.\nAlternatively, you can access this public repo and navigate to a blank copy of the assignment you were working on. In the case of Lab 5 for example, the notebook would be located at lab/lab05/lab05.ipynb. You can then check and copy over the contents of the deleted cell into a new cell in your existing notebook." }, { "objectID": "jupyter_datahub/jupyter_datahub.html#click-here-to-download-zip-file-is-not-working", @@ -88,7 +88,7 @@ "href": "autograder_gradescope/autograder_gradescope.html#autograder", "title": "Autograder and Gradescope", "section": "Autograder", - "text": "Autograder\n\nUnderstanding autograder error messages\nWhen you pass a test, you’ll see a nice, concise message and a cute emoji!\n\n\n\nWhen you don’t, however, the message can be a little confusing.\n\n\n\n\nThe best course of action is to find the test case that failed and use that as a starting point to debug your code.\n\n\n\n\n\nWhy do I get an error saying “grader is not defined”?\nIf it has been a while since you’ve worked on an assignment, the kernel will shut itself down to preserve memory. When this happens, all of your variables are forgotten, including the grader. That’s OK. The easiest way to fix this is by restarting your kernel and rerunning all the cells. To do this, in the top left menu, click Kernel -> Restart and Run All Cells.\n\n\nI’m positive I have the right answer, but the test fails. Is there a mistake in the test?\nWhile you might see the correct answer displayed as the result of the cell, chances are your solution isn’t being stored in the answer variable. Make sure you are assigning the result to the answer variable and that there are no typos in the variable name. Finally, restart your kernel and run all the cells in order: Kernel -> Restart and Run All Cells.\n\n\nWhy does grader.export(run_tests=True) fail if all previous tests passed?\nThis can happen if you “overwrite” a variable that is used in a question. For instance, say Question 1 asks you to store your answer in a variable named stat and, later on in the notebook, you change the value of stat; the test right after Question 1 will pass, but the test at the end of the notebook will fail. It is good programming practice to give your variables informative names and to avoid repeating the same variable name for more than one purpose.\n\n\nWhy does a notebook test fail now when it passed before, and I didn’t change my code?\nYou probably ran your notebook out of order. Re-run all previous cells in order, which is how your code will be graded.\n\n\nI accidentally deleted something in a cell that was provided to me – how do I get it back?\nSuppose you’re working on Lab 5. One solution is to go directly to DataHub and rename your lab05 folder to something else, like lab05-old. Then, click the Lab 5 link on the course website again, and it’ll bring you to a brand-new version of Lab 5. You can then copy your work from your old Lab 5 to this new one, which should have the original version of the assignment.\nAlternatively, you can access this public repo and navigate to a blank copy of the assignment you were working on. In the case of Lab 5 for example, the notebook would be located at lab/lab05/lab05.ipynb. You can then check and copy over the contents of the deleted cell into a new cell in your existing notebook." + "text": "Autograder\n\nUnderstanding autograder error messages\nWhen you pass a test, you’ll see a nice, concise message and a cute emoji!\n\n\n\nWhen you don’t, however, the message can be a little confusing.\n\n\n\n\nThe best course of action is to find the test case that failed and use that as a starting point to debug your code.\n\n\n\n\n\nWhy do I get an error saying “grader is not defined”?\nIf it has been a while since you’ve worked on an assignment, the kernel will shut itself down to preserve memory. When this happens, all of your variables are forgotten, including the grader. That’s OK. The easiest way to fix this is by restarting your kernel and rerunning all the cells. To do this, in the top left menu, click Kernel -> Restart and Run All Cells.\n\n\nI’m positive I have the right answer, but the test fails. Is there a mistake in the test?\nWhile you might see the correct answer displayed as the result of the cell, chances are your solution isn’t being stored in the answer variable. Make sure you are assigning the result to the answer variable and that there are no typos in the variable name. Finally, restart your kernel and run all the cells in order: Kernel -> Restart and Run All Cells.\n\n\nWhy does grader.export(run_tests=True) fail if all previous tests passed?\nThis can happen if you “overwrite” a variable that is used in a question. For instance, say Question 1 asks you to store your answer in a variable named stat and, later on in the notebook, you change the value of stat; the test right after Question 1 will pass, but the test at the end of the notebook will fail. It is good programming practice to give your variables informative names and to avoid repeating the same variable name for more than one purpose.\n\n\nWhy does a notebook test fail now when it passed before, and I didn’t change my code?\nYou probably ran your notebook out of order. Re-run all previous cells in order, which is how your code will be graded." }, { "objectID": "autograder_gradescope/autograder_gradescope.html#gradescope", diff --git a/index.md b/index.md index d5c5cf6..4871c2b 100644 --- a/index.md +++ b/index.md @@ -8,4 +8,4 @@ This text offers pointers for keyboard shortcuts or common mistakes that accompa Inspiration for this guide was taken from the UC San Diego course DSC 10: Principles of Data Science and their [debugging guide](https://dsc10.com/debugging/). -If you spot any typos or would like to suggest any changes, please email us at **data100.instructors@berkeley.edu** +If you spot any typos or would like to suggest any changes, please fill out the [Data 100 Content Feedback Form (Spring 2024)](https://docs.google.com/forms/d/e/1FAIpQLSe0fBEJwt6aEfZxU3fh3llNk8rSWHj6Umq0km3wPqmFu0MlGA/viewform?usp=sf_link). Note that this link will only work if you have an @berkeley.edu email address. If you're not a student at Berkeley and would like to provide feedback, please email us at **data100.instructors@berkeley.edu** diff --git a/jupyter_datahub/jupyter_datahub.md b/jupyter_datahub/jupyter_datahub.md index d0bc8e4..72f127e 100644 --- a/jupyter_datahub/jupyter_datahub.md +++ b/jupyter_datahub/jupyter_datahub.md @@ -62,6 +62,11 @@ Sometimes, a text (markdown) cell was changed to a code cell, or a code cell can ## Why does running a particular cell cause my kernel to die? If one particular cell seems to cause your kernel to die, this is likely because the computer is trying to use more memory than it has available. For instance: your code is trying to create a gigantic array. To prevent the entire server from crashing, the kernel will “die”. This is an indication that there is a mistake in your code that you need to fix. +### I accidentally deleted something in a cell that was provided to me – how do I get it back? +Suppose you’re working on Lab 5. One solution is to go directly to DataHub and rename your lab05 folder to something else, like lab05-old. Then, click the Lab 5 link on the course website again, and it’ll bring you to a brand-new version of Lab 5. You can then copy your work from your old Lab 5 to this new one, which should have the original version of the assignment. + +Alternatively, you can access this [public repo](https://github.com/DS-100/sp24-student) and navigate to a blank copy of the assignment you were working on. In the case of Lab 5 for example, the notebook would be located at `lab/lab05/lab05.ipynb`. You can then check and copy over the contents of the deleted cell into a new cell in your existing notebook. + ## "Click here to download zip file" is not working When this happens, you can download the zip file through the menu on the left. diff --git a/md_preview.png b/md_preview.png new file mode 100644 index 0000000..84c7db4 Binary files /dev/null and b/md_preview.png differ