diff --git a/example.md b/example.md index b364f053..04cfe9d7 100644 --- a/example.md +++ b/example.md @@ -99,12 +99,15 @@ You can also include figures: pie( c(Sky = 78, "Sunny side of pyramid" = 17, "Shady side of pyramid" = 5), init.angle = 315, - col = c("deepskyblue", "yellow", "yellow3"), + col = c("deepskyblue", "yellow", "yellow3"), border = FALSE ) ``` -plot of chunk pyramid +
+pie chart illusion of a pyramid +

Sun arise each and every morning

+
## Math diff --git a/introduction.md b/introduction.md index d70ba18b..72c99419 100644 --- a/introduction.md +++ b/introduction.md @@ -74,7 +74,7 @@ commit message being `Initial commit [via {sandpaper}]`. :::::::::::::::::::::: callout -## :ladybug: Known Quirk +## :beetle: Known Quirk If you are using RStudio, then an RStudio project file (`*.Rproj`) is automatically created to help anchor your project. You might notice changes to @@ -158,7 +158,7 @@ notice a warning at the end of the rendering: :::::::::::::: solution -### Warning Message +## Warning Message ```{.warning} Warning message: diff --git a/md5sum.txt b/md5sum.txt index d94a1968..34c88f29 100644 --- a/md5sum.txt +++ b/md5sum.txt @@ -2,13 +2,13 @@ "/Users/runner/work/sandpaper-docs/sandpaper-docs/CODE_OF_CONDUCT.md" "8d9e44dd5c39f241b5e8b47ecfc802d1" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/CODE_OF_CONDUCT.md" "/Users/runner/work/sandpaper-docs/sandpaper-docs/LICENSE.md" "afaf427b4223952624dcb6d8ded53ec0" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/LICENSE.md" "/Users/runner/work/sandpaper-docs/sandpaper-docs/index.md" "c2962fcb85a8af40b90de2e043f990c7" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/index.md" -"/Users/runner/work/sandpaper-docs/sandpaper-docs/episodes/introduction.md" "b35eed32210cfa4ef734339fcd98bc98" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/introduction.md" +"/Users/runner/work/sandpaper-docs/sandpaper-docs/episodes/introduction.md" "8bcceb034f013bb20675482a89ad21a7" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/introduction.md" "/Users/runner/work/sandpaper-docs/sandpaper-docs/episodes/episodes.Rmd" "89305de347de403844c0cb747d1ea806" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/episodes.md" "/Users/runner/work/sandpaper-docs/sandpaper-docs/episodes/editing.md" "472d7a8f9e11ef8113a339b1b9a66e77" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/editing.md" -"/Users/runner/work/sandpaper-docs/sandpaper-docs/episodes/example.Rmd" "d92224d8a2fde5e99ad7b04c0ade274b" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/example.md" +"/Users/runner/work/sandpaper-docs/sandpaper-docs/episodes/example.Rmd" "b030222a2d9cad33f04c8c2676e6a026" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/example.md" "/Users/runner/work/sandpaper-docs/sandpaper-docs/episodes/deployment.md" "cab12c5c0be0148522ad3af38f532ff8" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/deployment.md" "/Users/runner/work/sandpaper-docs/sandpaper-docs/instructors/notes.md" "1b23451c437e71b86f312bef374b02e5" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/notes.md" -"/Users/runner/work/sandpaper-docs/sandpaper-docs/learners/setup.md" "9d1084d404a366147117f3ba8530a502" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/setup.md" +"/Users/runner/work/sandpaper-docs/sandpaper-docs/learners/setup.md" "70e22a1f3d9ec87faf769eee2de78e24" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/setup.md" "/Users/runner/work/sandpaper-docs/sandpaper-docs/learners/github-pat.md" "65e9fd0b6de9f7904e01e5652fd3f12f" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/github-pat.md" "/Users/runner/work/sandpaper-docs/sandpaper-docs/profiles/maintainer.md" "2a2b790c0aa8da5fb72e323e4fafabd9" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/maintainer.md" "/Users/runner/work/sandpaper-docs/sandpaper-docs/profiles/instructor.md" "ff8c586028a5e1c7ef0be4178b40417c" "/Users/runner/work/sandpaper-docs/sandpaper-docs/site/built/instructor.md" diff --git a/setup.md b/setup.md index 6ddf98d7..263d4416 100644 --- a/setup.md +++ b/setup.md @@ -2,110 +2,272 @@ title: Setup --- -The {sandpaper} template requires [R] and [pandoc] to be installed. Since [pandoc] is installed via [RStudio], we recommend R and RStudio. Read on for more details about the software used in the template. +## Overview -## Foundational software +The lesson infrastructure is built on Git, [R], and [pandoc]. It consists of +four components: -There are three programs that the template works with: Git, RStudio, and pandoc. -They can be installed from the following resources: +1. The source content (plain markdown or RMarkdown files organized into folders + with a configuration yaml file) +2. The engine (R package [{sandpaper}])to orchestrate building the content from + markdown to HTML +3. The validator (R package [{pegboard}]) to parse the source files and + highlight common errors[^tinkr] +4. The style (R package [{varnish}]) HTML, CSS, and JavaScript styling elements + for the final website - - **Git** (>= 2.28) https://carpentries.github.io/workshop-template/#git - - **R** (>= 3.6) https://carpentries.github.io/workshop-template/#r[^linux-r] - - **pandoc** (>= 2.11) we recommend installing this by [installing the RStudio - IDE][RStudio][^linux-rstudio], but you can also install it [via pandoc's - website](https://pandoc.org/installing) or [via anaconda - ](https://carpentries.github.io/workshop-template/#python) +[Details of how these tools work together are explained in the Lesson +Deployment](deployment.md) chapter. In short, you can expect to interact with +the source content and {sandpaper} to author and preview your lesson. -::::: solution +### Required Software {#required} -### What if I don't want to use RStudio? +This setup document will walk you through the process of installing or upgrading +the required software in the following order. -That's perfectly okay and expected! +1. **Git** (≥ 2.28 recommended) +2. **R** (≥ 3.6) +3. **pandoc** (≥ 2.11) +4. The lesson infrastructure R packages + i. **[{sandpaper}]** (development version) + ii. **[{varnish}]** (development version) + iii. **[{pegboard}]** (development version) + iiii. **[{tinkr}]** (markdown parser required by {pegboard}, development version) -We recommend using RStudio because it wraps an R console, a text editor, -git management, and a file browser in one program. This provides a lot of -convenience of being able to work consistently across platforms and reduces the -barrier for entry. +### Recommended Software {#recommend} -We want to be able to meet you where you are to work with the new template. If -you feel comfortable using a different tool (e.g. the command line or VSCode), -then you should install R and pandoc separately and make sure that they are in -your path. +If you are using R or pandoc for the first time, we recommend using [the RStudio +IDE][RStudio] for the following reasons: -If you are using Windows, setting up your PATH variables can sometimes be -tricky. The pandoc installer will automatically add itself to your PATH, but R -will not. [Here are some instructions on setting up your PATH on Windows using -both the GUI and CLI](https://www.maketecheasier.com/what-is-the-windows-path/). -Note that R will normally install at something like -`c:\Program Files\R\R-4.0.0\bin\x64`, but if you are not admin, it will install -in your documents folder. +1. It comes with [pandoc] pre-installed. +2. Works consistently across all major platforms. +3. A dedicated BASH console so you can easily switch between R and Git + operations. +4. Convenient keyboard shortcuts to preview lessons. +5. On Windows, it will automatically detect your R installation without you + needing to edit your `PATH`. -::::::::: +If you do not want to use RStudio, that's perfectly okay and expected! We want +to be able to meet you where you are to work with the new template. If you feel +comfortable using a different tool (e.g. the command line or VSCode), then you +should install R and pandoc separately and make sure that they are in your path. -## Starting R +### Installation -Throughout the lesson, I will ask you to **open R or RStudio**. If you are using -RStudio, you can open it by double-clicking on the RStudio icon in your -application launcher. You do not have to open R separately for this. +This will guide you through installing the foundational software and +infrastructure packages on your computer. If you already have software +installed and are curious if you should update it to a newer version, the answer +is almost always, yes, update to a newer version, because often the [newer +versions will contain important bug fixes that are important to the secruity of +your computer](https://github.com/git/git/security/advisories/GHSA-8prw-h3cq-mghm). -If you are using R, you can open it in your terminal application by typing `R`. -Your prompt will be replaced by a `>`, which indicates that you are in R's -interactive [REPL](https://glosario.carpentries.org/en/#repl). +Jump to the installation instructions for your system: [Windows](#windows), +[MacOS](#mac), or [Linux](#linux) +## Installing on Windows {#windows} -You can exit R by typing `q()` in the R console. +### Git -::::::::: prereq +We recommend installing git via the Git for Windows installer at +. The installer is going to ask a lot of questions, +so we recommend [using The Carpentries checklist for workshop +participants](https://carpentries.github.io/workshop-template/#shell-windows). -### Setting up your R workspace +#### Test your installation -When you set up R, it's important to make sure you set it up to always start R -with a clean slate[^workspace]: never save your workspace on exit and never -load a previously saved workspace on startup. +To test that you have git installed, you can go to your taskbar at the bottom +of your screen and type `cmd` to bring up the command prompt. From there, you +can type `git --version` to see the version of your git installation. You might +see something like this: -#### Via RStudio +```bash +git --version +``` -If you are using RStudio, you can [follow the instructions in this forum -post](https://community.rstudio.com/t/first-line-of-every-r-script/799/12?u=zkamvar): +```output +git version 2.31.1.windows.1 +``` -1. From the menu, select Tools > Global Options -2. Under **Workspace Options**, de-select "Restore .RData into workspace at - startup" and set "Save workspace to .RData on exit" to "Never" +If, however, you see this error, then you should try to install git again. -#### Via Command Line Interface +```error +'git' is not recognised as an internal or external command, +operable program or batch file. +``` -The flags `--no-restore` and `--no-save` will set these defaults, so you can -create an alias for R in the `.bashrc` file in your home directory: + +### R + +You can install the latest [R] for Windows from +. There is also a video tutorial +up on [The Carpentries instructions for workshop +participants](https://carpentries.github.io/workshop-template/#rstats-windows) +that can be quite helpful for parsing the steps of installing R on Windows. + +::::::::::::::::::::: callout + +#### Optional: Want to add R to your PATH? {#winpath} + +As we mention above, [we recommend using RStudio for your lesson](#recommend), +but if you want to be able to integrate the lesson infrastructure into your own +preferred workflow, you need to have R on your path. The catch is that R for +Windows does not automatically set your `PATH` variable. + +[Here are some instructions on setting up your PATH on Windows using both the +GUI and CLI](https://www.maketecheasier.com/what-is-the-windows-path/). Note +that R will normally install at something like +`c:\Program Files\R\R-4.1.0\bin\x64`, but if you are not admin, it will install +in your Documents folder. + +To verify that R is installed in your `PATH`, you can go to your taskbar at the +bottom of your screen and type `cmd` to bring up the command prompt. From there, +you can type `R --version` at the prompt: ```bash -alias R='R --no-restore --no-save' +R --version +``` +```output +R version 4.1.0 (2021-05-18) -- "Camp Pontanezen" +Copyright (C) 2021 The R Foundation for Statistical Computing +Platform: x86_64-mingw32/x64 (64-bit) + +R is free software and comes with ABSOLUTELY NO WARRANTY. +You are welcome to redistribute it under the terms of the +GNU General Public License versions 2 or 3. +For more information about these matters see +https://www.gnu.org/licenses/. ``` -:::::::::::::::::: +::::::::::::::::::::::::::::: + +### pandoc + +There are two ways to install pandoc: + +#### Via RStudio (recommended) + +Since pandoc comes bundled with RStudio, you can install it by installing the +latest version of RStudio. You can [download the installer from the RStudio +website][RStudio]. + +#### Via the pandoc website + +If you are comfortable adding R to your windows PATH (see [previous +section](#winpath)), then you can install pandoc by using the binary provided on +its website at + +#### Test your installation + +We will wait to test the pandoc installation after we install the +infrastructure packages, to make sure it's discoverable by R. + +### Infrastructure R packages -:::::::::::::::::::::: callout +To install the R packages, you will need to **open RStudio** (or start R from +the command line if you did not install RStudio) and enter the following lines +into the console. -### There are many ways to set up R to work with the lesson template +```r +# register the repositories for The Carpentries and CRAN +options(repos = c( + carpentries = "https://carpentries.github.io/drat/", + ropensci = "https://ropensci.r-universe.dev/", + CRAN = "https://cran.rstudio.com/" +)) + +# Install the template packages to your R library +install.packages(c("sandpaper", "varnish", "pegboard", "tinkr")) +``` + +## Installing on MacOS {#mac} + +### Git + +You should have git pre-installed on your macOS, but it is likely that this is +an old version. We recommend installing [The latest version of Git for MacOS +from sourceforge](http://sourceforge.net/projects/git-osx-installer/files/) +(**ignore the big green button** and choose the latest version from the list). +For a video walkthrough and an explanation of what to expect, you can look at +the [instructions for workshop +participants](https://carpentries.github.io/workshop-template/#git-macos). + +#### Test your installation + +To test your installation of Git and confirm it works, open **Terminal.app** and +type the following: + +```bash +git --version +``` + +```output +git version 2.31.0 +``` -For example, Zhian Kamvar uses Vim with the NVim-R plugin and -[radian](https://github.com/randy3k/radian#readme) on macOS and Linux. There is -no one right way! +If you have the default version of git, you might see this output, and that's +okay for the purposes of this template. -::::::::::::::::::::::::::::::: +```output +git version 2.24.3 (Apple Git-128) +``` + +### R + +You can install the latest [R] release for MacOS from +. There is also a video tutorial +up on [The Carpentries instructions for workshop +participants](https://carpentries.github.io/workshop-template/#rstats-macos) +that can be quite helpful for parsing the steps of installing R on MacOS. + +#### Test your installation + +You can test your installation of R by opening **Terminal.app** and typing `R +--version` into the prompt: + +```bash +R --version +``` +```output +R version 4.1.0 (2021-05-18) -- "Camp Pontanezen" +Copyright (C) 2021 The R Foundation for Statistical Computing +Platform: x86_64-apple-darwin17.0 (64-bit) + +R is free software and comes with ABSOLUTELY NO WARRANTY. +You are welcome to redistribute it under the terms of the +GNU General Public License versions 2 or 3. +For more information about these matters see +https://www.gnu.org/licenses/. +``` -## Lesson Template Modules (R packages) +### pandoc -The template is divided into three R packages, which are designed to be modular -and upgradable on the fly. Because these are still in developement, please use -the following to install (*and update*) the packages: +There are two ways to install pandoc: -First, **open R or RStudio** and then follow the instructions based on your -operating system: +#### Via RStudio (recommended) -::::::::::: solution +Since pandoc comes bundled with RStudio, you can install it by installing the +latest version of RStudio. You can [download the installer from the RStudio +website][RStudio]. -### MacOS/Windows +#### Via the pandoc website + +If are more comfortable using R from the command line, then you can install +pandoc by clicking the "Download the latest installer for macOS" button at +. This will save a file called +`pandoc-X.XX-macOS.pkg` installer to your computer. Open the installer and +follow the instructions to install pandoc on your computer. + +#### Test your installation + +We will wait to test the pandoc installation after we install the +infrastructure packages, to make sure it's discoverable by R. + +### Infrastructure R packages + +To install the R packages, you will need to **open RStudio** (or start R from +the command line if you did not install RStudio) and enter the following lines +into the console. ```r # register the repositories for The Carpentries and CRAN @@ -119,12 +281,118 @@ options(repos = c( install.packages(c("sandpaper", "varnish", "pegboard", "tinkr")) ``` -:::::::::::::::::::: +## Installing on Linux {#linux} +A lot of the documentation for Linux is nuanced because it assumes that if you +use Linux, then you automatically know how to install things by the command +line. I will be providing instructions as best I can for Ubuntu Linux and point +to resourced for other distributions. For Ubuntu/Debian, the default `apt` +repository is often out of date, so you will need to use a +[Personal Package Archive aka PPA](https://itsfoss.com/ppa-guide/) to install +the latest version of a particular software, which I will include in these +instructions. -::::::::::: solution +### Git -### Linux +You should have git pre-installed on your computer, but it will likely be +outdated. It's okay if this is the case, but if you want to update via `apt`, +you can add the git-core ppa: + +```bash +sudo add-apt-repository ppa:git-core/ppa +sudo apt update +sudo apt install git +``` + +#### Test your installation + +Test your git installation by opening the terminal and running + +```bash +git --version +``` +```output +git version 2.31.1 +``` + +### R + +To install R, you can visit to check if +your platform is supported. For Ubuntu, there are detailed instructions at: +. Here are the commands to register +the PPA on your machine and then install R: + +```bash +# update indices +sudo apt update -qq +# install two helper packages we need +sudo apt install --no-install-recommends software-properties-common dirmngr +# import the signing key (by Michael Rutter) for these repo +sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E298A3A825C0D65DFD57CBB651716619E084DAB9 +# add the R 4.0 repo from CRAN -- adjust 'focal' to 'groovy' or 'bionic' as needed +sudo add-apt-repository "deb https://cloud.r-project.org/bin/linux/ubuntu $(lsb_release -cs)-cran40/" + +# Install R +apt install --no-install-recommends r-base +``` + +#### Test your installation + +Test your R installation by opening your terminal and running: + +```bash +R --version +``` + +```output +R version 4.1.0 (2021-05-18) -- "Camp Pontanezen" +Copyright (C) 2021 The R Foundation for Statistical Computing +Platform: x86_64-pc-linux-gnu (64-bit) + +R is free software and comes with ABSOLUTELY NO WARRANTY. +You are welcome to redistribute it under the terms of the +GNU General Public License versions 2 or 3. +For more information about these matters see +https://www.gnu.org/licenses/. + +``` + +### pandoc + +There are two ways to install pandoc: + +#### Via RStudio (recommended) + +Since pandoc comes bundled with RStudio, you can install it by installing the +latest version of RStudio. You can [download the installer from the RStudio +website][RStudio]. When installing RStudio for Linux, your distribution may not +be shown on the landing page (e.g. Ubuntu 20.04). In this case, choose the most +recent version and download it to your Downloads folder or install it directly. + +::::::::::: callout + +##### Optional: verify the install + +You can optionally verify the download before installing by following the +instructions at . + +::::::::::::::::::: + + +#### Via the pandoc website + +If are more comfortable using R from the command line, then you can install +pandoc by clicking the "Download the latest installer" button at +. This will bring you to the release page +on GitHub with a list of installers, and you should choose one of the ones that +says "linux" according to what chip architecture you have (AMD vs ARM). + +#### Test your installation + +We will wait to test the pandoc installation after we install the +infrastructure packages, to make sure it's discoverable by R. + +### Infrastructure R packages Linux packages normally need to be compiled by your system, which can take a long time the first time it happens. RStudio provides a package manager that @@ -134,7 +402,7 @@ take advantage of these binaries. The one we are using is set up for Ubuntu :::: callout -### What if I have a different version of Linux? +#### What if I have a different version of Linux? If you have a different version of linux, you can visit https://packagemanager.rstudio.com/client/#/repos/1/overview, select your @@ -143,20 +411,30 @@ Ubuntu 20.04 (Focal) **change**", and replace the packagemanager URL below. :::: +To install the R packages, you will need to **open RStudio** (or start R from +the command line if you did not install RStudio) and enter the following lines +into the console. + ```r +# register the repositories for The Carpentries and CRAN options(repos = c( carpentries = "https://carpentries.github.io/drat/", ropensci = "https://ropensci.r-universe.dev/", CRAN = "https://packagemanager.rstudio.com/all/__linux__/focal/latest" )) +# Install the template packages to your R library install.packages(c("sandpaper", "varnish", "pegboard", "tinkr")) ``` +::::::::::::: callout + +#### What if I get errors installing packages? + If you run into errors (non-zero exit status), it probably means that you were missing a C library dependency that needs to be installed via your package -manager. To resolve these issues, scroll back in the log and you might find -messages that looks similar to this: +manager (i.e. apt). To resolve these issues, scroll back in the log and you +might find messages that looks similar to this: ```output * installing *source* package ‘xslt’ ... @@ -185,14 +463,84 @@ compilation terminated. Use the instructions in these logs to install the correct package from your terminal and then open R or RStudio and retry installing the packages. -:::::::::::::::::::: +::::::::::::::::::::: -::::::::::::::::::::::::::::::::::::::::: callout +## Test your installation {#install-test} -### Your R library +Now that you have installed the lesson components, it is a good idea to run a +small test to verify that these components work together. To test your +installation **open RStudio** (or launch R if you have not installed RStudio) +and enter the following commands to confirm everything works -When you install R packages, the first message you will see will probably be -something like (on Windows): +```r +rmarkdown::pandoc_version() +tmp <- tempfile() +sandpaper::create_lesson(tmp, open = FALSE) +sandpaper::build_lesson(tmp, preview = FALSE, quiet = TRUE) +fs::dir_tree(tmp, recurse = 1) +``` + +```output +[1] ‘2.12’ +[1] "/tmp/RtmpCjGtw3/fileac05502830cf" +Warning message: +In warn_schedule() : + No schedule set, using Rmd files in `episodes/` directory. +To remove this warning, define your schedule in `config.yaml` or use `set_episodes()` to generate it. +/tmp/RtmpCjGtw3/fileac05502830cf +├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md +├── LICENSE.md +├── README.md +├── config.yaml +├── episodes +│ ├── 01-introduction.Rmd +│ ├── data +│ ├── fig +│ └── files +├── index.md +├── instructors +│ └── instructor-notes.md +├── learners +│ └── Setup.md +├── profiles +│ └── learner-profiles.md +└── site + ├── DESCRIPTION + ├── README.md + ├── _pkgdown.yaml + ├── built + └── docs +``` + +If the installation did not work, please [raise an issue on +GitHub](https://github.com/zkamvar/sandpaper-docs/issues/new) and I can help +troubleshoot. + +## Installation FAQ + +### Why does it take 6 lines of code to install the infrastructure? + +In the future, this will be ONE line of code! + +Since we are currently in the alpha phase of testing, the infrastructure can +update at any moment. Normally, packages will come from +[CRAN](https://glosario.carpentries.org/en/#cran), but our development packages +are not yet on CRAN, so the are stored in The Carpentries and rOpenSci +development repositories. + +### Do I really need to use RStudio? + +No. We recommend using RStudio for [several reasons that pertain to ease of +use and standardisation across systems](#recommend), but we do not absolutely +require it. If you are able to get Git, R, and pandoc installed on your system, +then you do not need to use RStudio. + +### What is an R Library? + +An R library is a folder on your computer that stores R packages. When you +install R packages, the first message you will see will probably be something +like (on Windows): ``` Installing packages into ‘c:/Users/USER/Documents/R/win-library/4.0’ @@ -203,12 +551,49 @@ This folder is where all of the R packages you install via `install.packages()` will live. If you ever need to look this up, you can use the `.libPaths()` function. -Sometimes, your R session will throw a warning that says a folder is not +Sometimes, your R session will issue a warning that says a folder is not writeable and asks if you would like to use a personal library instead. In this -case, select "yes". +case, select "yes". + +## Using the lesson engine + +Throughout the lesson, I will ask you to **open R or RStudio**. If you are using +RStudio, you can open it by double-clicking on the RStudio icon in your +application launcher; you do not have to open R separately to use RStudio. + +If you are using R, you can open it in your terminal application by typing `R`. +Your prompt will be replaced by a `>`, which indicates that you are in R's +interactive [REPL](https://glosario.carpentries.org/en/#repl). -:::::::::::::::::::::::::::::::::::::::::::::::::: +You can exit R or RStudio by typing `q()` in the R console. +::::::::: prereq + +### Setting up your R workspace + +When you set up R, it's important to make sure you set it up to always start R +with a clean slate[^workspace]: never save your workspace on exit and never +load a previously saved workspace on startup. + +#### Via RStudio + +If you are using RStudio, you can [follow the instructions in this forum +post](https://community.rstudio.com/t/first-line-of-every-r-script/799/12?u=zkamvar): + +1. From the menu, select Tools > Global Options +2. Under **Workspace Options**, de-select "Restore .RData into workspace at + startup" and set "Save workspace to .RData on exit" to "Never" + +#### Via Command Line Interface + +The flags `--no-restore` and `--no-save` will set these defaults, so you can +create an alias for R in the `.bashrc` file in your home directory: + +```bash +alias R='R --no-restore --no-save' +``` + +:::::::::::::::::: ## Connect to GitHub @@ -249,21 +634,18 @@ setting up authentication credentials for your account: [R]: https://cran.rstudio.org/ [pandoc]: https://pandoc.org/ +[{sandpaper}]: https://carpentries.github.io/sandpaper/ +[{pegboard}]: https://carpentries.github.io/pegboard/ +[{varnish}]: https://github.com/carpentries/varnish#readme +[{tinkr}]: https://docs.ropensci.org/tinkr/ [RStudio]: https://rstudio.com/products/rstudio/download/#download -[^workspace]: By default, R will ask if you want to save your workspace to a hidden file -called `.RData`. This is loaded when you start R, restoring your environment -with all of the packages and objects you had previously loaded. This default -behavior is not good for reproducibility and makes updating packages very -very difficult. In 2017 Jenny Bryan wrote a very good article about the benefits -of having a project-based workflow, starting from a clean slate: -https://www.tidyverse.org/blog/2017/12/workflow-vs-script/ -[^linux-r]: Linux installation may be a bit tricky. Official instructions for -various flavours of linux can be found at - -[^linux-rstudio]: When installing RStudio for Linux, your distribution may not -be shown on the landing p age (e.g. Ubuntu 20.04). In this case, choose the -most recent version and download it to your Downloads folder or install it -directly. If you download it, you can [verify the -download](https://www.rstudio.com/code-signing/) before installing. To start -RStudio, you can type `rstudio &` to launch RStudio and let the process run in -the background. +[^workspace]: By default, R will ask if you want to save your workspace to a + hidden file called `.RData`. This is loaded when you start R, restoring your + environment with all of the packages and objects you had previously loaded. + This default behavior is not good for reproducibility and makes updating + packages very very difficult. In 2017 Jenny Bryan wrote a very good article + about the benefits of having a project-based workflow, starting from a clean + slate: + +[^tinkr]: Note: {pegboard} requires the [{tinkr}] package from rOpenSci. It + is still in development, so we will install this package explicitly.