This repository is structured as a standard R package following the conventions outlined in the Writing R extensions manual. A few additional files are provided that are not part of the built R package and are listed in
.Rbuildignore, such as
.travis.yml, which is used for continuous testing and integration.
All code for this package is found in
R/, (except compiled source code, if used, which is in
/src). All functions should be thoroughly documented with
roxygen2 notation; see Documentation.
Any new feature or bug-fix should include a unit-test demonstrating the change. Unit tests follow the
testthat framework with files in
tests/testthat. Please make sure that the testing suite passes before issuing a pull request. This can be done by running
check() from the
devtools package, which will also check for consistent documentation, etc.
This package uses the travis continuous testing mechanism for R to ensure that the test suite is run on each push to Github. An icon at the top of the README.md indicates whether or not the tests are currently passing.
All of the function documentation is generated automatically. Please do not edit any of the documentation files in
man/ or the
NAMESPACE. Instead, construct the appropriate roxygen2 documentation in the function files in
R/ themselves. The documentation is then generated by running the
document() function from the
devtools package. Please consult the Advanced R programming guide if this workflow is unfamiliar to you. Note that functions should include examples in the documentation. Please use
\dontrun for examples that take more than a few seconds to execute or require an internet connection.
Likewise, the README.md file in the base directory should not be edited directly. This file is created automatically from code that runs the examples shown, helping to ensure that they are functioning as advertised and consistent with the package README vignette. Instead, edit the
README.Rmd source file in
manuscripts and run
make to build the README.
The manuscript files are built using the dynamic documentation tool
knitr from the
.Rmd versions of the file. Please do not edit the
.md versions since such files are built automatically. The
.md versions are built for viewing on Github, and take advantage of Github’s rendering and display of text-based diffs. The
.md files should then be generated using the
Makefile provided, which will also handle details such as Github-compatible syntax highlighting and the embedding of images.
Makefile will also generate a pdf version of the manuscript using pandoc and the appropriate LaTeX templates.
Text should be hard-wrapped at less than 80 characters width when possible. This allows git to better track real changes to the files and impoves the display of line-based diffs. For this reason, also avoid re-wrapping text frequently, or changing line end encodings, etc.
Embedding images: Image generation is handled by the markdown file, which will embed online png images published to imgur for the
.md output, and vector pdf graphics for the
Citations: Citations should be added to the
.Rmd file using pandoc markdown notation, with the corresponding bibtex entries added to
citations.bib. Citations can also be added as a standard markdown link.
Caching To avoid rerunning potentially slow R code embedded in the mansucript simply to view changes to the text, results from running the code are cached in
cache (see the knitr documentation for details on how caching is used). Run
make clean to erase the cache and clear your workspace. Recall that the Makefile will only rerun the relevant command if the source file has changed. Consequently, changes to to the package functions themselves will not automatically cause make to recompile the manuscript.