Merge pull request #331 from UBC-DSCI/quotes

fixing figure captions in jupyter and version control

Author: trevorcampbell

README.md

@@ -117,6 +117,18 @@ bookdown::gitbook:
 - when saying that students will do things in code, always say "in R"
 - "you will be able to" (not "students will be able to", "the reader will be able to")
 
+#### Captions
+- If you have special characters (particularly underscores, quotation marks, plus signs, other LaTeX math symbols) make sure to separate
+  the caption out of the code chunk like so
+  ```
+  (ref:blah)
+  
+  \`\`\`
+  {r blah, other_options}
+  code here
+  \`\`\`
+  ```
+
 #### Equations
 - make sure all equations get capitalized labels ("Equation \\@ref(blah)", not "equation below" or "equation above")
 

jupyter.Rmd

@@ -260,7 +260,10 @@ image_read("img/out-of-order-2.png") |>
   image_crop("3632x800")
 ```
 
-```{r out-of-order-3, echo = FALSE, fig.cap = 'Code that was written out of order, and was executed in a linear order using "Restart Kernel and Run All Cells..." This resulted in an error at the execution of the second code cell and it failed to run all code cells in the notebook.', fig.retina = 2, out.width="100%"}
+
+(ref:out-of-order-3) Code that was written out of order, and was executed in a linear order using "Restart Kernel and Run All Cells..." This resulted in an error at the execution of the second code cell and it failed to run all code cells in the notebook.
+
+```{r out-of-order-3, echo = FALSE, fig.cap = '(ref:out-of-order-3)', fig.retina = 2, out.width="100%"}
 image_read("img/out-of-order-3.png") |> 
   image_crop("3632x800")
 ```

version-control.Rmd

