In CenterForAssessment/packageSkeletonForR: A GitHub based package skeleton for R together with a static website

library(packageSkeletonForR)
is_html_output = function() {
  knitr::opts_knit$get("rmarkdown.pandoc.to")=="html"
}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "",
    prompt=TRUE,
    fig.dpi = 96
            )
if (is_html_output()) {
    options(width=1000)
}

The packageSkeletonForR is both a GitHub version control repository, and associated GitHub hosted static website as well as an R package. The combination of GitHub and R together is a super-power skill to develop if you have a serious interest in data analysis.

The following steps are meant to help you get set up:

Step 0: Make sure you have the basics

You'll need to have software installed and access to GitHub to make all of this work.

• Have R >= 4.0 installed. If you use RStudio, make sure to update it to the latest version.
• Make sure you have a GitHub account with a username and password.
• Update all your R packages that you have installed: update.packages(ask=FALSE)
• You'll need to install several R packages to make all of this work:
• devtools: install.packages("devtools")
• packagePages: devtools::install_github("centerforassessment/packagePages")
• centerPackageTemplate: devtools::install_github("centerforassessment/centerPackageTemplate")

Step 1: Clone the GitHub repository

The contents of this repo need to be cloned to your local computer/device. This is done by cloning the repo. Don't fork the repo as you won't be contributing to this package skeleton (at least I don't expect you will --- however that's OK too) but instead will be using this as a starting point to create your own customzed R package/GitHub repo that will, ideally, be quite different. If you're using RStudio, there are some easy to follow directions on how to integrate RStudio with GitHub and, among many other things, clone a repo.

Step 2: Create a repo in your account for your package

Once you have cloned the packageSkeletonForR repo, you need to create a repo in your personal (or institutional) GitHub page that will house your modified version of this package skeleton. Go to your GitHub page and look for the repositories tab toward the top and click on the new button to start creating a new repo that will house the source code for your R package. Here's a screenshot from my initial setup:

Step 3: Have fun customizing the package

The packageSkeletonForR package is a super simple R package that contains just two functions for illustration purposes: strHead and strTail. These two functions take two arguments (string and n_char) and take the first n_char characters off the head or tail of the string (or a vector of character strings), respectively. They are the analogs of the R functions head and tail but for strings. You're welcome to keep these functions or remove them.

Some things you should do:

• Change the name of the package from packageSkeletonForR to something you want (in these instructions we'll call is myPackageName). Throughout the package change any occurrence of packageSkeletonForR to the name you pick.
• Add additional functions to the package.
• For each new function you add, update the NAMESPACE (export the function) and document the function in the man (manual) folder. Examine the current NAMESPACE and man folder contents to see how that is done.
• Update the NEWS.md and NEWS files indicating changes to the package. NEWS.md is used for the static website and, ideally, will just be a copy of NEWS.
• Add a vignette to the vignettes folder. Use the basic vignette that you're reading now (packageSkeletonForR.Rmd) in the folder as a starter.
• Change the version number in DESCRIPTION, inst/CITATION, man/packageSkeletonForR.Rmd (last file should be named the package name you picked).

To help illustrate what all these changes would look like, I've cloned the packageSkeletonForR and modified it and created a customized version of it called customizedPackageForR:

• GitHub repo
• Website

Step 4: Build, check and install your package locally

Once you get your package tidied up with name changes and customizations, to make sure everything is working build your package locally. If you're using RStudio, there are capabilities to build the package included in the user interface. If you are using OSX or Windows you will likely be using the command line to build, check, and install your package locally.

Step 5: Update your package website

Step 6: Push your package to GitHub and set up GitHub

You'll need to create a GitHub repo in your account for myPackageName.

GitHub is rapidly evolving into much more than a website to do version control. For each repo, one can set up:

• A static website that can be used in many ways including documentation of the R package, demonstrating the R package capabilities,
• Process to build the package and test whether the build has any issues. The build processes on GitHub allow one to build against different OS platforms as well as against the current development version of R (which is required if you want to post to CRAN).

Another huge benefit of using GitHub to build your package is that you can immediately share your package with others without necessarily posting the package to CRAN. packageSkeletonForR is a functional R package and can be installed from GitHub just like any other R package via:

devtools::install_github("CenterForAssessment/packageSkeletonForR")

or

remotes::install_github("CenterForAssessment/packageSkeletonForR")

Once you get the package set up in your own repository, your package will be able to be installed similarly. In our work we have functional development versions of the package available via GitHub and periodically post a big release version on CRAN just to keep that up-to-date.

Contributions & Requests

The packageSkeletonForR Package is crafted with love by:

• Damian Betebenner

I love feedback and am happy to answer questions. Feel free to clone and make a pull request with the specifications for other languages.

CenterForAssessment/packageSkeletonForR documentation built on April 24, 2022, 7:54 p.m.