chore(sync): 🔨 synced file(s) with rostools/r3-theme

.gitignore

@@ -9,6 +9,7 @@ _ignore
 bin/
 dev/
 _temp/
+/.luarc.json
 
 # Temporary files
 *.tmp

.vscode/settings.json

@@ -30,4 +30,14 @@
     "sessions",
     "appendix"
   ],
+  "cSpell.customDictionaries": {
+    "project-words": {
+      "name": "repo-words",
+      "path": "${workspaceRoot}/includes/dictionary.txt",
+      "description": "Words used in this repository.",
+      "addWords": true
+    },
+    "custom": true, // Enable the `custom` dictionary
+    "internal-terms": false // Disable the `internal-terms` dictionary
+  }
 }

_extensions/rostools/r3-theme/custom-slides.scss

@@ -8,37 +8,13 @@ $font-family-serif: "Quicksand", sans-serif !default;
 $font-family-sans-serif: "Quicksand", sans-serif !default;
 $font-family-monospace: "PT Mono", monospace !default;
 $presentation-heading-font: "Outfit", sans-serif !default;
-
-/*
-From litera:
-$primary: #4582ec !default;
-$secondary: #adb5bd !default;
-*/
-
-/*
-# For background
-monochromeR::generate_palette("#ffffff", "go_darker", n_colours = 20, view_palette = TRUE)
-# For headers (primary)
-monochromeR::generate_palette("#4582ec", "go_darker", n_colours = 4, view_palette = TRUE)
-# For links
-monochromeR::generate_palette("#4582ec", "go_lighter", n_colours = 4, view_palette = TRUE)
-*/
-
 $primary: #203C6E !default;
 $secondary: #adb5bd !default;
-
 $presentation-heading-color: $primary !default;
-
 $presentation-font-size-root: 35px !default;
 $presentation-h2-font-size: 2em !default;
 $body-bg: #E9E9E9 !default;
 $link-color: #4582ec !default;
-/* sets color of controls as well as links */
-/*
-$body-color: #403E4A;
-$highlight-color: #574997;
-$selection-bg: #9A91C0;
-*/
 
 /*-- scss:rules --*/
 

_extensions/rostools/r3-theme/includes/install-r-packages.qmd

