Travis CI and pkgdown: Who or what is it?

Summary

In this tutorial we will discuss:

What Travis CI is and how it works
We will demonstrate two methods for adding Travis CI to a GitHub repo that does not contain a package - so in our case our repo contains an .rmd and we want to test if it renders
1. We will show how this process can be done manually, (this helps demonstrate what other packages that make this process faster actually do)
2. We will show a shorter version of the process using the usethis package
We will discuss what pkgdown is and how to use it
We will provide additional references including tutorials for adding Travis to a repo that does contain a package

Travis CI

What is Travis? Is this a person? Why is everyone talking about Travis???
Have you ever heard someone say that they used Travis to test their package? Who is this amazing code guru?!

Allow me to introduce you

Turns out Travis is not a person after all, although there is a pretty awesome mascot that looks like a person.

Check here if you want to know more about why Travis is called Travis

What Travis CI really is…

This was actually a company in Berlin, Germany that was founded in 2001 that was recently acquired by Idera.

It is really a Continuous Integration and Continuous Deployment platform.

What is Continuous Integration?

Continuous Integration (CI) is “the practice of merging all developer’s copies to a shared mainline several times a day”

*like pushing your code to the master branch on GitHub regularly

How Continuous Integration works?

Typically programmers build their code and complete tests on their code before they commit

Build meaning: “the process of converting the human-readable source artifacts into machine-readable artifacts” according to users on stackoverflow
- rendering
- generating reports
- compilation etc.
```
           ***Travis helps automate this process***
```

What is Continuous Delivery / Deployment?

Basically you are getting your code ready to be deployed at all times - ie it can build without issues.

Travis-CI can directly link to GitHub - thus it can also deliver or deploy websites of your code through GitHub/GitHub pages. We will talk more about that later.

https://blog.travis-ci.com/2019-05-30-setting-up-a-ci-cd-process-on-GitHub

How Travis works

ref

Does Travis also work on private repos?

Yes, Travis CI works on private and public projects!

Lets add Travis to our repos!

We will show you how to add Travis CI to a repo without a package.

If you have a package look at one of these other tutorials: https://docs.travis-ci.com/user/tutorial/ https://GitHub.com/lcolladotor/r-travis https://GitHub.com/craigcitro/r-travis/wiki https://neuroconductor.org/tutorials/getting_ready_for_submission

Adding Travis CI to a package can be a tad easier/faster with the right tools.

How do we do this? step 1: sign up/sign in to travis-ci

How do we do this? step2: activate GitHub repos

Organization repo activation

How do we do this? step 3: create a .travis.yml file

Commit and push to GitHub!!

For more details on what to include see here and here.

Our .travis.yml file for our repo that doesn’t have a package

Our DESCRIPTION file

In our case we are adding travis to repos that are not packages
But we still need to have a description file with info about our dependencies, authors, etc. even if just placeholders

Add GitHub package dependencies

Manually add a field called “Remotes” specifying where the package is on GitHub

Add Travis badge

Go to the desired activated repository where you added .travis.yml and/or DESCRIPTION files
Click the build gray button
Select Markdown format
Copy and paste the result into your README file

Trouble shooting

If your repo fails, you can modify your files and then run the test again.
Look at your errors to see what went wrong.

If Travis didn’t seem to run a build - check requests for more information.

pkgdown

pkgdown allows you to create a website of your repo
Here is an example: https://crunch.io/r/crplyr/

Go to GitHub repo settings and select the desired branch as source

Create _pkgdown.yml and if you haven’t yet and a .Rbuildignore file

Build and check your website

Commit and push all your changes!
Your website URL is the one listed in your GitHub settings
For more info check here.

Alternative Faster Method

You can also create only the DESCRIPTION file manually, then use the usethis package to create the other necessary files

library(usethis)
usethis::use_readme_rmd() 
# if you only have an README.md file
# this will also add the travis badge
# make sure you update the .md and .Rmd files!
usethis::use_travis() 
# this will create the .travis.yml file
# this will also pull up https://travis-ci.org to allow you activate this repo easily
usethis::use_pkgdown() 
# this will create .Rbuildignore and _pkdown.yml files

Additional Info

The wikipedia page has additional information on Travis CI in general.
This link will tell you more about how Travis CI works.
Remember you can use the usethis package to easily use pkgdown and travis for a package. This did not work as easily in our case as we were adding Travis CI and pkgdown to repos without a package. Here is a great tutorial.
Here is a list of common build problems.