Automated Deployment of a Package Website

Gareth Burns

Exploristics

Introduction

This presentation is learn how to carry out a the automated deployment of an R package website when files are changed to GitHub. This code deployment pipeline can be considered as generic to apply to the following other use-cases:

  • Deploying a shinyapp

  • Deploying a dashboard

  • Updating a datasource

Learning Objectives

By the end of this presentation

  • Become familiar with a pkgdown website structure
  • Learn which package files are related to which section of website
  • Overview of an automated CI/CD pipeline
  • How to create a basic Code Build pipeline
  • Common errors in building a Code Build pipeline

Why create an package website?

Centralized Documentation: pkgdown provides a centralized location for all your package’s documentation, vignettes, and function references. This makes it easier for users to find and navigate through information about your package.

Promotion and Visibility: Having a dedicated website increases the visibility of your package. Users can discover it through web searches, and having clear documentation can attract more users and contributors.

Automatic Generation: pkgdown automates the process of creating a website from your package documentation. It extracts information from your package’s metadata and generates web pages, reducing manual effort.

Why create an package website?

Professional Appearance: The generated website has a professional appearance with consistent styling and navigation, which enhances the overall user experience.

User Engagement: A well-organized and informative website encourages user engagement. Users can quickly find the information they need, understand how to use your package effectively, and contribute to its development.

How to create a package website

library(pkgdown)
library(usethis)

How to create a package website

library(pkgdown)
library(usethis)

# Run once to configure package to use pkgdown
usethis::use_pkgdown()

How to create a package website

library(pkgdown)
library(usethis)

# Run once to configure package to use pkgdown
usethis::use_pkgdown()
# Run to build the website
pkgdown::build_site()

How to create a package website

library(pkgdown)
library(usethis)

# Run once to configure package to use pkgdown
usethis::use_pkgdown()
# Run to build the website
pkgdown::build_site()

Easy eh?

Pre-requites

For this to work seamlessly you need to have developed an R-package in a standard format, adhering to best practice and coding conventions…but when you do this you have access to a host of tools and resources!

  • Readme file

  • Description file

  • Code documentation (roxygen2)

  • Vignettes

  • News file (Change log)

Automated deployment workflow

flowchart LR
    subgraph Automated Pipeline
      direction LR
      A(Write Code)<-. code review .-> B[Github]
      B -. change detected .-> C(Recompile html)
      C -. deploy files .-> D{Website}
      click B href "https://github.com/GABurns/ExploristicsTheme" _blank
      click D href "http://exploristic.theme.s3-website-eu-west-1.amazonaws.com/index.html" _blank
    end

How can this go wrong?

  1. But it works on my machine…

    1. Missing dependencies1

    2. Change of permissions

  2. Syntax errors

  3. Files in wrong location (relative position)

Took failed 24 builds before first success!

How to setup AWS CodeBuild

flowchart TB
  subgraph AWS CodeBuild
      direction LR
      A{Code Source} --> B(Webhook)
      B --> C(Filter)
      C --> D[Build Environment]
      D -.->|BuildSpec| E{{Install}}
      E -.- F{{Pre-build}}
      F -.- G{{Build}}
      G -.-> H{{Deploy}}
    end

Resources