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:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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:
pleiotropy 