08b_pkg_functions.qmd

---
title: "Packaging functionality"
---

## R Package Structure

Used to share functionality with the R community

-   Useful **conventions**

-   Useful **software development tools**

-   Easy **publishing** through GitHub

## R Package conventions:

-   **metadata**: in the **`DESCRIPTION` file**

-   **functions** in **`.R` scripts** in the **`R/` folder**

-   **tests** in the **`tests/` folder**

-   **Documentation:**

    -   *functions* using **Roxygen notation**
    -   *workflows* using **`.Rmd` documents** in the **`vignettes/`** folder

## Software Engineering approach

Following conventions allows us to **make use of automated tools** for:

-   **Checking** and **testing code**

-   **Producing documentation** for code and workflows

-   **Publishing, distributing** and **citing** code



## Anatomy of an R package

Let's use [`pkgreviewr`](https://github.com/ropensci-org/pkgreviewr), a package I authored to help automate some aspects of the rOpenSci review process, as an example to examine some elements of what makes a package:

## `DESCRIPTION` file

Capture metadata around the package - Functionality description - Creators - License

```         
Package: pkgreviewr
Type: Package
Title: rOpenSci package review project template
Version: 0.1.1
Authors@R: c(person("Anna", "Krystalli", email = "annakrystalli@googlemail.com",
                  role = c("aut", "cre")),
             person("Maëlle", "Salmon", email = "maelle.salmon@yahoo.se", role = "aut"))
Description: Creates files and collects materials necessary to complete an rOpenSci package review. 
    Review files are prepopulated with review package specific metadata. Review package source code is
    also cloned for local testing and inspection.
License: GPL-3 + file LICENSE
URL: https://github.com/ropenscilabs/pkgreviewr
BugReports: https://github.com/ropenscilabs/pkgreviewr/issues
Encoding: UTF-8
LazyData: true
Imports:
    devtools,
    git2r (>= 0.23.0),
    usethis (>= 1.2.0),
    here,
    reprex,
    gh,
    base64enc,
    whoami,
    magrittr,
    covr,
    goodpractice,
    assertthat,
    httr,
    rstudioapi,
    clipr,
    clisymbols,
    crayon,
    dplyr,
    glue,
    fs,
    urltools,
    shiny
Suggests: 
    testthat,
    mockery,
    knitr,
    rmarkdown
RoxygenNote: 6.1.1
Remotes: 
    ropensci/git2r
VignetteBuilder: knitr
Roxygen: list(markdown = TRUE)
```

### citation

```{r}
citation("pkgreviewr")
```

## Dependency management

It’s the job of the DESCRIPTION to **list the packages that your package needs to work**.

```         
Imports:
    devtools,
    git2r (>= 0.23.0),
    usethis (>= 1.2.0),
    here,
    reprex,
    gh,
    base64enc,
    whoami,
    magrittr,
    covr,
    goodpractice,
    assertthat,
    httr,
    rstudioapi,
    clipr,
    clisymbols,
    crayon,
    dplyr,
    glue,
    fs,
    urltools,
    shiny
```

Imports are necessary dependencies for the functions in your package to work

```         
Suggests: 
    testthat,
    mockery,
    knitr,
    rmarkdown
```

Suggests are dependencies that are not necessary for the functions in your package but might be neccessary to run all the vignettes or tests in your package

## `R/`

-   Keep all functions in R scripts in `R/` folder

```         
.
├── github.R
├── pkgreview.R
├── pkgreviewr-package.R
├── render-templates.R
├── rmd-utils.R
├── style.R
└── utils.R

0 directories, 7 files
```

### example function script

Create a new function `.R` file in the `R/` folder

```{r, eval=FALSE}
library(usethis)
use_r("add")
```

```         
R
└── add.R

0 directories, 1 files
```

## Document functions with `Roxygen`

-   Document functions with **Roxygen** notation
-   Automatically create help files on build

```{r}
#' Add together two numbers.
#'
#' @param x A number.
#' @param y A number.
#' @return The sum of x and y.
#' @examples
#' add(1, 1)
#' add(10, 1)
add <- function(x, y) {
  x + y
}
```

## `tests/`

Tests provide confidence in what the code is doing.

*Contents of `pkgreviewr` test folder*

```         
.
├── testthat
│   ├── setup.R
│   ├── test-create-pkgreview.R
│   ├── test-gh-calls.R
│   ├── test-render-templates.R
│   └── test-setup.R
└── testthat.R

1 directory, 6 files
```

### Example test

```{r, eval=FALSE}
use_test("add")
```

```         
tests
├── testthat
│   ├── test-add.R
└── testthat.R
```

```{r, eval=FALSE}
test_that("add works", {
  expect_equal(add(2, 2), 4)
})
```

The **R package structure** can help with providing a logical organisation of files, by **providing a set of standard locations for certain types of files**.

To work with packages in RStudio we use the **Build pane**, which includes a variety of tools for **building, documenting and testing packages**. This will appear if Rstudio recognises the project as an R package.

![](assets/build-panel.png)



# :computer: Create your first package


::: {.callout-tip collapse="true"}
## Creating a new package locally

To create a new package, you can follow the steps for creating any new project, but this time select **`R package`** instead of `New Project` and call your new package `mypackage`.

::: {.alert .alert-info}
<strong>File \> New Project... \> New Directory \> R package \> mypackage </strong>
:::

Otherwise, you can **use function `usethis::create_package("mypackage")`** to create a new package. The argument we provide is the path to here we want our new package created, the **last element being the package name**. Note that there are [restrictions on what characters can be used in a package name](https://r-pkgs.org/workflows101.html#naming).
:::


## Copy **`mypackage`** Project

To make things easier, I've gone ahead and **set up the basic contents of a new package in project `mypackage`.**

In our shared space click on the {{< fa plus-square >}} copy button next to the **mypackage** Project to copy it.

![](assets/copy-pkgdev-proj.png)

Your new project should have the following structure.

```         
.
├── DESCRIPTION
├── NAMESPACE
├── R
└── project.Rproj
```





## Initialise git and commit files.

Let's **also configure git again, initialise our project as a git repository and commit our initial files**. We'll need to configure git again as this is a new Posit Cloud project.



```{r, eval=FALSE}
# configure git
usethis::use_git_config(
  user.name = "Jane",
  user.email = "jane@example.org"
)
# intialise git and commit
usethis::use_git()
```


```         
✔ Setting active project to '/cloud/project/mypackage'
✔ Initialising Git repo
✔ Adding '.Rhistory', '.Rdata', '.httr-oauth', '.DS_Store', '.quarto' to '.gitignore'
There are 5 uncommitted files:
* '.gitignore'
* '.Rbuildignore'
* 'DESCRIPTION'
* 'mypackage.Rproj'
* 'NAMESPACE'
Is it ok to commit them?

1: No way
2: Nope
3: I agree

Selection: 3
✔ Adding files
✔ Making a commit with message 'Initial commit'
```

# :vertical_traffic_light: Functions in the **`R/`** dir

## Create function script and first function

Let's create a script and write our first function:

```{r, eval=FALSE}
usethis::use_r("hello")
```

```         
• Modify 'R/hello.R'
```

![](assets/r_hello.png)

In the opened `hello.R` script, let's write our first function:

```{r}
#| eval: false
hello <- function() {
  print("Hello, world!")
}
```

It's a function that takes no arguments and prints `Hello, world!` to the console when called.

## Install package.

You can install a package locally from it's source code with function `devtools::install()`

```{r, eval=FALSE}
devtools::install()
```

```         
── R CMD build ────────────────────────────────────────────
✔  checking for file ‘/cloud/project/mypackage/DESCRIPTION’ ...
─  preparing ‘mypackage’:
✔  checking DESCRIPTION meta-information
─  checking for LF line-endings in source and make files and shell scripts
─  checking for empty or unneeded directories
─  building ‘mypackage_0.0.0.9000.tar.gz’
   Warning: invalid uid value replaced by that for user 'nobody'
   
Running /opt/R/4.3.3/lib/R/bin/R CMD INSTALL \
  /tmp/RtmpVJXWXx/mypackage_0.0.0.9000.tar.gz \
  --install-tests 
* installing to library ‘/cloud/lib/x86_64-pc-linux-gnu-library/4.3’
* installing *source* package ‘mypackage’ ...
** using staged installation
** R
** byte-compile and prepare package for lazy loading
** help
*** installing help indices
** building package indices
** testing if installed package can be loaded from temporary location
** testing if installed package can be loaded from final location
** testing if installed package keeps a record of temporary installation path
* DONE (mypackage)
```

Or click on **{{< fa hammer >}} Install** on the Build panel

![](assets/rsc_build-package.png)


## Load library

You can now load it like any other package...

```{r, eval=FALSE}
library("mypackage")
```

## Try using function

Let's try using our function

```{r}
#| error: true
hello()
```

Oooops? Our function doesn't seem to be available! :thinking:


```{r}
#| echo: false
hello <- function() {
  print("Hello, world!")
}
```


Let's try something else:

```{r}
#| eval: false
mypackage:::hello()
```

```{r}
#| echo: false
hello()
```


```{r, echo=FALSE}
rm(hello)
```

So what's happened here? 

Although the package contains our function, **we have not exported it** to make it available to a user. 

Currently **it is contained as an internal function**. Hence **we can access it with the notation for internal functions (`:::`)** but not directly when we load the package!

To export the function, **we will need to add a tag to tell R to do so** using a special documentation notation called **Roxygen**!

------------------------------------------------------------------------

# :vertical_traffic_light: Add Roxygen documentation

[`Roxygen2`](http://r-pkgs.had.co.nz/man.html) allows you to write specially-structured comments preceding each function definition to document:

-   a description of what it does
-   the inputs and outputs
-   an example of how to use it
-   **whether to export the function or treat it as internal**

These are **processed automatically to produce `.Rd` help files** for your functions and **control which functions are exported to the package `NAMESPACE`**.

Let's document our example function.

## Insert Roxygen skeleton

You can **insert a Roxygen skeleton** by placing the cursor within a function and clicking:

> **Code \> Insert Roxygen Skeleton**

```{r, eval=FALSE}
#' Title
#'
#' @return
#' @export
#'
#' @examples
hello <- function() {
  print("Hello, world!")
}
```

## Roxygen basics

-   `roxygen` notation indicated by **beginning line with `#'`**.

-   **First line** will be the **title** for the function.

-   After title, include a blank `#'` line and then write a **longer description.**

-   `@param argument_name` **description of the argument.**

-   `@return` description of **what the function returns.**

-   `@export` tells `Roxygen2` to **add this function to the `NAMESPACE`** file, so that it will be **accessible to users.**

-   `@examples` allows to include example of how to use a function

## Complete Roxygen documentation

```{r}
#' Hello World!
#'
#' Print hello greeting
#' @return prints hello greeting to console
#' @export
#'
#' @examples
#' hello()
hello <- function() {
  print("Hello, world!")
}
```

## Autogenerate documentation

To auto-generate documentation:
- **use function `devtools::document()`** or 
- click on **{{< fa cog >}} More > Document**

![](assets/build-document.png)
```
ℹ Updating mypackage documentation
ℹ Loading mypackage
Writing 'hello.Rd'
Writing 'NAMESPACE'
Documentation completed
```

This re-creates a `hello.Rd` help file in the `man/` folder and populates the `NAMESPACE` with our functions


::: callout-tip

### Configure Build Tools

We can also configure our Build Tools to **run `devtools::document()` every time we re-install the package**. 

To do so, we click on the **Build \> Configure Build Tools > Generate documentation with Roxygen >  [Configure...](){.btn .btn-outline-primary}** and then tick the **Install and Restart** box.

![](assets/build-doc_config.png)


Now clicking {{< fa hammer >}} **Install** in the Build panel will also build your docs in the `man/` folder for you.


:::

Now that the documentation has been built, the help file for our `hello()` function is now available!

![](assets/roxygen-done.png)


# :vertical_traffic_light: Personalise function

Let's go a step further and **customise our function so that the greeting is from ourselves!**

```{r, tidy="styler"}
#' Hello World!
#'
#' Print hello greeting
#' @return prints hello greeting to console from me
#' @export
#'
#' @examples
#' hello()
hello <- function() {
  print("Hello, world from Anna")
}
```

## Add some fun!

Programming is most useful for having fun. So **let's make our function extra fun!**

We'll use package `cowsay`

```{r, eval=FALSE}
install.packages("cowsay")
```

which has a single function `say`, which does this...

```{r}
cowsay::say("Say whaaaaaat?", by = "shark")
```

:stuck_out_tongue_winking_eye:

So **let's create a function that randomly chooses one of the animals** available in `cowsay` **to deliver the greeting**, and also **allow the user to customise who the recipient of the greeting is**.

```{r}
#' Hello World!
#'
#' Print personalised hello greeting from me.
#'
#' @param name character string. Your name!
#'
#' @return prints hello greeting to console
#' @export
#'
#' @examples
#' hello()
#' hello("Lucy Elen")
hello <- function(name = NULL) {
    
    # create greeting
    if (is.null(name)){name <- "world"}
    greeting <- paste("Hello", name, "from Anna!")

    # randomly sample an animal
    animal_names <- names(cowsay::animals)
    i <- sample(1:length(animal_names), 1)

    cowsay::say(greeting, animal_names[i])
}
```

Document, Install and restart to load our changes

```{r}
hello("y'all")
```

Let's **commit our current files and changes.**

# :vertical_traffic_light: Check package integrity

An **important part of the package development process is `R CMD check`**. `R CMD check` automatically **checks your code** and can **automatically detects many common problems** that we'd otherwise discover the hard way.

To check our package, we can:

-   use `devtools::check()`

-   press Ctrl/Cmd + Shift + E

-   click on the :check:**Check** tab in the **Build** panel.

This:

-   **Ensures that the documentation is up-to-date** by running `devtools::document()`.

-   **Bundles the package** before checking it.

More info on [checks](http://r-pkgs.had.co.nz/check.html) here.

<br>

Both these run `R CMD check` which **return three types of messages**:

-   **ERRORs**: Severe problems that you should fix regardless of whether or not you’re submitting to CRAN.

-   **WARNINGs**: Likely problems that you must fix if you’re planning to submit to CRAN (and a good idea to look into even if you’re not).

-   **NOTEs**: Mild problems. If you are submitting to CRAN, you should strive to eliminate all NOTEs, even if they are false positives.

Let's **Check** our package:

Click on the **Check** button (:clipboard: :white_check_mark:)

```         
   
── R CMD check results ────────────────────────────── mypackage 0.0.0.9000  ────
Duration: 8.4s

❯ checking DESCRIPTION meta-information ... WARNING
  Non-standard license specification:
    What license is it under?
  Standardizable: FALSE

❯ checking dependencies in R code ... WARNING
  '::' or ':::' import not declared from: ‘cowsay’

0 errors ✔ | 2 warnings ✖ | 0 notes ✔
Error: R CMD check found WARNINGs
Execution halted

Exited with status 1.
```

Aha, so our checks have thrown up some warnings! First, it's telling us we haven't added a `LICENSE`. It's also telling us that we have a dependency (import) from package `cowsay` which we haven't documented in the `DESCRIPTION` file. `usethis` to the rescue!

## :vertical_traffic_light: Add dependencies

Add `cowsay` as a dependency.

```{r, eval=FALSE}
usethis::use_package("cowsay")
```

```         
✔ Setting active project to '/cloud/project'
✔ Adding 'cowsay' to Imports field in DESCRIPTION
• Refer to functions with `cowsay::fun()`
```

## Add License

```{r, eval = FALSE}
usethis::use_mit_license("Anna Krystalli")
```

```
✔ Adding 'MIT + file LICENSE' to License
✔ Writing 'LICENSE'
✔ Writing 'LICENSE.md'
✔ Adding '^LICENSE\\.md$' to '.Rbuildignore'
```

![](assets/clear-checks.png)

Check again...All should be good!

```         
── R CMD check results ─ mypackage 0.0.0.9000 ────
Duration: 8s

0 errors ✔ | 0 warnings ✔ | 0 notes ✔

R CMD check succeeded
```

#### {{< fa square-check >}} Let's commit our current files and changes.

------------------------------------------------------------------------

# :vertical_traffic_light: Add Test

**Testing is a vital part of package development**. It ensures that our code does what you want it to do.

Once you're set up with a testing framework, the workflow is simple:

1.  Modify your code or tests.

2.  Test your package with Ctrl/Cmd + Shift + T or `devtools::test()`.

3.  Repeat until all tests pass.

## Create test file

To create a new test file (and the testing framework if required), use function `usethis::use_test()`. It's good practice to name the test files after the `.R` files containing the functions being tested.

```{r, eval=FALSE}
usethis::use_test("hello")
```

``` r
✔ Adding 'testthat' to Suggests field in DESCRIPTION
✔ Adding '3' to Config/testthat/edition
✔ Creating 'tests/testthat/'
✔ Writing 'tests/testthat.R'
✔ Writing 'tests/testthat/test-hello.R'
• Modify 'tests/testthat/test-hello.R'
```

This just created the following folders and files

```         
tests
├── testthat
│   └── test-hello.R
└── testthat.R

1 directory, 2 files
```

It also added `testthat` to the suggested packages in the `DESCRIPTION` file.

```         
Suggests: 
    testthat
```

That's because you don't need test that to run the functions in `mypackage`, but you do if you want to run the tests.

When the tests are run (either through running `devtools::test()`, clicking on **More \> Test Package** in the Build panel or `Cmd/Ctrl + Shift + T`), the code in each test script in directory `testthat` is run.

## **`test-hello.R`**

Let's load the library so we can explore the `testthat` testing framework

```{r, message=FALSE}
library(testthat)
```

```{r}
test_that("multiplication works", {
  expect_equal(2 * 2, 4)
})

```

If the test doesn't pass it throws an error

```{r, error=TRUE}
test_that("multiplication works", {
  expect_equal(2 * 2, 5)
})

```

## Write test

Let's **write a simple test to check that we are getting an expected output type**. 

One way to **test the consistency of the output of a function**, especially one that may output messages, warnings etc, like ours does, is to **use `expect_snapshot()`**. 

This function takes a snapshot of the output of a function and compares it to the snapshot the next time the test is run.

Now, because our functions has a random element to it (selecting a random animal), we need to **set the seed** to ensure that the output is consistent across runs.

So let'sr eplace the placeholder testing code and add a snapshot test each for:

- the function's default behaviour.
- the function's behaviour when a `name` is provided.

```{r}
#| eval: false
test_that("hello works", {
  set.seed(1)
  expect_snapshot(hello())
  expect_snapshot(hello("Lucy Elen"))
})
```

Now let's test our package

```{r, eval=FALSE}
devtools::test()
```

The first time we run our tests, `testthat` will create a snapshot of the output of our function and warns us of that. The next time we run the tests, it will compare the output of the function to the snapshot and let us know if it has changed.


If you run your tests twice you should have success!

```         
==> devtools::test()

ℹ Testing mypackage
✔ | F W  S  OK | Context
✔ |          2 | hello                            

══ Results ═══════════════════════════════════════
[ FAIL 0 | WARN 0 | SKIP 0 | PASS 2 ]
```

#### {{< fa square-check >}} Let's commit our current files and changes.

# :vertical_traffic_light: Create README

The final document you will need for your package is a `README`.

```{r, eval=FALSE}
usethis::use_readme_rmd()
```

```         
✔ Setting active project to '/cloud/project'
✔ Writing 'README.Rmd'
✔ Adding '^README\\.Rmd$' to '.Rbuildignore'
• Modify 'README.Rmd'
• Update 'README.Rmd' to include installation instructions.
✔ Writing '.git/hooks/pre-commit'
```

`.Rmd` documents are the predecessors to Quarto documents and allow us to run R code in our GitHub README.

Because it's an `.Rmd` but GitHub can only display an `md` document as it's landing page, this is a **special `.Rmd` that renders to a markdown document rather than `html`**. 

The function adds a check to `.git` to ensure you commit an up to date version on the `md` when you commit changes to the `.Rmd`.

Important elements of a README to include:

- **Installation instructions:** In our case we will be distributing our package via GitHub, so we will include instructions on how to install the package from GitHub using `remotes::install_github("<yourgithubusername>/mypackage")`.
- **Description:** A brief description of what the package does.
- **Examples:** A few simple examples of how to use the package.

Complete the README. Here's what mine looks like:


````
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# mypackage

<!-- badges: start -->
<!-- badges: end -->

The goal of mypackage is to print a personalised greeting from me!

## Installation

You can install the development version of mypackage from GitHub with:

``` r
# install.packages("remotes")
remotes::install_github("annakrystalli/mypackage")
```

## Example

This is a basic example which shows you how to print a generic greeting:

```{{r example}}
library(mypackage)
## basic example code
hello()
```

This is a basic example which shows you how to print a personalised greeting:

```{{r}}
hello(name = "Lucy Elen")
```

````

and renders to the following when **Knit**

![](assets/rendered-pkg-readme.png)


#### {{< fa square-check >}} Let's commit our current files and changes.

# :vertical_traffic_light: Complete package metadata

Let's head to the `DESCRIPTION` file and complete the details.

## Authors

First let's complete the authors. 

Remove the current author and maintainer lines and replace it with the following line:

```         
Authors@R: person("First", "Last", email = "first.last@example.com", role = c("aut", "cre"))
```

completed with your own details

## Add a title and description

**Complete the title and description fields with appropriate details.**

If you want to form a paragraph of text, make sure do indent the hanging lines by 4 spaces (one tab). And make sure that your Description field **ends in a full-stop**.

## Add a date

Use today's date in ISO format, ie **`r config::get('pkgdev_date_iso')`**. This will populate a citation entry for us.

### Completed `DESCRIPTION`

The complete `DESCRIPTION` file should look something like this:

```         
Package: mypackage
Title: Customised greetings from me!
Version: 0.0.0.9000
Authors@R: person("Anna", "Krystalli", 
  email = "annakrystalli@googlemail.com", 
  role = c("aut", "cre"))
Description: Prints a customised greeting from myself,
  delivered by a friend.
License: MIT + file LICENSE
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.3.1
Imports: 
    cowsay
Suggests: 
    testthat (>= 3.0.0)
Config/testthat/edition: 3
Date: 2024-04-19
```

Check your package. If all is good, document, install and restart!

Now, check you're package's citation:

```{r, eval=FALSE}
citation("mypackage")
```

```         
To cite package ‘mypackage’ in publications use:

  Krystalli A (2024). _mypackage: Customised
  greetings from me!_. R package version 0.0.0.9000.

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {mypackage: Customised greetings from me!},
    author = {Anna Krystalli},
    year = {2024},
    note = {R package version 0.0.0.9000},
  }
```

#### {{< fa square-check >}} Let's commit our current files and changes.

## Create GitHub repo and push to GitHub

Now you have everything you need to share your package on GitHub so create a GitHub repository and push our local content up to it.

_You will need to set your PAT through `credentials` again in this new project._

```{r, eval=FALSE}
# configure GitHub PAT credentials
credentials::set_github_pat()

# create GitHub repository and push
usethis::use_github(protocol = "https")
```

```
✔ Creating GitHub repository 'annakrystalli/mypackage'
✔ Setting remote 'origin' to 'https://github.com/annakrystalli/mypackage.git'
✔ Adding 'https://github.com/annakrystalli/mypackage' to URL
✔ Adding 'https://github.com/annakrystalli/mypackage/issues' to BugReports
There is 1 uncommitted file:
* 'DESCRIPTION'
Is it ok to commit it?

1: Absolutely
2: Not now
3: No way

Selection: 1
✔ 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/annakrystalli/mypackage'
```

This will **create a new GitHub repository** and **push the contents of your package to it**. 

Before doing so it also adds details of our remote to the `DESCRIPTION` file and commits it.

Now anyone will be able to install my package using, eg:

```{r, eval=FALSE}
remotes::install_github("annakrystalli/mypackage")
```

Add the link to your package repo in the [hackpad](`r config::get("hackpad_url")`). 

**Visit someone else's package repo, follow the instructions to install, load it and receive a personalised greeting from the author!**

# Setup Continuous Integration with GitHub Actions

## Continuous Integration Background

Continuous integration (CI) is the practice of automating the integration of code changes from multiple contributors into a single software project. Automated tools are used to assert the new code’s correctness before integration. In our case this is what are tests are for. And GitHub Actions allows us to do this all within GitHub!

Once the appropriate CI workflow is set up, **it will automatically run our tests for us every time we push new code to GitHub or when a new pull request is made**. This way we can (try to) **ensure we don't merge new code into our code base that introduces bugs** (causing our tests to fail). 

**Obviously, our ability to screen for breaking changes is only as good as our tests!** But at least we can get GitHub to run our tests for us!

## Setup R CMD CHECK GitHub Action

To run CI workflows through GitHub Actions, we specify the actions or jobs we want the CI system in a `.yaml` file that lives in `.github/workflows/` folder in the root of our package/project. 

This can be quite complicated for complex projects as you have to **effectively specify instructions for GitHub to recreate a computational environment to run the tests in**. The `.yaml` format can also be fiddly, with indents having special meaning. 

However for a standard R project like ours, there is a `usethis` functions that can create and appropriate `.yaml` for us that works right out of the box!

Let's try it out:

```{r, eval=FALSE}
usethis::use_github_action("check-standard")
```

```         
✔ Creating '.github/'
✔ Adding '^\\.github$' to '.Rbuildignore'
✔ Adding '*.html' to '.github/.gitignore'
✔ Creating '.github/workflows/'
✔ Saving 'r-lib/actions/examples/check-standard.yaml@v2' to '.github/workflows/R-CMD-check.yaml'
• Learn more at <https://github.com/r-lib/actions/blob/v2/examples/README.md>.
✔ Adding R-CMD-check badge to 'README.Rmd'
• Re-knit 'README.Rmd' with `devtools::build_readme()`
```

This workflow installs the latest release of R on macOS and runs R CMD check via the `rcmdcheck` package.

```{yaml, eval=FALSE, code=readLines("https://raw.githubusercontent.com/r-lib/actions/master/examples/check-release.yaml"), results="asis"}

```

-   Re-knit `README.Rmd` to include GitHub Actions badge.
-   Commit the whole `.github` folder as well as `README.Rmd` & `README.md`
-   Push to GitHub

#### {{< fa square-check >}} Let's commit our current files and changes and push to GitHub.
_You'll need your GitHub PAT again_


This will activate the `R-CMD-CHECK` GitHub Actions workflow and begin running it.

To see details and the status of GitHub Actions workflows, click on the {{< fa play-circle >}} **Actions** tab and select the workflow to view. 

![](assets/ga-actions-running.png)

If our test passes, the run will show as successful :white_check_mark: and so will the badge in our README. If there are any problems, error messages will appear in the logs.


![](assets/ga-r-cmd-check-success.png)



# :vertical_traffic_light: Create documentation site

While the README is a great first step for documenting your package, there is an easy way to create a full website which makes the documentation of each exported function avaliable online and where you could include additional, more detailed vignettes.

You can use package `pkgdown` to create an online site for your documentation. It effectively recycles the documentation you have already created for your functions, information in your README and DESCRIPTION file and presents it in a standardised website form.

Let's set up our package with such a site.

```{r, eval=FALSE}
usethis::use_pkgdown()
```

```
✔ Setting active project to '/cloud/project'
✔ Adding '^_pkgdown\\.yml$', '^docs$', '^pkgdown$' to '.Rbuildignore'
✔ Adding 'docs' to '.gitignore'
✔ Writing '_pkgdown.yml'
• Modify '_pkgdown.yml'
```

And now let's build it the site.

```{r}
#| eval: false
pkgdown::build_site()
```

```         
-- Installing package into temporary library --------------
== Building pkgdown site =======================================================
Reading from: '/cloud/project'
Writing to:   '/cloud/project/docs'
-- Initialising site -----------------------------------------------------------
Copying '../lib/x86_64-pc-linux-gnu-library/4.3/pkgdown/BS5/assets/link.svg' to 'link.svg'
Copying '../lib/x86_64-pc-linux-gnu-library/4.3/pkgdown/BS5/assets/pkgdown.js' to 'pkgdown.js'
-- Building home ---------------------------------------------------------------
Writing 'authors.html'
Reading 'LICENSE.md'
Writing 'LICENSE.html'
Writing 'LICENSE-text.html'
Writing '404.html'
-- Building function reference -------------------------------------------------
Writing 'reference/index.html'
Reading 'man/hello.Rd'
Writing 'reference/hello.html'
Writing 'sitemap.xml'
-- Building search index -------------------------------------------------------
== DONE ========================================================================
-- Previewing site ----------------------------------------
```

This creates html documentation for our package in the `docs/` folder and presents you with a preview to the site.

::: callout-caution
_Note the Preview might be blocked in Posit Cloud and when you click to allow a pop might still look a bit wonky!_
:::

Now, you could push this `docs/` folder to GitHub and serve through GitHub Pages, but **you would need to rebuild, commit and push these docs any time there was a change in the package documentation**.

Instead what we could do is **get our CI system (GitHub Actions) to build our docs for us automatically every time there is a push or pull request to our repository!!** So let's try this approach!

Indeed that's what the `usethis::use_pkgdown()` workflow expects so **has already told git to ignore local copies of the docs in our `docs/` folder by adding `docs/*` to our `.gitignore` file**. This way, we can still build and preview our site locally if we want but we won't commit it to our`master` or `main` branch.

Then, we can deploy another GitHub Actions template, provided by `usethis` that again will work right out the box!

```{r, eval=FALSE}
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>.
```

This creates another file in `.github/workflows/` called `pkgdown.yaml`. The workflow installs the package, building all documentation, installs `pkgdown` and uses it to build the site. It then commits the build site to a separate `gh-pages` site.

```{r, eval=FALSE, code=readLines("https://raw.githubusercontent.com/r-lib/actions/master/examples/pkgdown.yaml"), results="asis"}

```

Commit the file and push it up to GitHub to activate. Once the workflow completes successfully, you will find the html for your documentation for you site in a new `gh-pages` branch!

#### {{< fa square-check >}} Let's commit our current files and changes.

## Enable `gh-pages`

To **serve our new site**, we need to **enable GitHub Pages and set the source directory to the root of the `gh-pages` branch.**

We can use function `usethis::use_github_pages()` to do so.

```{r}
#| eval: false

usethis::use_github_pages()
```

```
✔ Activating GitHub Pages for 'annakrystalli/mypackage'
✔ GitHub Pages is publishing from:
• URL: 'http://annakrystalli.me/mypackage/'
• Branch: 'gh-pages'
• Path: '/'
```



To check our Github Pages settings we go to {{< fa cog >}} **Settings** and click on **Pages** on the navigation bar on the left. 

Also Double Check that **Enforce HTTPS is checked at the bottom**.

![](assets/enforce-https.png)

## Check site

You'll find your site at the URL provided in the GitHub Pages settings. 

![](assets/mypackage-site.png)

You can add it to your repo details by clicking on the **{{< fa cog >}} in the About side panel** and ticking **Use your Github Pages website**.

![](assets/add-pages-to-about.png)


Check out my complete example [here](https://github.com/annakrystalli/mypackage-demo)