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:
- 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.
- 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}. - Check out ‘gh-pages’ and from that branch, run:
staticdocs::build_site(site_path='.') - 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!)
- 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:
| docs: | |
| Rscript -e "devtools::document(roclets=c('rd', 'collate', 'namespace', 'vignette'))" | |
| gh-pages: | |
| 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 |
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:
