New R package: packagedocs

I’m pleased to announce the CRAN release of packagedocs which provides a mechanism for simple generation and automated deployment of nice-looking online R package documentation that plugs into the traditional R package vignette system.

You can see some examples of documentation generated with packagedocs here, here, and here.

A feature list and usage guide is provided below, but it’s probably easiest to get a feel for what the package does by watching this short screencast:

Brief History

packagedocs has been around in one form or another for quite some time and is a successor of, heavily influenced by, and borrows from Hadley Wickham’s staticdocs package. packagedocs was conceived from the desire to have a package’s vignettes and function reference all rendered into a single website with several features for convenience and utility which I’ll list below. We’ve been using it for a few years to render the documentation for packages in our DeltaRho project. Recently Barret Schloerke jumped in and revamped the package to improve and add several features and get it ready to release on CRAN. I didn’t realize until writing this post that staticdocs, which has been relatively dormant for the past few years, is now being actively revamped, and is now known as pkgdown, also worth checking out.

Features

Here are some of the features of the package:

• All documentation is generated from a single RMarkdown file, "vignettes/docs.Rmd"
• Documentation is nicely styled and responsive for mobile viewing with a collapsible auto-scrolling table of contents
• Simple Github / TravisCI hooks are provided for automatically building and deploying documentation to your github pages branch after each commit
• Once configured, by default any commits pushed to the master branch of repository https://github.com/username/reponame will have docs made automatically available at https://username.github.io/reponame
• Valid R vignettes are generated that point to the live version of the docs
• Automatic generation of all R object and function documentation, called the “function reference”
• Examples in the function reference are evaluated and the output, including graphics, is rendered inline with the documentation
• The function reference can be organized into groups with custom headings using a yaml configuration file
• A convenience function is provided for linking references to functions in your vignette directly to the associated function documentation on the generated function reference page
• Helper functions to initialize, run, and set up your docs for Github deployment
• Github pages branch is stomped on each commit to prevent repository bloat – NOTE: this is important – if you use this package, make sure you don’t care about version control history in your gh-pages branch!

Installation

From CRAN:

install.packages("packagedocs")

From Github:

devtools::install_github("hafen/packagedocs")

Usage

There are three main functions.

To initialize your packagedocs documentation:

# in current package directory
packagedocs::init_vignettes()

This will create some files in your package’s "vignettes" directory. Edit "vignettes/docs.Rmd” and to generate your vignettes, run:

packagedocs::build_vignettes()

To set up your repository to automatically build and deploy to your github pages branch on every commit:

packagedocs::use_travis()

More detail about how to use the package is found in the package’s documentation, generated of course using packagedocs!