packagedocs

# R output pre blocks are styled by default to indicate output
knitr::opts_chunk$set(comment = NA, eval = FALSE)

# shorthand for rd_link() - see ?packagedocs::rd_link for more information
rdl <- function(x) packagedocs::rd_link(deparse(substitute(x)))

packagedocs

packagedocs provides a mechanism for simple generation and automated deployment nice-looking online R package documentation that plugs into the traditional R package vignette system.

Features

Some features of this package include:

Quick Start

Adding packagedocs documentation to a package is quite straightforward.

Initializing Vignettes

Given an R package directory with documented functions, you can initialize your vignettes from within the package's directory with:

# in current package directory
packagedocs::init_vignettes()

This will create three files in your package's vignettes directory: docs.Rmd, rd.Rmd, and rd_index.yaml. You can read more about the latter two files in the "Function Reference Customization" section below, but the main file of interest is vignettes/docs.Rmd.

Building Vignettes

The docs.Rmd file is the home webpage for your package's documentation. The main content has very little structure, allowing you to insert any rmarkdown formatted document. (Just like this one!). The docs.Rmd file is a great place to show off long examples that regular function documentation just cannot do justice.

packagedocs::build_vignettes()

This manually builds vignettes and places them by default in a directory _gh-pages. You can view the pages in this directory to see what your rendered documentation looks like. This function also generates vignette files placed in inst/docs that redirect to the location where you will host the pages.

You can push the contents of this directory to a custom website location where you would like to host your documentation. If you do this, look at the redirect: option in the header yaml of your .Rmd files to make sure the redirects are pointing the correct location.

A much more convenient option, however, is to configure your packagedocs to be delpoyed automatically by the TravisCI build every time you make a package commit to Github.

TravisCI Deployment

