Using Quarto and RStudio to build Data fellowship module materials

MACEPA Data Fellowship - Training Materials

Starting Point

These resources are intended to help us build and maintain materials and modules for the Data Fellowship training materials. These can also serve as a useful resource when wanting to use Quarto and GitHub pages for other aspects of our work. Therefore these resources will continue to grow and evolve with us - send suggestions for content or improvements through the issues tab on the GitHub Repo.

⚠ System Requirements ⚠

Before you can start using Quarto to build out webpages or reports you need to ensure the following are installed on your computer

• R - https://www.r-project.org/

• Rstudio - https://posit.co/download/rstudio-desktop/

• Quarto - https://quarto.org/docs/download/

• Git - https://git-scm.com/downloads

Ensure you have a GitHub profile and are a member of PATH-Global-Health organization

If you haven’t installe these packages before ensure the usethis gh renv and quarto packages are installed by typing this in the RStudio console:

install.packages(c("usethis", "gh", "renv", "quarto", "gitcreds"))

Configure Git with RStudio

After installing Git and setting up a GitHub account, the next step is to configure Git in RStudio. If you’ve linked your GitHub account to R already then skip ahead to What stage are you building from?

1. Open RStudio.

2. Configure Git in RStudio:

   • Go to Tools > Global Options.

   • In the left-hand sidebar, click Git/SVN.

   • Make sure the path to the Git executable is correct (this should automatically detect where Git was installed). For Windows, it might look something like C:/Program Files/Git/bin/git.exe.

   • Click Ok

3. We want Git to know who we are so it can associate changes with you. Enter the following code in your console and replace the user name and email to those linked to your github account

usethis::use_git_config(user.name="Jane Doe", user.email="jane@example.org")

Linking to GitHub

When its time to send our files to GitHub, we need GitHub to know who we are and that we have permission to write to our repositories. We can establish this authorisation through either a personal access token or a SSH key.

We can generate a PAT through GitHub directly through https://github.com/settings/tokens and click “Generate token”. Look over the scopes; I highly recommend selecting repo, user, and workflow. Copy the generated PAT to your clipboard. Or leave that browser window open and available for a little while, so you can come back to copy the PAT.

Another option is to create this directly in R using:

usethis::create_github_token()

Recommended scopes will be pre-selected if you used create_github_token().

Now in R call, gitcreds::gitcreds_set() to get a prompt where you can paste your PAT:

> gitcreds::gitcreds_set()

? Enter password or token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-> Adding new credentials...
-> Removing credentials from cache...
-> Done.

You should be able to work with GitHub now, i.e. push and pull!

What stage are you building from?

Before getting started we need to understand from what point we are building resources from - the following starting points cover the most common starting points we tend to find ourselves in

Starting Point	Description
Building from scratch	Start here if you want to learn about setting up a completly new resource and with tips and steps about using GitHub for the first time too
Building from an existing GitHub Repository	Start here if you are collaborating on resources and want to add additional materials to an already existing module