Repository structure
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.
Code
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.
Testing
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.
Documentation
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.
Manuscript
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.
The 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 .pdf manuscript.
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.