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.
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.
Please ensure that any pull requests are made to the relevant branch.
Do not hesistate to open an issue in the issues tracker to raise any questions or comments about the package or these guidelines.