deploy_site_github: Deploy a pkgdown site on Travis-CI to Github Pages

Description

deploy_site_github() sets up your SSH keys for deployment, builds the site with build_site(), commits the site to the gh-pages branch and then pushes the results back to GitHub. deploy_site_github() is meant only to be used by the CI system on Travis, it should not be called locally. See 'Setup' for details on setting up your repository to use this.

Usage

deploy_site_github(pkg = ".", install = TRUE,
  tarball = Sys.getenv("PKG_TARBALL", ""),
  ssh_id = Sys.getenv("id_rsa", ""),
  repo_slug = Sys.getenv("TRAVIS_REPO_SLUG", ""),
  commit_message = construct_commit_message(pkg), verbose = FALSE, ...)

Arguments

pkg

Path to package.

install

Optionally, opt-out of automatic installation. This is necessary if the package you're document is a dependency of pkgdown

tarball

The location of the built package tarball. The default Travis configuration for R packages sets PKG_TARBALL to this path.

ssh_id

The private id to use, a base64 encoded content of the private pem file. This should not be your personal private key. Instead create a new keypair specifically for deploying the site. The easiest way is to use travis::use_travis_deploy().

repo_slug

The user/repo slug for the repository.

commit_message

The commit message to be used for the commit.

verbose

Print verbose output

...

Additional arguments passed to build_site().

Setup

For a quick setup, you can use usethis::use_pkgdown_travis(). It will help you with the following detailed steps.

Add the following to your .travis.yml file.

before_cache: Rscript -e 'remotes::install_cran("pkgdown")'
deploy:
  provider: script
  script: Rscript -e 'pkgdown::deploy_site_github()'
  skip_cleanup: true

Then you will need to setup your deployment keys. The easiest way is to call travis::use_travis_deploy(). This will generate and push the necessary keys to your GitHub and Travis accounts. See the travis package website for more details.
Next, make sure that a gh-pages branch exists. The simplest way to do so is to run the following git commands locally:
```
git checkout --orphan gh-pages
git rm -rf .
git commit --allow-empty -m 'Initial gh-pages commit'
git push origin gh-pages
git checkout master
```
We recommend doing this outside of RStudio (with the project closed) as from RStudio's perspective you end up deleting all the files and then re-creating them.
If you're using a custom CNAME, make sure you have set the url in _pkgdown.yaml:
```
url: http://pkgdown.r-lib.org
```