gaborcsardi/Pkgdown deploy from Travis.md

## Pkgdown deploy from Travis.md

      
    Raw
  

              Pkgdown deploy from Travis.md
            
          
    Run usethis::use_pkgdown_travis()

❯ usethis::use_pkgdown_travis()
✔ Setting active project to '/Users/gaborcsardi/works/ps'
✔ Adding 'docs/' to '.gitignore'
● Set up deploy keys by running `travis::use_travis_deploy()`
● Insert the following code in '.travis.yml'
  before_cache: Rscript -e 'remotes::install_cran("pkgdown")'
  deploy:
    provider: script
    script: Rscript -e 'pkgdown::deploy_site_github()'
    skip_cleanup: true
  [Copied to clipboard]
This adds /docs to .gitignore and tells you two other steps you
need to do. Our setup here is a bit more complicated, but this is a good
start.
Set up the .travis.yml file

The suggested config will probably work, but I want to use a custom
pkgdown branch, and also deploy for git tags. I tend to use this config:
matrix:
  include:
    - r: 3.2
    - r: 3.3
    - r: 3.4
    - r: 3.5
    - r: release
      env: R_CODECOV=true
      before_cache: Rscript -e 'remotes::install_github("r-lib/pkgdown@fix/examples-dontshow")'
      deploy:
        provider: script
        script: Rscript -e 'pkgdown::deploy_site_github()'
        skip_cleanup: true
        on:
          all_branches: true
          condition: '"$TRAVIS_BRANCH" == "pkgdown-travis" || -n "$TRAVIS_TAG"'
    - r: devel
    - os: osx
      osx_image: xcode9.3 #High Sierra
    - os: osx
      osx_image: xcode8.3 #Sierra
We want to deploy the dev version on every push to GitHub, and also
the released versions that correspond to tags. The condition line above
makes sure that we deploy from the selected branch, and also for tags.
Initially you might want to set the branch (like pkgdown-travis here),
to deploy from to a different one, so you don't need to experiment in the
master branch. Once it is working, you can change it to master.
You probably do not need this custom pkgdown version, and you are fine
with 'remotes::install_cran("pkgdown") as usethis suggested above.
Only the r: release build is interesting for pkgdown, you don't need to
add the other R versions and OSes.
Setting up the _pkgdown.yml file

Make sure you have
destination: docs

development:
  mode: auto
in _pkgdown.yml. Other destination and development entries should
be removed, if you had a different setup before.
Setting up deployment on Travis

This is supposed to be simple via travis::use_travis_deploy() (the
travis package is at https://github.com/ropenscilabs/travis). But that has
never worked for me, I am not sure why. We can follow its code manually,
though, and run, from R:
key <- openssl::rsa_keygen()
pub_key <- travis:::get_public_key(key)
private_key <- travis:::encode_private_key(key)
Now go to the 'Settings' Travis page of your repo (e.g.
https://travis-ci.org/r-lib/ps/settings) and add the string in
private_key as an environment variable, for all branches. Its name
should be id_rsa. Do not display its value in the logs.
We'll need this private key a bit later, so save it now.
Now go to the GitHub repo of the package to set up the deploy key there.
E.g. at https://github.com/r-lib/ps/settings/keys
Click on 'Add deploy key', the title can be 'pkgdown from Travis' and the
key should be the output of
openssl::write_ssh(pub_key)
Make sure you allow write access.
Trying to deploy

Now remove the /docs directory from your repo. I suggest you create a
new branch, e.g. pkgdown-travis. Make sure that you configure deployment
for this branch in .travis.yml, see the example Travis yaml above.
Then push all changes to GitHub.
Travis will start building the new branch. You can cancel all but one
builds in the build matrix, just keep the R-release one, that'll do the
deployment.
If everything is OK, Travis deploys the pkgdown site for the dev version
of the package. You can look at the files in the gh-pages branch, e.g.
for the ps package this is at https://github.com/r-lib/ps/tree/gh-pages
You should see a dev directory and in it the pkgdown website.
Deploying the released version

We still need to deploy the released version. There are various ways to
do this, maybe the easiest is to do it from your computer, as you cannot
go back in time and change the Travis config of the package at the time
of the last release. (Alternatively, you could create a git branch from the
last release tag and update the Travis and pkgdown config there, and then
let Travis build your pkgdown web site.)
Check out the tag of the latest release from git, e.g. for ps:
git tag
git checkout v1.3.0

Then (temporarily) update the _pkgdown.yml file, to keep the dev version
in /dev and deploy the released version in /. As above, add:
destination: docs

development:
  mode: auto
We'll deploy using pkgdown::deploy_site_github(), and this needs a
tarball of the package, so let's build that first, from R:
devtools::build()
We'll also need the private key for the deployment, in the id_rsa
environment variable:
Sys.setenv(id_rsa = private_key)
Ready to deploy. You'll need to provide the repo slug as well, this is
detected on Travis, but not here. E.g.
pkgdown::deploy_site_github(
  tarball = "../ps_1.3.0.tar.gz",
  repo_slug = "r-lib/ps"
)
Now look at the gh-pages branch on GitHub, to make sure that it
has both the released and the dev version of the package.
E.g. at https://github.com/r-lib/ps/tree/gh-pages
You should see a bunch of files and directories, and again the similar
structure in the dev directory.
Now you can go to the setting page of the repo, e.g.
https://github.com/r-lib/ps/settings and set GitHub Pages to the
gh-pages branch.
Double check that the web site is properly deployed. E.g. for the ps
package, the released version is at https://ps.r-lib.org/ and the
dev version it is at https://ps.r-lib.org/dev/
Cleanup and merge to master

Now clean up the changes we made in the detached HEAD of the git repo,
and go back to our deployment branch:
git checkout -- .
git checkout pkgdown-travis

Update the Travis config to deploy from the master branch, like this,
(see full config above):
        on:
          all_branches: true
          condition: '"$TRAVIS_BRANCH" == "master" || -n "$TRAVIS_TAG"'

You can remove the all_branches line if you like. I prefer to keep it,
just in case I want to deploy from another branch in the future. I would
probably forget to add it back then.
Push the pkgdown-travis branch to GitHub, create a pull request for it
and merge it. Once it is merged, Travis should deploy the dev version of
the pkgdown site again.