To initialize automatic documentation builds from TravisCI, you need to do the following:

  1. Get a github API key and make it available as an environment variable GITHUB_PAT. This can be done by visiting https://github.com/settings/tokens. The minimal scope to select is "public_repo". github pat
  2. Install the TravisCI Ruby Gem (and Ruby if it isn't installed). On most MacOS and Linux systems, Ruby is already installed. On Windows, a good option for Ruby is RubyInstaller. Once you have Ruby, you need to install the travis Ruby gem: bash gem install travis There appears to be an R package that will make this process easier in the future.
  3. Make sure your repository is activated in TravisCI by visiting https://travis-ci.org/profile.
  4. Run: r packagedocs::use_travis() This will set things appropriately in your .travis.yml file such that future commits will build the documentation and push it to the gh-pages branch of your repository.

Note that if you go the use_travis() route, you never need to run packagedocs::build_vignettes() locally other than as a method to check the vignette output prior to deploying, and once to generate the vignette redirects.

You are now all set up.

Function Reference Customization

When you initialize your packagedocs vignettes, files are generated that provide a default rendering of the function reference, which is a listing of all documented functions in the package. The files created that are related to the function reference are rd.Rmd and rd_index.yaml.

rd.Rmd is a shell file that will be filled with contents as specified in rd_index.yaml. It is okay to not touch this file at all, but if you'd like you can add some header content to this document.

rd_index.yaml is a yaml file that specifies the layout of function documentation that will be populated in rd.Rmd.

Editing rd_index.yaml

rd_index.yaml has two main sections: knitr and sections. The knitr section allows you to specify a list of knitr chunk options. These options are the default options for all topics. They may be overwritten in each topic for different behavior

The sections partion of rd_index.yaml allows you to specify the grouping and ordering of documentation topics. It contains a list of section and topics pairs. Initially, the section pairs in the rd_index.yaml file are auto-generated according to the keywords used in the package documentation. All functions that do not have a keyword will be placed in the last section. internal keyword functions will not be added automatically. It is okay to rename, remove, rearrange, or repeat the sections and topics!

A topic may be a single character string. This will be upgraded at run time. The following example will produce the same topic:

- my_function
-
  title: my_function
  file: my_function.Rd

The following topic object fields will be understood by packagedocs:

The topics below will all produce the same information:

- my_function
-
  title: my_function
-
  file: my_function.Rd
-
  title: my_function
  file: my_function.Rd

You can look at examples of rd_index.yaml files here and here for an idea of what is possible.

Keeping Topics Up to Date

As you are developing your package, you are bound to add, remove, or rename functions. To keep your rd_index.yaml file up to date, there is a convenience function:

packagedocs::check_rd_index()

Which will tell you both what topics are missing in your rd_index.yaml and what topics specified in rd_index.yaml no longer exist.

Additional Notes

Opinions

It is worth noting a few opinions that are baked into this package. To make this package simple, we had to make some judgements and sacrifice some flexibility. Some of the assumptions this package is based on are discussed here.

First, with this package your vignette is a single R Markdown document. If you like the idea of multiple vignettes, think of each individual vignette as a section in this master R markdown document. Personally, when packages have multiple vignettes, I find it difficult to know which ones are relevant and in what order I should look at them. With a single master vignette, there is a better complete narrative but still the ability to break things into natural sections. You do have the ability to add other vignettes (see below) and even link into them in your packagedocs vignettes if you'd like.

Second, I am a huge proponent of only storing minimal code that is needed to support a package on github. Repositories quickly become bloated when generating and re-generating binary or difficult-to-diff files like raster images or large htmlwidget blobs. Aditionally, compiling all of the necessary components into two self contained vignettes often makes the package too large to submit to CRAN without issues. Therefore, packagedocs takes the approach of creating html vignettes that are submitted to CRAN that automatically redirect to the gh-pages of the github repository of the R package. This allows for documentation that directly matches the latest master branch while not over inflating the package that is submitted to CRAN. Only your vignette sources (vignettes/docs.Rmd, etc.) are checked in to github, but the resulting generated pages are deployed in a separate branch, gh-pages,

More on Vignettes

packagedocs creates two forms of vignettes: html redirect vignettes that are submitted to CRAN and full html vignettes that are placed in the gh-pages of your github repo. We refer to them as 'CRAN vignettes' and 'gh-pages vignettes' respectively.

Vignette Engines

There is only one packagedocs vignette engine: packagedocs::redirect. This engine requires an .Rmd file with the key redirect in the yaml header of the .Rmd file. It will produce an html vignette that automatically redirects to the website provided.

Mixing Vignette Engines

Package docs may be built along side other vignette engines, such as knitr. To include other vignette engines, set your VignetteBuilder line in the DESCRIPTION file to be, for example, VignetteBuilder: packagedocs,knitr. When the regular vignette build process occurs, the non-packagedocs vignettes will be built like normal, and the packagedocs vignettes will produce html redirects to the gh-pages vignettes on github. r rdl(packagedocs::build_vignettes()) and r rdl(packagedocs::deploy_travis()) will generate all vignette files (even non-packagedocs vignettes). Feel free to add your other vignettes to the navpills header field of docs.Rmd and rd.Rmd vignettes for in between vignette navigation.

Deploy After Success

By default, if it is the master branch and it is not a pull request, r rdl(packagedocs::deploy_travis()) will build both the CRAN vignettes and gh-pages vignettes. r rdl(deploy_travis()) will then deploy the generated _gh-pages folder (default) from Travis to the package's github repo. This forced commit will be done by "Travis CI" user (default).

Please look at r rdl(deploy_travis) for more information.

Also note that r rdl(deploy_travis) will STOMP the gh-pages every time it is called. Use this function wisely!

Dev notes

The template style for the generated pages is based on Bootstrap with several customizations. These are built using less and gulp with node.js. These are not necessary for using the package, but for development, you can do bower install after checking out the repo to get a dev environment going.

Acknowledgements

This package has gone through several iterations, and was heavily influenced and borrows from Hadley Wickham's staticdocs (now pkgdown) package.



Try the packagedocs package in your browser

Any scripts or data that you put into this service are public.

packagedocs documentation built on May 2, 2019, 4:18 a.m.