@@ -267,7 +267,7 @@ If you are working on a project with collaborators, they will also be making cha
 (e.g., to the analysis code in a Jupyter notebook and the project's README file),
 committing them to their own local repository, and pushing their commits to the remote GitHub repository
 to share them with you. When they push their changes, those changes will only initially exist in 
-the remote GitHub repository and not in your local repository (Figure \@ref(fig:vc2-changes)).
+the remote GitHub repository and not in your local repository (Figure \@ref(fig:vc6-remote-changes)).
 
 ```{r vc6-remote-changes, fig.cap = 'Changes pushed by collaborators, or created directly on GitHub will not be automatically sent to your local repository.', fig.retina = 2, out.width="100%"}
 image_read("img/vc6-remote-changes.png") %>%
@@ -276,7 +276,7 @@ image_read("img/vc6-remote-changes.png") %>%
 
 To obtain the new changes from the remote repository on GitHub, you will need
 to **pull** \index{git!pull} those changes to your own local repository.  By pulling changes,
-you synchronize your local repository to what is present on GitHub.
+you synchronize your local repository to what is present on GitHub (Figure \@ref(fig:vc7-pull)).
 Additionally, until you pull changes from the remote repository, you will not
 be able to push any more changes yourself (though you will still be able to
 work and make commits in your own local repository). 
@@ -310,7 +310,9 @@ your project by clicking on the "+" icon in the upper right
 hand corner, and then on "New Repository," as shown in 
 Figure \@ref(fig:new-repository-01).
 
-```{r new-repository-01, fig.cap = 'New repositories on GitHub can be created by clicking on "New Repository" from the + menu.', fig.retina = 2, out.width="100%"}
+(ref:new-repository-01) New repositories on GitHub can be created by clicking on "New Repository" from the + menu. 
+
+```{r new-repository-01, fig.cap = '(ref:new-repository-01)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/new_repository_01.png") %>%
   image_flop() %>%
   image_crop("3632x1148") %>%
@@ -449,7 +451,9 @@ image_read("img/version_control/upload-files_01.png") %>%
   image_flop()
 ```
 
-```{r upload-files-02, fig.cap = 'Specify files to upload by dragging them into the GitHub website (red circle) or by clicking on "choose your files." Uploaded files are also required to be committed along with an associated commit message.', fig.retina = 2, out.width="100%"}
+(ref:upload-files-02) Specify files to upload by dragging them into the GitHub website (red circle) or by clicking on "choose your files." Uploaded files are also required to be committed along with an associated commit message.
+
+```{r upload-files-02, fig.cap = '(ref:upload-files-02)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/upload-files_02.png") %>%
   image_flop() %>%
   image_crop("3584x2200") %>%
@@ -485,7 +489,9 @@ copy that knows where it was obtained from so that it knows where send/receive
 new committed edits. In order to do this, first copy the URL from the HTTPS tab 
 of the Code drop down menu on GitHub (Figure \@ref(fig:clone-02)).
 
-```{r clone-02, fig.cap = 'The remote address (URL) corresponding to the location of the remote GitHub repository can be found in the green "Code" drop down menu.', fig.retina = 2, out.width="100%"}
+(ref:clone-02) The remote address (URL) corresponding to the location of the remote GitHub repository can be found in the green "Code" drop down menu.
+
+```{r clone-02, fig.cap = '(ref:clone-02)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/clone_02.png") %>%
   image_crop("3584x1500")
 ```
@@ -539,18 +545,22 @@ This is a temporary "checkpoint file" created by Jupyter when you work on `eda.i
 You generally do not want to add auto-generated files to Git repositories;
 only add the files you directly create and edit.
 
-```{r git-add-02, fig.cap = 'The plus sign (+) is used to add the `eda.ipynb` file to the staging area.', fig.retina = 2, out.width="100%"}
+(ref:git-add-02) The plus sign (+) is used to add the `eda.ipynb` file to the staging area.
+
+```{r git-add-02, fig.cap = '(ref:git-add-02)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/git_add_02.png")
 ```
 
 Clicking the plus sign (+) moves the file from the "Untracked" heading to the "Staged" heading, 
 flagging this file so that Git knows we want a snapshot of its current state 
-as a commit (Figure \@ref(fig:git-add-02)).
+as a commit (Figure \@ref(fig:git-add-03)).
 Now we are ready to "commit" the changes. 
 Make sure to include a (clear and helpful!) message about what was changed
 so that your collaborators (and future you) know what happened in this commit. 
 
-```{r git-add-03, fig.cap = 'Once added, the `eda.ipynb` file is visible in the staging area, labeled as "Staged" in the Jupyter Git extension tool.', fig.retina = 2, out.width="100%"}
+(ref:git-add-03) Once added, the `eda.ipynb` file is visible in the staging area, labeled as "Staged" in the Jupyter Git extension tool.
+
+```{r git-add-03, fig.cap = '(ref:git-add-03)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/git_add_03.png")
 ```
 
@@ -574,7 +584,7 @@ image_read("img/version_control/git_commit_01.png")
 
 After "committing" the file(s), you will see there are 0 "Staged" files 
 and we are now ready to push our changes
-to our remote repository on GitHub (Figure \@ref(fig:git-commit-01)).
+to our remote repository on GitHub (Figure \@ref(fig:git-commit-03)).
 
 ```{r git-commit-03, fig.cap = 'After recording a commit, the staging area should be empty.', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/git_commit_03.png")
@@ -586,7 +596,9 @@ To send the committed changes back to the remote repository on
 GitHub, we need to *push* them. \index{git!push} To do this we click on the cloud icon with the up arrow on the Jupyter Git tab 
 (Figure \@ref(fig:git-push-01)).
 
-```{r git-push-01, fig.cap = 'The Jupyter Git extension "push" button (circled in red).', fig.retina = 2, out.width="100%"}
+(ref:git-push-01) The Jupyter Git extension "push" button (circled in red).
+
+```{r git-push-01, fig.cap = '(ref:git-push-01)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/git_push_01.png")
 ```
 
@@ -624,22 +636,28 @@ person who created the GitHub \index{GitHub!collaborator access} repository has
 delete files (*write access*). To give your collaborators write access to the 
 projects, navigate to the "Settings" tab (Figure \@ref(fig:add-collab-01)).
 
-```{r add-collab-01, fig.cap = 'The "Settings" tab on the GitHub web interface.', fig.retina = 2, out.width="100%"}
+(ref:add-collab-01) The "Settings" tab on the GitHub web interface.
+
+```{r add-collab-01, fig.cap = '(ref:add-collab-01)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/add_collab_01.png") %>%
   image_crop("3584x1250")
 ```
 
 Then click "Manage access" (Figure \@ref(fig:add-collab-02)).
 
-```{r add-collab-02, fig.cap = 'The "Manage access" tab on the GitHub web interface.', fig.retina = 2, out.width="100%"}
+(ref:add-collab-02) The "Manage access" tab on the GitHub web interface.
+
+```{r add-collab-02, fig.cap = '(ref:add-collab-02)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/add_collab_02.png") %>%
   image_crop("3584x1200")
 ```
 
 Click the green "Invite a collaborator" button 
 (Figure \@ref(fig:add-collab-03)).
 
-```{r add-collab-03, fig.cap = 'The "Invite a collaborator" button on the GitHub web interface.', fig.retina = 2, out.width="100%"}
+(ref:add-collab-03) The "Invite a collaborator" button on the GitHub web interface.
+
+```{r add-collab-03, fig.cap = '(ref:add-collab-03)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/add_collab_03.png") %>%
   image_crop("3584x2200")
 ```
@@ -692,7 +710,9 @@ image_read("img/version_control/git_pull_02.png")
 And then when you open (or refresh) the files whose changes you just pulled,
 you should be able to see them (Figure \@ref(fig:git-pull-03)).
 
-```{r git-pull-03, fig.cap = 'Changes made by the collaborator to `eda.ipynb` (code highlighted by red arrows).', fig.retina = 2, out.width="100%"}
+(ref:git-pull-03) Changes made by the collaborator to `eda.ipynb` (code highlighted by red arrows).
+
+```{r git-pull-03, fig.cap = '(ref:git-pull-03)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/git_pull_03.png")
 ```
 
@@ -795,14 +815,18 @@ thread. Replying to issues from email is also possible. Given all of these advan
 To open a GitHub issue, 
 first click on the "Issues" tab (Figure \@ref(fig:issue-01)).
 
-```{r issue-01, fig.cap = 'The "Issues" tab on the GitHub web interface.', fig.retina = 2, out.width="100%"}
+(ref:issue-01) The "Issues" tab on the GitHub web interface.
+
+```{r issue-01, fig.cap = '(ref:issue-01)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/issue_01.png") %>%
   image_crop("3584x1250")
 ```
 
 Next click the "New issue" button (Figure \@ref(fig:issue-02)).
 
-```{r issue-02, fig.cap = 'The "New issues" button on the GitHub web interface.', fig.retina = 2, out.width="100%"}
+(ref:issue-02) The "New issues" button on the GitHub web interface.
+
+```{r issue-02, fig.cap = '(ref:issue-02)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/issue_02.png") %>%
   image_crop("3584x1250")
 ```
@@ -828,7 +852,9 @@ When a conversation is resolved, you can click "Close issue".
 The closed issue can be later viewed by clicking the "Closed" header link 
 in the "Issue" tab (Figure \@ref(fig:issue-06)).
 
-```{r issue-06, fig.cap = 'The "Closed" issues tab on the GitHub web interface.', fig.retina = 2, out.width="100%"}
+(ref:issue-06) The "Closed" issues tab on the GitHub web interface.
+
+```{r issue-06, fig.cap = '(ref:issue-06)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/issue_06.png") %>%
   image_crop("3584x1900")
 ```