Skip to contents

R Package Site with pkgdown, Github Pages and Actions

Source: vignettes/ffv_pkgdown_github.Rmd
ffv_pkgdown_github.Rmd

Set up Git, Github Repository, and Github Actions

Develop a package, that includes functions with ROxygen2 documentation and also vignette files. Then, use functions from usethis to automate various git and github related tasks.

We will use below:

  • usethis::use_git(message = “Initial commit”), this makes the folder a git folder.
  • usethis::use_github(private = FALSE), this creates the local folder as a github repository (assuming authentication is established already locally).
  • usethis::use_github_action(“pkgdown”), this copies over a set of instructions for Github Action.
  • usethis::use_pkgdown_github_pages(), this creates the remote “gh-pages” branch and run Github Action first time.

Once these are set up, then in the future, edit functions and vignette files, test functions locally, and build site locally with pkgdown::build_site() in a gitignored folder. Then any pushed commits to the remote repo will trigue running through the Github Actions again, and lead to an update of the website.

# One time set-up with Git, Github, and Github Actions
usethis::use_git(message = "Initial commit")
usethis::use_github(private = FALSE)
usethis::use_github_action("pkgdown")
usethis::use_pkgdown_github_pages()

# locally building site
pkgdown::build_site()

# Install package
devtools::install_github("FanWangEcon/PkgTestR")

Initialize Git

First, initialize the project folder as a git folder with usethis::use_git(), and then commit all existing non-gitignored files. See the .gitignore file for which documents are ignored. Having commited the changes, can use VSCode, Atom, various other editors to monitor and track changes and manage git operations. RStudio also provides in the top-right pane a git tab.

For additional information, see here for how to set up git, github, github pages, etc, outside of the R environment.

# Make sure we are in the "G:/repos/PkgTestR/" directory
usethis::use_git(message = "Initial commit")

# ✔ Initialising Git repo
# ✔ Adding '.Rhistory', '.Rdata', '.httr-oauth', '.DS_Store' to '.gitignore'
# There are 10 uncommitted files:
# * '.gitignore'
# * '.Rbuildignore'
# * '_pkgdown.yml'
# * 'DESCRIPTION'
# * 'LICENSE'
# * 'man/'
# * 'NAMESPACE'
# * 'PkgTestR.Rproj'
# * 'R/'
# * 'vignettes/'
# Is it ok to commit them?
# 
# 1: Absolutely not
# 2: Yup
# 3: No way
# 
# Selection: 2
# ✔ Adding files
# ✔ Making a commit with message 'Initial commit'
# • A restart of RStudio is required to activate the Git pane
# Restart now?
# 
# 1: No
# 2: Yes
# 3: Negative
# 
# Selection: 1

Connect to Github

Second, connect to github using usethis::use_github(). Calling this, after the repo is git-initialized, accomplishes the following:

  1. Creates a remote repo on github (under the authenticated account) with the same name as the local project folder name
  2. Set up remote
  3. Update URL fields in R package
  4. Commits and pushes local to remote
  5. Open up remote repo site: https://github.com/FanWangEcon/PkgTestR

Prior to this, authentication has to be set up. This Managing Git(Hub) Credentials. See some additional authentication details here.

usethis::use_github(private = FALSE)

# ℹ Defaulting to 'https' Git protocol
# ✔ Setting active project to 'G:/repos/PkgTestR'
# There are uncommitted changes and we're about to create and push to a new GitHub repo
# Do you want to proceed anyway?
# 
# 1: Yeah
# 2: No way
# 3: Nope
# 
# Selection: Yeah
# ✔ Creating GitHub repository 'FanWangEcon/PkgTestR'
# ✔ Setting remote 'origin' to 'https://github.com/FanWangEcon/PkgTestR.git'
# ✔ Setting URL field in DESCRIPTION to 'https://github.com/FanWangEcon/PkgTestR'
# ✔ Setting BugReports field in DESCRIPTION to 'https://github.com/FanWangEcon/PkgTestR/issues'
# There is 1 uncommitted file:
# * 'DESCRIPTION'
# Is it ok to commit it?
# 
# 1: Negative
# 2: Definitely
# 3: No way
# 
# Selection: 2
# ✔ Adding files
# ✔ Making a commit with message 'Add GitHub links to DESCRIPTION'
# ✔ Pushing 'master' branch to GitHub and setting 'origin/master' as upstream branch
# ✔ Opening URL 'https://github.com/FanWangEcon/PkgTestR'

Set up Github Actions

Third, setup Github Actions using usethis::use_github_actions(). The automates a number of package building procedures for building the project’s public facing website.

The command below generates the file .github/workflows/pkgdown.yaml, which is copied over from r-lib actions. The instructions build site and deploy to Github pages, on the gh-pages branch of the github repo.

usethis::use_github_action("pkgdown")

# ✔ Saving 'r-lib/actions/examples/pkgdown.yaml@v2' to '.github/workflows/pkgdown.yaml'
# • Learn more at <https://github.com/r-lib/actions/blob/v2/examples/README.md>.

Push and Create pkgdown Website

Running usethis::use_pkgdown_github_pages() will update population various files with proper url. And it will also create on the repo repository a branch “gh-pages”, which will be used to publish the site.

usethis::use_pkgdown_github_pages()

# Overwrite pre-existing file '_pkgdown.yml'?
# 
# 1: Definitely
# 2: Absolutely not
# 3: Not now
# 
# Selection: 1
# ✔ Writing '_pkgdown.yml'
# • Modify '_pkgdown.yml'
# ✔ Initializing empty, orphan 'gh-pages' branch in GitHub repo 'FanWangEcon/PkgTestR'
# ✔ GitHub Pages is publishing from:
# • URL: 'https://fanwangecon.github.io/PkgTestR/'
# • Branch: 'gh-pages'
# • Path: '/'
# ✔ Saving 'r-lib/actions/examples/pkgdown.yaml@v2' to '.github/workflows/pkgdown.yaml'
# • Learn more at <https://github.com/r-lib/actions/blob/v2/examples/README.md>.
# ✔ Recording 'https://fanwangecon.github.io/PkgTestR/' as site's url in '_pkgdown.yml'
# ✔ Adding 'https://fanwangecon.github.io/PkgTestR/' to URL field in DESCRIPTION
# ✔ Setting 'https://fanwangecon.github.io/PkgTestR/' as homepage of GitHub repo 'FanWangEcon/PkgTestR'

Continuous Development

Once these are set up, then in the future, edit functions and vignette files, test functions locally, and build site locally with pkgdown::build_site(), whose outputs are stored in a gitignored folder and will not be pushed to the remote repo.

We can also use devtools::check to make sure that various documentations etc are all proper.

After we have completed local testing, we can commit and push. Any pushed commits to the remote repo will trigue running through the Github Actions again, and lead to an update of the website. This allows for continuous package development. Note that if we are confident about the new code and instructions, we can commit and push without local testing, after running devtools::document(), other the results generated from that function in the man folder are commited. Results from check and build_site do not change contents that would be pushed to remote.

# Update the .Rd files if .R files have been modified. 
devtools::document()
# locally building site
pkgdown::build_site()

Installing the Package.

Once the repository is on github, can use devtools::install_github to install the latest version of the package locally.

# remove.packages("PkgTestR")
devtools::install_github("FanWangEcon/PkgTestR")