Package development with pkgdown

Building a website for R software packages
module 3
week 6
packages
pkgdown
Author
Affiliation

Boyi Guo

Department of Biostatistics, Johns Hopkins

Published

November 30, 2023

Pre-lecture materials

Read ahead

Read ahead

Before class, you can prepare by reading the following materials:

  1. https://pkgdown.r-lib.org/articles/pkgdown.html

Prerequisites

Before starting you must install the additional package:

  • pkgdown - the R package that helps you to build a package website with little efforts
  • usethis - an automation package that simplifies project creation and setup

You can do this by calling

install.packages(c("usethis", "pkgdown"))

or use the “Install Packages…” option from the “Tools” menu in RStudio.

You also need to have a GitHub account and set up your access from your local computer to GitHub.com. If you forget, please re-visit your previous lecture.

Acknowledgements

Material for this lecture was borrowed and adopted from

Learning objectives

Learning objectives

At the end of this lesson you will:

  • build a website for your package
  • deploy your website on GitHub

Why do we want a website for our packages?

The primary reason to make a website for our packages is to make it more popular. Having a publicly available website is similar to create a home for your package where people know where to find you package. Reciprocally, you can tell others a more stable address, i.e. your website link, to find your package.

Moreover, compare to the default reference manual, a website provides more interactability and accessibility. It is easier to navigate through different functions via clickable links or to follow through a vignette with a table of content in a point-and-click system. A website is also a more integrative resources where it keeps not only the reference manual and vignettes, but also change-log and development history. All of these makes it easier for the users to understand and appreciate your work.

In addition, a website is a great place to market yourself and show your personality. Different from a GitHub repo which follows the same template, a website is the place where you have more freedom to showcase your creativity. You can customize the websites and have more space to explain.

What is pkgdown?

While creating a website can be a daunting task for people who don’t have extensive web programming experience, pkgdown provides a shortcut. pkgdown can automatically generate a website of an R package, containing references to the enclosed function, different vignettes if exists, within two lines of code (slight exaggeration). It also helps to deploy the website to GitHub server. Amazingly, pkgdown facilitates automatic updates of the website following any changes made to the package that are pushed to GitHub.

How to use pkgdown?

Live demonstration

While the pkgdown website provides a comprehensive walkthrough for those who set up their GitHub access using personal access token, it is slightly tricky for those whose access is set up with SSH. During this lecture, we live demonstrate how to deploy the website, specifically for SSH GitHub access.

Did you try pkgdown::deploy_to_branch()?

If you run into problem when running usethis::use_pkgdown_github_pages() and get stuck, you should try to understand what the function does by reading its manual ?usethis::use_pkgdown_github_pages(). Is it possible to create the necessary gh_pages using pkgdown::deploy_to_branch()? Don’t forget to set up the GitHub Action by calling usethis::use_github_action("pkgdown"). Now you should be able to find access your website via github_account_name.github.io/pkg_name

Website customization

There are a lot of customization possible. Nevertheless, there is no point-and-click system for it. You need to manually edit _pkgdown.yml following certain syntax. Please refer to https://pkgdown.r-lib.org/articles/customise.html.

Summary

In this lecture, we

  • introduce the package pkgdown that automates website
  • demonstrate how to use pkgdown to create website for an R package

Additional Resources

Tip