Auto-deploying documentation: multiple R vignettes
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
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
[embedGitHubContent owner="stephlocke" repo="optiRum" path=".push_gh_pages.sh"]
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/
][10]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.