@@ -0,0 +1,62 @@
+```{=html}
+<!-- 
+Need to set a project or document level "workshop_level" variable:
+
+So far, can only be:
+
+- "introduction"
+- "intermediate"
+- "advanced"
+-->
+```
+
+We will be using specific R packages for the workshop, so you will need to
+install them. A detailed walkthrough for installing the necessary
+packages is available on the [pre-workshop tasks for installing
+packages](https://r-cubed-intro.rostools.org/preamble/pre-course.html#installing-r-packages)
+section of the introduction workshop, however, you only need to install
+the r3 helper package in order to install all the necessary packages by
+running these commands in the R Console:
+
+1.  Install the `{pak}` package:
+
+    ``` r
+    install.packages("pak")
+    ```
+
+2.  Install our custom r3 helper package for this workshop:
+
+    ``` r
+    pak::pak("rostools/r3")
+    ```
+
+3.  Install the necessary packages for the workshop:
+
+    ``` r
+    r3::install_packages_{{< meta workshop_level >}}
+    ```
+
+::: {.callout-warning appearance="default"}
+You might encounter an error when running this code. That's ok, you can
+fix it if you restart R by going to `Sessions -> Restart R` and re-run
+the code in items 2 and 3, it should work. If that also doesn't work, try to
+complete the other tasks, complete the survey, and let us know you have a
+problem in the survey.
+:::
+
+*Note*: When you see a command like `something::something()`, for
+example with `r3::install_packages_{{< meta workshop_level >}}`, you would
+"read" this as:
+
+> R, can you please use the `install_packages_{{< meta workshop_level >}}`
+> function from the r3 package.
+
+The normal way of doing this would be to load the package with
+`library(r3)` and then running the command
+(`install_packages_{{< meta workshop_level >}}`). But by using the `::`,
+we tell R to directly use a function from a package, without needing to
+load the package and all of its other functions too. We use this trick
+because we only want to use the
+`install_packages_{{< meta workshop_level >}}` command from the r3 package
+and not have to load all the other functions as well. In this workshop we
+will be using `::` often.

_extensions/rostools/r3-theme/includes/installing-programs-r.qmd

@@ -0,0 +1,124 @@
+The first thing to do is to install these programs. You may already have
+some of them installed and if you do, please make sure that they are at
+least the minimum versions listed below. If not, you will need to update
+them.
+
+::: panel-tabset
+### Windows
+
+1.  [R](https://cloud.r-project.org/bin/windows/base/): Any version
+    above `r min(r3admin::get_allowed_r_versions())`. If you have used R
+    before, you can confirm the version by running `R.version.string` in
+    the Console.
+2.  [RStudio](https://www.rstudio.com/products/rstudio/download/#download):
+    Any version above `r r3admin::get_allowed_rstudio_versions()[1]`. If
+    you have installed it before, check the current version by going to
+    the menu `Help -> About RStudio`.
+3.  [Git](https://git-scm.com/download/win): Select the "Click here to
+    download" link. Git is used throughout many sessions in the courses.
+    When installing, it will ask for a selecting a "Text Editor" and
+    while we won't be using this in the course, Git needs to know this
+    information so choose Notepad.
+4.  [Rtools](https://cran.r-project.org/bin/windows/Rtools/): Version
+    that says "R-release". Rtools is needed in order to build some R
+    packages. For some computers, installing Rtools can take some time.
+
+### MacOS
+
+1.  [R](https://cloud.r-project.org/bin/macosx/): Any version above
+    `r min(r3admin::get_allowed_r_versions())`. If you have used R
+    before, you can confirm the version by running `R.version.string` in
+    the Console. If you use [Homebrew](https://brew.sh/), installing R
+    is as easy as opening a Terminal and running:
+
+    ``` bash
+    brew install --cask r
+    ```
+
+2.  [RStudio](https://www.rstudio.com/products/rstudio/download/#download):
+    Any version above `r r3admin::get_allowed_rstudio_versions()[1]`. If
+    you have installed it before, check the current version by going to
+    the menu `Help -> About RStudio`. With Homebrew:
+
+    ``` bash
+    brew install --cask rstudio
+    ```
+
+3.  [Git](https://git-scm.com/download/mac): Git is used throughout many
+    sessions in the courses. With Homebrew:
+
+    ``` bash
+    brew install git
+    ```
+
+### Linux (Ubuntu)
+
+1.  [R](https://cloud.r-project.org/bin/linux/ubuntu/): Any version
+    above `r min(r3admin::get_allowed_r_versions())`. If you have used R
+    before, you can confirm the version by running `R.version.string` in
+    the Console.
+
+    ``` bash
+    sudo apt -y install r-base
+    ```
+
+2.  [RStudio](https://www.rstudio.com/products/rstudio/download/#download):
+    Any version above `r r3admin::get_allowed_rstudio_versions()[1]`. If
+    you have installed it before, check the current version by going to
+    the menu `Help -> About RStudio`.
+
+3.  [Git](https://git-scm.com/download/mac): Git is used throughout many
+    sessions in the courses.
+
+    ``` bash
+    sudo apt install git
+    ```
+:::
+
+All these programs are required for the course, even Git. Git, which is
+a software program to formally manage versions of files, is used because
+of it's popularity and the amount of documentation available for it.
+Check out the online book [Happy Git with
+R](https://happygitwithr.com/), especially the "Why Git" section, for an
+understanding on why we are teaching Git. Windows users tend to have
+more trouble with installing Git than macOS or Linux users. See the
+section on [Installing Git for
+Windows](https://happygitwithr.com/install-git.html#install-git-windows)
+for help.
+
+::: {.callout-note appearance="default"}
+Some pictures may show a Git pane in RStudio, but you may not see it. If
+you haven't created or opened an RStudio R Project (which is taught in
+the introductory course), the Git pane *does not* show up. It only shows
+up in R Projects that use Git to track file changes.
+:::
+
+::: {.callout-note appearance="default"}
+*A note to those who have or use work laptops with restrictive
+administrative privileges*: You may encounter problems installing
+software due to administrative reasons (e.g. you don't have permission
+to install things). Even if you have issues installing or updating the
+latest version of R or RStudio, you will likely be able to continue with
+the course as long as you have the minimum version listed above for R
+and for RStudio. If you have versions of R and RStudio that are older
+than that, you may need to ask your IT department to update your
+software if you can't do this yourself. Unfortunately, Git is not a
+commonly used software for some organizations, so you may not have it
+installed and you *will* need to ask IT to install it. We *require* it
+for the course, so please make sure to give IT enough time to be able to
+install it for you prior to the course.
+:::
+
+Once R, RStudio, and Git have been installed, open RStudio. *If you
+encounter any troubles during these pre-course tasks*, try as best as
+you can to complete the task and then let us know about the issues in
+the pre-course survey of the course. If you continue having problems,
+indicate on the survey that you need help and we can try to book a quick
+video call to fix the problem. Otherwise, you can come to the course
+15-20 minutes earlier to get help.
+
+If you're unable to complete the setup procedure due to unfixable
+technical issues, you can use Posit Cloud (to use RStudio on the cloud)
+as a final solution in order to participate in the course. For help
+setting up Posit Cloud for this course, refer to the [Posit Cloud setup
+guide](https://guides.rostools.org/posit-cloud).