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
- Automated documentation hosting on github via Travis-CI
- Auto-deploying documentation: multiple R vignettes
- Auto-deploying documentation: FASTER!
- Auto-deploying documentation: Rtraining
- Auto-deploying documentation: better change tracking of artefacts
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.
- An index.html file
- A way of extracting any number of html files from the vignette folder
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
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
rm -rf out || exit 0;
for files in '*.tar.gz'; do
tar xfz $files
git config user.name "stephs-travis"
git config user.email "travis"
for files in '../optiRum/inst/doc/*.html'; do
cp $files .
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
For optiRum this would be: stephlocke.github.io/optiRum/
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.