Following on from my post about the principles behind using travis-ci to commit to a gh-pages I wanted to follow-up with how I tackled my “intermediate” use case.


Posts in this series

  1. Automated documentation hosting on github via Travis-CI
  2. Auto-deploying documentation: multiple R vignettes
  3. Auto-deploying documentation: FASTER!
  4. Auto-deploying documentation: Rtraining
  5. Auto-deploying documentation: better change tracking of artefacts

Multiple vignettes

In my original post I show how I pushed the tfsR vignette to gh-pages, which involved copying it and renaming it to index.html.

Unfortunately, this wouldn’t work if I had multiple vignettes that I wanted to be accessible online.

Requirements

  • An index.html file
  • A way of extracting any number of html files from the vignette folder

index.html

The easiest thing to do is create an index.Rmd vignette.

I used my README content inside mine since this should contain an overview of your package already. I then inserted relative URLs to other vignettes at sensible locations.

See the vignette [Presentation components](presentation.html) for more info

If you wanted navigation from “sub-vignettes” you could simply point to the index.html file

Multiple files

The base code from Robert, that I utilised in my tfsR project had a hardcoded copy and rename of a single vignette to the index file. With multiple files it would soon become wearisome to hard code all the files in. For limited cognitive effort, I turned the copy statement into a loop based on the loop Robert uses for unzipping the package.

The loop is restricted to the docs folder and any html files within it. The simple loop is the primary reason for having an index.Rmd file, as that file ensures there is a destination for landing on stephlocke.github.io/optiRum

#!/bin/bash

rm -rf out || exit 0;
mkdir out;

GH_REPO="@github.com/stephlocke/optiRum.git"

FULL_REPO="https://$GH_TOKEN$GH_REPO"

for files in '*.tar.gz'; do
tar xfz $files
done

cd out
git init
git config user.name "stephs-travis"
git config user.email "travis"

for files in '../optiRum/inst/doc/*.html'; do
cp $files .
done

git add .
git commit -m "deployed to github pages"
git push --force --quiet $FULL_REPO master:gh-pages

Putting it all together

When this push file and vignettes get committed and pushed to Travis, the build process will loop through all the generated vignettes (after the package successfully builds) and pushes them into the gh-pages branch. This in turn presents the documentation on the https://[CONTAINER].github.io/[REPO] URL.

For optiRum this would be: stephlocke.github.io/optiRum/

Travis-CI build & autodeploy
Travis-CI build & autodeploy

Where next?

My “advanced” use case is publishing a lot of files both standalone and compiled. These aren’t currently stored as vignettes so it’s going to be interesting to tackle this, but will form a useful basis for anyone who wants to build a webpage from some analysis they’ve written in R.

Auto-deploying documentation: multiple R vignettes

What do you think?