R package docs + github.io

Ever wish you had a painless way to generate spiffy online documentation for your R package, a la ggplot2? Now you can, using github’s free project site hosting and hadley’s staticdocs package. Here’s how:

  1. Make some nice documentation for your project, ideally using Roxygen and devtools::document(). Follow the instructions at http://r-pkgs.had.co.nz/man.html.
  2. Create a new git branch for your project named ‘gh-pages’. Github recognizes this as a special branch name, so an index.html file here will be rendered and visible at http://{your_github_username}.github.io/{project_name}.
  3. Check out ‘gh-pages’ and from that branch, run: staticdocs::build_site(site_path='.')
  4. Watch as staticdocs creates a beautiful web page for your project. Add all the files it generates to git, commit and push it (remember- stay in the gh-pages branch!)
  5. Visit your new site at the URL in #2.

The next step is to keep it updated as you develop your package. To facilitate this, I’ve written a small Makefile:

Rscript -e "devtools::document(roclets=c('rd', 'collate', 'namespace', 'vignette'))"
git checkout gh-pages
git merge master -X theirs -m "merge master"
site:docs gh-pages
Rscript -e "staticdocs::build_site(site_path='.', launch=FALSE)"
git commit -am 'updated docs'
git checkout master
update: site
git push
git checkout gh-pages
git push
git checkout master
view raw Makefile hosted with ❤ by GitHub

Now, whenever you make a change to your package that you want reflected in the docs/site, just run make update and it will rebuild the docs, switch to the gh-pages branch, rebuild the site, then push both master and gh-pages branches to Github.

I’m using this for my random collection of R functions here:


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s