Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update setup.md #205

Merged
merged 1 commit into from
Oct 21, 2024
Merged

Update setup.md #205

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 39 additions & 43 deletions learners/setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,20 @@

## Overview

The lesson infrastructure is built on Git, [The R language][R], and [pandoc]. It consists of
The lesson infrastructure is built on Git, the R language, and pandoc. It consists of
four components:

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]
highlight common errors
4. The style (R package [{varnish}]) HTML, CSS, and JavaScript styling elements
for the final website

[Details of how these tools work together are explained in the Lesson
Deployment](../episodes/deployment.md) chapter. In short, you can expect to
Details of how these tools work together are explained in the [Lesson
Deployment chapter](../episodes/deployment.md). In short, you can expect to
interact with the source content and {sandpaper} to author and preview your
lesson.

Expand All @@ -26,19 +26,19 @@
This setup document will walk you through the process of installing or upgrading
the required software in the following order.

1. **Git** (≥ 2.28 recommended)
2. **R** (≥ 3.6)
3. **pandoc** (≥ 2.11)
1. **[Git]** (≥ 2.28 recommended)
2. **[R]** (≥ 4.x)

Check warning on line 30 in learners/setup.md

View workflow job for this annotation

GitHub Actions / Build markdown source files if valid 

 [link text too short]: [R](https://cran.rstudio.org/)
3. **[pandoc]** (≥ 3.x)
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)
iiii. **[{tinkr}]** (markdown parser required by {pegboard})

Once you have Git, R, and Pandoc installed, these packages can be installed
and updated via:
```r
install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"),
install.packages(c("sandpaper", "varnish", "pegboard"),
repos = c("https://carpentries.r-universe.dev/", getOption("repos")))
```

Expand All @@ -48,10 +48,10 @@
IDE][RStudio] for the following reasons:

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
2. It works consistently across all major platforms.
3. It provides a dedicated BASH console so you can easily switch between R and Git
operations.
4. Convenient keyboard shortcuts to preview lessons.
4. There are convenient keyboard shortcuts to preview lessons.
5. On Windows, it will automatically detect your R installation without you
needing to edit your `PATH`.

Expand All @@ -66,9 +66,9 @@
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
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).
your computer.

Jump to the installation instructions for your system: [Windows](#windows),
[MacOS](#mac), or [Linux](#linux)
Expand All @@ -77,15 +77,14 @@

### Git

We recommend installing git via the Git for Windows installer at
<https://gitforwindows.org/>. 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).
We recommend installing git via the [Git for Windows installer](https://gitforwindows.org/). The installer is going to ask a lot of questions,
so we recommend [using The Carpentries instructions for workshop
participants](https://carpentries.github.io/workshop-template/#the-bash-shell).

#### Test your installation

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
To test that you have git installed, open your command line by pressing <kbd>Windows</kbd>+<kbd>R</kbd>
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:

Expand All @@ -107,10 +106,9 @@

### R

You can install the [latest version of R][R] for Windows from
<https://cran.r-project.org/bin/windows/base/>. There is also a video tutorial
Install the [latest version of R for Windows](https://cran.r-project.org/bin/windows/base/). There is also a video tutorial
up on [The Carpentries instructions for workshop
participants](https://carpentries.github.io/workshop-template/#rstats-windows)
participants](https://carpentries.github.io/workshop-template/#r-1)
that can be quite helpful for parsing the steps of installing R on Windows.

::::::::::::::::::::: callout
Expand All @@ -128,10 +126,11 @@
`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,
To verify that R is installed in your `PATH`, open your command line by pressing
<kbd>Windows</kbd>+<kbd>R</kbd>
and type `cmd` to bring up the command prompt. From there,
you can type `R --version` at the prompt. Your output should be similar to below,
with a version ≥ 3.6.
with a version ≥ 4.x.

```bash
R --version
Expand Down Expand Up @@ -185,7 +184,7 @@
))

# Install the template packages to your R library
install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"))
install.packages(c("sandpaper", "varnish", "pegboard"))
```

## Installing on MacOS {#mac}
Expand All @@ -195,12 +194,10 @@
### 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](https://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
an old version. We recommend installing [The latest version of Git for MacOS](https://git-scm.com/downloads/mac).
For a video guide, you can look at
the [instructions for workshop
participants](https://carpentries.github.io/workshop-template/#git-macos).
participants](https://carpentries.github.io/workshop-template/#git-1).

#### Test your installation

Expand Down Expand Up @@ -247,7 +244,7 @@

You can test your installation of R by opening **Terminal.app** and typing `R
--version` into the prompt. Your output should be similar to below,
with a version ≥ 3.6.
with a version ≥ 4.x.

```bash
R --version
Expand All @@ -272,7 +269,7 @@

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]. RStudio will be a `*.dmg` (disk image) that you will open
website][RStudio]. RStudio will be a `*.dmg` (disk image) that you will
double click to open a window that will look something like this:

![](fig/rstudio-mac-install.png){alt="Installation window for RStudio on mac
Expand All @@ -284,9 +281,9 @@

#### 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
<https://pandoc.org/installing.html>. This will save a file called
If are more comfortable using R from the command line, then you can [install
pandoc](https://pandoc.org/installing.html) by clicking the "Download the latest
installer for macOS" button. 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.

Expand All @@ -309,7 +306,7 @@
))

# Install the template packages to your R library
install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"))
install.packages(c("sandpaper", "varnish", "pegboard"))
```

## Installing on Linux {#linux}
Expand Down Expand Up @@ -371,7 +368,7 @@

Test your R installation by opening your terminal and running
`R --version` into the prompt. Your output should be similar to below,
with a version ≥ 3.6.
with a version ≥ 4.x.

```bash
R --version
Expand Down Expand Up @@ -500,7 +497,7 @@
))

# Install the template packages to your R library
install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"))
install.packages(c("sandpaper", "varnish", "pegboard"))
```

::::::::::::: discussion
Expand Down Expand Up @@ -741,7 +738,9 @@

::::::::::::::::::::::::

[Git]: https://git-scm.com/
[R]: https://cran.rstudio.org/
[pandoc]: https://pandoc.org/
[{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
Expand All @@ -751,6 +750,3 @@
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/>

[^tinkr]: Note: {pegboard} requires the [{tinkr}] package from rOpenSci. It
is still in development, so we will install this package explicitly.
Loading